A database document generation artifact

Gitee project address, you can directly go to the open source project to view (recommended)

Introduction

In enterprise-level development, we often spend time writing database table structure documents. Since we have worked in several companies, the status of database table structure documents: either there is no, or there is, but they are all handwritten, and later operation and maintenance development , it needs to be manually maintained in the document, which is very cumbersome. If you forget to maintain once, it will cause a lot of trouble for future work, and create a lot of pitfalls for yourself and future generations.

So I came up with the idea of ​​writing a plug-in tool by myself, but because I didn't have a lot of attainments in programming design in the early stage, and my ability was low, I couldn't realize my ideas well. With the increase of work experience and the continuous accumulation of knowledge, Finally, writing started in mid-March 2020.

The first edition was completed in early April, and I wanted to improve it almost open source, but due to my busy work and lack of spare time, I did not improve it. In June, due to work reasons, I frequently designed and changed the database, and I often used this plug-in written by myself, which saved a lot of money. A lot of time, many problems have been solved. In the only and not much spare time, open source preparations were made. On June 22, 2020, it was open sourced. Everyone is welcome to use, suggest, and contribute.

As for the name, it is too difficult to think of one. Fortunately, my clever little brain has a flash of inspiration. How to highlight its small but important? I have learned Lei Feng's screw spirit since I was a child, from Lei Feng's diary: Although it is a small screw, it is a tiny pinion, but if it is missing, the whole machine will not work. The small screw is not tightened, a small gear is slightly damaged, and the operation of the machine will also break down... I feel that this tool I wrote has a lot of meaning. Although it is small, it is not enough without it in the development. So it was named screw (screw).

features

• Simple, lightweight and well designed

• Multiple database support

• Documentation in various formats

• flexible expansion

• Support for custom templates

database support

• MySQL

• MariaDB

• TIDB

• Oracle

• SqlServer

• PostgreSQL

• Cache DB（2016）

• H2 (under development)

• DB2 (under development)

• HSQL (under development)

• SQLite (under development)

• Henkel (under development)

• Dameng (under development)

• Void Valley (under development)

• Renminda Jincang (under development)

Document Generation Support

• html

• word

• markdown

document screenshot

• html

• word

• 

   

• markdwon

How to use

normal way

• Introduce dependencies

<dependency>
    <groupId>cn.smallbun.screw</groupId>
    <artifactId>screw-core</artifactId>
    <version>${lastVersion}</version>
 </dependency>

• Write code

/**
 * 文档生成
 */
void documentGeneration() {
   //数据源
   HikariConfig hikariConfig = new HikariConfig();
   hikariConfig.setDriverClassName("com.mysql.cj.jdbc.Driver");
   hikariConfig.setJdbcUrl("jdbc:mysql://127.0.0.1:3306/database");
   hikariConfig.setUsername("root");
   hikariConfig.setPassword("password");
   //设置可以获取tables remarks信息
   hikariConfig.addDataSourceProperty("useInformationSchema", "true");
   hikariConfig.setMinimumIdle(2);
   hikariConfig.setMaximumPoolSize(5);
   DataSource dataSource = new HikariDataSource(hikariConfig);
   //生成配置
   EngineConfig engineConfig = EngineConfig.builder()
         //生成文件路径
         .fileOutputDir(fileOutputDir)
         //打开目录
         .openOutputDir(true)
         //文件类型
         .fileType(EngineFileType.HTML)
         //生成模板实现
         .produceType(EngineTemplateType.freemarker)
         //自定义文件名称
         .fileName("自定义文件名称").build();

   //忽略表
   ArrayList<String> ignoreTableName = new ArrayList<>();
   ignoreTableName.add("test_user");
   ignoreTableName.add("test_group");
   //忽略表前缀
   ArrayList<String> ignorePrefix = new ArrayList<>();
   ignorePrefix.add("test_");
   //忽略表后缀    
   ArrayList<String> ignoreSuffix = new ArrayList<>();
   ignoreSuffix.add("_test");
   ProcessConfig processConfig = ProcessConfig.builder()
         //指定生成逻辑、当存在指定表、指定表前缀、指定表后缀时，将生成指定表，其余表不生成、并跳过忽略表配置 
   //根据名称指定表生成
   .designatedTableName(new ArrayList<>())
   //根据表前缀生成
   .designatedTablePrefix(new ArrayList<>())
   //根据表后缀生成 
   .designatedTableSuffix(new ArrayList<>())
         //忽略表名
         .ignoreTableName(ignoreTableName)
         //忽略表前缀
         .ignoreTablePrefix(ignorePrefix)
         //忽略表后缀
         .ignoreTableSuffix(ignoreSuffix).build();
   //配置
   Configuration config = Configuration.builder()
         //版本
         .version("1.0.0")
         //描述
         .description("数据库设计文档生成")
         //数据源
         .dataSource(dataSource)
         //生成配置
         .engineConfig(engineConfig)
         //生成配置
         .produceConfig(processConfig)
         .build();
   //执行生成
   new DocumentationExecute(config).execute();
}

Maven plugin

<build>
    <plugins>
        <plugin>
            <groupId>cn.smallbun.screw</groupId>
            <artifactId>screw-maven-plugin</artifactId>
            <version>${lastVersion}</version>
            <dependencies>
                <!-- HikariCP -->
                <dependency>
                    <groupId>com.zaxxer</groupId>
                    <artifactId>HikariCP</artifactId>
                    <version>3.4.5</version>
                </dependency>
                <!--mysql driver-->
                <dependency>
                    <groupId>mysql</groupId>
                    <artifactId>mysql-connector-java</artifactId>
                    <version>8.0.20</version>
                </dependency>
            </dependencies>
            <configuration>
                <!--username-->
                <username>root</username>
                <!--password-->
                <password>password</password>
                <!--driver-->
                <driverClassName>com.mysql.cj.jdbc.Driver</driverClassName>
                <!--jdbc url-->
                <jdbcUrl>jdbc:mysql://127.0.0.1:3306/xxxx</jdbcUrl>
                <!--生成文件类型-->
                <fileType>HTML</fileType>
                <!--打开文件输出目录-->
                <openOutputDir>false</openOutputDir>
                <!--生成模板-->
                <produceType>freemarker</produceType>
                <!--文档名称 为空时:将采用[数据库名称-描述-版本号]作为文档名称-->
                <fileName>测试文档名称</fileName>
                <!--描述-->
                <description>数据库文档生成</description>
                <!--版本-->
                <version>${project.version}</version>
                <!--标题-->
                <title>数据库文档</title>
            </configuration>
            <executions>
                <execution>
                    <phase>compile</phase>
                    <goals>
                        <goal>run</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

extension module

pojo generation function

Function introduction

The pojo generation function is based on the extension module extended by screw, which is currently in the state of preliminary development. In daily development, after requirement analysis and modeling, tables are often built in the database first, followed by code development. Then the pojo generation function can help you save some repetitive labor at this stage.

Use the pojo generation function to directly generate the corresponding java pojo object according to the database. In this way, subsequent modifications and development will be very convenient.

database support

• MySQL

How to use

• Introduce dependencies

<dependency>
    <groupId>cn.smallbun.screw</groupId>
    <artifactId>screw-extension</artifactId>
    <version>${lastVersion}</version>
 </dependency>

• Write code

/**
 * pojo生成
 */
void pojoGeneration() {
    //数据源
    HikariConfig hikariConfig = new HikariConfig();
    hikariConfig.setDriverClassName("com.mysql.cj.jdbc.Driver");
    hikariConfig.setJdbcUrl("jdbc:mysql://127.0.0.1:3306/screw");
    hikariConfig.setUsername("screw");
    hikariConfig.setPassword("screw");
    //设置可以获取tables remarks信息
    hikariConfig.addDataSourceProperty("useInformationSchema", "true");
    hikariConfig.setMinimumIdle(2);
    hikariConfig.setMaximumPoolSize(5);
    DataSource dataSource = new HikariDataSource(hikariConfig);

    ProcessConfig processConfig = ProcessConfig.builder()
        //指定生成逻辑、当存在指定表、指定表前缀、指定表后缀时，将生成指定表，其余表不生成、并跳过忽略表配置
        //根据名称指定表生成
        .designatedTableName(new ArrayList<>())
        //根据表前缀生成
        .designatedTablePrefix(new ArrayList<>())
        //根据表后缀生成
        .designatedTableSuffix(new ArrayList<>()).build();

    //设置生成pojo相关配置
    PojoConfiguration config = new PojoConfiguration();
    //设置文件存放路径
    config.setPath("/cn/smallbun/screw/");
    //设置包名
    config.setPackageName("cn.smallbun.screw");
    //设置是否使用lombok
    config.setUseLombok(false);
    //设置数据源
    config.setDataSource(dataSource);
    //设置命名策略
    config.setNameStrategy(new HumpNameStrategy());
    //设置表过滤逻辑
    config.setProcessConfig(processConfig);
    //执行生成
    new PojoExecute(config).execute();
}

common problem

• Is the document garbled after generation?

  MySQL: URL added ?characterEncoding=UTF-8.

• Caused by: java.lang.NoSuchFieldError: VERSION_2_3_30？

  Check the project freemarkerdependencies. This is caused by the version being too low. Just upgrade the version 2.3.30to .

• java.lang.AbstractMethodError: oracle.jdbc.driver.T4CConnection.getSchema()Ljava/lang/String;

  This is because the oracle driver version is too low, delete or block the current driver version, add and upgrade the driver to the following version:

    <dependency>
       <groupId>com.oracle.ojdbc</groupId>
       <artifactId>ojdbc8</artifactId>
       <version>19.3.0.0</version>
    </dependency>
    <dependency>
       <groupId>cn.easyproject</groupId>
       <artifactId>orai18n</artifactId>
       <version>12.1.0.2.0</version>
    </dependency>

• MySQL database table and column fields have descriptions, but there is no description in the generated document?

  Just add the URL link useInformationSchema=true.

• java.lang.AbstractMethodError: com.mysql.jdbc.JDBC4Connection.getSchema()Ljava/lang/String;

  This is because the mysql driver version is too low, just upgrade the mysql driver version to the latest