数据库结构文档的生成利器

灰太狼 2022-12-18 13:54 129阅读 0赞

之前我们每次的数据库变更，都会增量更新我们的数据库文档，如下所示，便于从文档中了解数据库结构，

![format_png][]

但是自从我们开始使用自研的数据库变更管控平台，每次变更都会记录到系统中，因此不再手动更新这个文档。可最近同事因为项目需求，需要一个最新的数据库文档，这可有些为难了，难道要回溯每次变更，手工加到这个文档中？

其实不然，这个问题，可能有很多技术解决方式，例如用PowerDesigner，可以反向生成数据库文档，可参考《[PowerDesigner逆向工程导出pdm][PowerDesigner_pdm]》。还可以自己写个程序，读取user\_tables、user\_indexes、user\_constraints等视图，构建一个数据库文档，曾经为了比对两个数据库结构，写过一个生成pdf格式的程序，列出table、index、constraint等的不同，用的就是这种。

无意中从git上找到了一个契合此需求的项目，叫做screw，他是一个数据库表结构文档生成工具。

![format_png 1][]

作者的解释，是不是和我们的日常状态非常相像？

> 关于数据库表结构文档状态：要么没有、要么有、但都是手写、后期运维开发，需要手动进行维护到文档中，很是繁琐、如果忘记一次维护、就会给以后工作造成很多困扰、无形中制造了很多坑留给自己和后人。
> 
> 关于名字，想一个太难了，好在我这个聪明的小脑瓜灵感一现，怎么突出它的小，但重要呢？从小就学过雷锋的螺丝钉精神，摘自雷锋日记：虽然是细小的螺丝钉，是个细微的小齿轮，然而如果缺了它，那整个的机器就无法运转了，慢说是缺了它，即使是一枚小螺丝钉没拧紧，一个小齿轮略有破损，也要使机器的运转发生故障的...，感觉自己写的这个工具，很有这意味，虽然很小、但是开发中缺了它还不行，于是便起名为screw（螺丝钉）。
> 
> https://github.com/pingfangushi/screw

他的特点很鲜明，

1. 简洁、轻量、设计良好。代码量很少，从如下示例，可以体会一下。

2. 多数据库支持。目前支持MySQL、MariaDB、TIDB、Oracle、SqlServer 、PostgreSQL、Cache DB，在开发中的，包括H2、DB2、HSQL 、SQLite、瀚高、达梦、虚谷、人大金仓，可以看到，不仅有主流商业数据库，还支持很多国产数据库。

3. 多种格式文档。目前支持html格式、word格式、md格式。

4. 灵活扩展。可以自行选择导出的数据库对象。

5. 支持自定义模板。可以根据需求，定制自己的数据库导出逻辑。

不多说了，直接上代码，创建一个maven工程，首先要在pom中引入依赖，

<dependency>
        <groupId>cn.smallbun.screw</groupId>
        <artifactId>screw-core</artifactId>
        <version>${lastVersion}</version>
     </dependency>
     <dependency>
        <groupId>com.zaxxer</groupId>
        <artifactId>HikariCP</artifactId>
        <version>3.4.5</version>
    </dependency>
    //需要连接的数据库driver

接下来可以参照这个，定制自己的逻辑，有几点可以说下，

1. 示例用的Oracle，可以改成其他的数据库连接。

2. 可以使用ignore\*方法过滤不需要导出的表或者指定需要导出的表，支持完整表名、前缀、后缀等形式。

package com.swagger.Swagger;
    
    
    import java.util.ArrayList;
    
    
    import com.zaxxer.hikari.HikariDataSource;
    
    
    import cn.smallbun.screw.core.Configuration;
    import cn.smallbun.screw.core.engine.EngineConfig;
    import cn.smallbun.screw.core.engine.EngineFileType;
    import cn.smallbun.screw.core.engine.EngineTemplateType;
    import cn.smallbun.screw.core.execute.DocumentationExecute;
    import cn.smallbun.screw.core.process.ProcessConfig;
    
    
    public class ScrewApplicationTest {
        public static void main(String args[]) {
            new ScrewApplicationTest().documentGeneration();
        }
    
    
        void documentGeneration() {
    
    
            //配置 - 数据源
            HikariDataSource ds = new HikariDataSource();
            ds.setJdbcUrl("jdbc:oracle:thin:@//x.x.x.x:1523/user");
            ds.setUsername("user");
            ds.setPassword("password");
            ds.setDriverClassName("oracle.jdbc.driver.OracleDriver");
            ds.setSchema("user");
            
            //配置 - 输出文件
            String fileOutputDir = "D:\\doc";
            EngineConfig engineConfig = EngineConfig.builder()
                    //生成文件路径
                    .fileOutputDir(fileOutputDir)
                    //打开目录
                    .openOutputDir(true)
                    //文件类型
                    .fileType(EngineFileType.WORD)
                    //生成模板实现
                    .produceType(EngineTemplateType.freemarker)
                    //自定义文件名称
                    .fileName("test_file")
                    .build();
    
    
            //配置 - 读取哪些数据表
            ArrayList<String> ignoreTableName = new ArrayList<>();
            ignoreTableName.add("test_user");
            ArrayList<String> ignorePrefix = new ArrayList<>();
            ignorePrefix.add("test_");
            ArrayList<String> ignoreSuffix = new ArrayList<>();
            ignoreSuffix.add("_test");
            ArrayList<String> tablePrefix = new ArrayList<>();
            tablePrefix.add("T_");
            ProcessConfig processConfig = ProcessConfig.builder()
                    //指定生成逻辑、当存在指定表、指定表前缀、指定表后缀时，将生成指定表，其余表不生成、并跳过忽略表配置
                    //根据名称指定表生成
    //                .designatedTableName(new ArrayList<>())
                    //根据表前缀生成
                    .designatedTablePrefix(tablePrefix)
                    //根据表后缀生成
                    .designatedTableSuffix(new ArrayList<>())
                    //忽略表名
                    .ignoreTableName(ignoreTableName)
                    //忽略表前缀
                    .ignoreTablePrefix(ignorePrefix)
                    //忽略表后缀
                    .ignoreTableSuffix(ignoreSuffix)
                    .build();
            Configuration config = Configuration.builder()
                    //版本
                    .version("1.0.0")
                    //描述
                    .description("DB Schema Doc")
                    //数据源
                    .dataSource(ds)
                    //生成配置
                    .engineConfig(engineConfig)
                    //生成配置
                    .produceConfig(processConfig)
                    .build();
    
    
            //执行生成
            System.out.println("start");
            new DocumentationExecute(config).execute();
            System.out.println("end");
        }
    }

忽略网络因素，执行起来的速度还是很快的，格式很清晰。

word格式，

![format_png 2][]

html格式，支持超链接，

![format_png 3][]

md格式，

![format_png 4][]

正如作者所说，这个工具，很有意味，虽然很小，但是开发中缺了他还不行，这就是技术的意义所在，解决我们日常的点点滴滴，实现工作生活的价值。

**近期的热文：**

《[主键约束索引的奇葩现象][Link 1]》

《[如何判断应用系统性能好不好？][Link 2]》

《[Oracle Cloud创建19c数据库][Oracle Cloud_19c]》

《[DATE类型的“小陷阱”][DATE]》

《[SQL工具集-格式化结果的SQL][SQL_-_SQL]》

《[聊聊数据库范式》][Link 3]

《[如何捕获问题SQL解决过度CPU消耗的问题][SQL_CPU]》

《[如何查看JVM运行的堆内存情况][JVM]》

《[打造国产技术产品的必要性][Link 4]》

《[Oracle删除字段的方式和风险，你都了解么？][Oracle]》

《[登录缓慢的诡异问题][Link 5]》

《[从70万字SRE神作提炼出的7千字精华文章][70_SRE_7]》

《[公众号600篇文章分类和索引][600]》

[format_png]: /images/20221122/85ae21be29a34f34b9d6592d62c472b6.png
[PowerDesigner_pdm]: http://mp.weixin.qq.com/s?__biz=MzI2NzM1OTM4OA%3D%3D&chksm=ea814c89ddf6c59f2256f6257fca67092592a87bdf27b13e3ac012a2a80c4d11d5d2151ca7a8&idx=1&mid=2247485818&scene=21&sn=9e7b4c63748b2f9ab90aa6be6e7df0a8#wechat_redirect
[format_png 1]: /images/20221122/8763798aa8654fb282f7e9b98216a558.png
[format_png 2]: /images/20221122/3bfede210883414c9e6c1b86358535b8.png
[format_png 3]: /images/20221122/5d48ecde0e8f450db2a116478cc73387.png
[format_png 4]: /images/20221122/e603ae076a6c4e8bad44814b684f984d.png
[Link 1]: http://mp.weixin.qq.com/s?__biz=MzI2NzM1OTM4OA%3D%3D&chksm=ea815a52ddf6d34410fc367c116948a693d98005f6f43ffd9d0468a0af83e4e60c6af3d3045e&idx=1&mid=2247491489&scene=21&sn=f2cc824ff4a7148dc8289d03eb8e7418#wechat_redirect
[Link 2]: http://mp.weixin.qq.com/s?__biz=MzI2NzM1OTM4OA%3D%3D&chksm=ea815ad4ddf6d3c28b6bc547fe08a3de87e06d8c3292a6cc9bdffc7fc5f7d432263637d86231&idx=1&mid=2247491367&scene=21&sn=89f5263257059b2c7f61be001bc27b94#wechat_redirect
[Oracle Cloud_19c]: http://mp.weixin.qq.com/s?__biz=MzI2NzM1OTM4OA%3D%3D&chksm=ea815ad1ddf6d3c71da6d160381513bc2cb57b4d1b801bfde274c999abae90fadaa4fb27c14c&idx=1&mid=2247491362&scene=21&sn=0aeaf1f06a566c5e34ce258cfe5ef8f2#wechat_redirect
[DATE]: http://mp.weixin.qq.com/s?__biz=MzI2NzM1OTM4OA%3D%3D&chksm=ea815b06ddf6d21009d16b5dd491e3e62fcb22bd45c2fff61c7fb01b78e21248ed99050a0191&idx=1&mid=2247491317&scene=21&sn=ecdd579f838a26303eb3ba35ad98c87f#wechat_redirect
[SQL_-_SQL]: http://mp.weixin.qq.com/s?__biz=MzI2NzM1OTM4OA%3D%3D&chksm=ea815b02ddf6d214ff8098c44d2f1aabacb383ae1fb4e25a94db4ac0bfa4fa8c8e65610cec94&idx=1&mid=2247491313&scene=21&sn=8ee15fea049d85c2534c2bbfad4eaab8#wechat_redirect
[Link 3]: http://mp.weixin.qq.com/s?__biz=MzI2NzM1OTM4OA%3D%3D&chksm=ea815b24ddf6d232f8395bbf2ee5dcec7f71c5c63ede0630d34a21f363ba02f77559801d2b3a&idx=1&mid=2247491287&scene=21&sn=7327002ce4b56f72a84a09bd04bdafd6#wechat_redirect
[SQL_CPU]: http://mp.weixin.qq.com/s?__biz=MzI2NzM1OTM4OA%3D%3D&chksm=ea815b6addf6d27c0f85b9b84c237e4ca93f497fe293c31877990cef9259c6ab8450745b31be&idx=1&mid=2247491225&scene=21&sn=ac866f3d0bbba602e31aa53ca880b74f#wechat_redirect
[JVM]: http://mp.weixin.qq.com/s?__biz=MzI2NzM1OTM4OA%3D%3D&chksm=ea815b74ddf6d2621f3b547a49d4b6c8025612fb1ab0892928365b881ad2f76f01206ed68e45&idx=1&mid=2247491207&scene=21&sn=11ad7551928df895633f9b73f103eb0e#wechat_redirect
[Link 4]: http://mp.weixin.qq.com/s?__biz=MzI2NzM1OTM4OA%3D%3D&chksm=ea81588bddf6d19d016604aedd9ae6d523f5dcd74d1223d304a6c114d0e5d186b90381a3a5ba&idx=1&mid=2247490936&scene=21&sn=6d21bb9d94ad29ea7865a95b8e848b96#wechat_redirect
[Oracle]: http://mp.weixin.qq.com/s?__biz=MzI2NzM1OTM4OA%3D%3D&chksm=ea815939ddf6d02f97942e6dd5b5c60e60cd732d31c893f8879244f66d7d914b9f23fe7fc207&idx=1&mid=2247490762&scene=21&sn=67f5fdf567297ab86db77a57162f7a6a#wechat_redirect
[Link 5]: http://mp.weixin.qq.com/s?__biz=MzI2NzM1OTM4OA%3D%3D&chksm=ea815955ddf6d0434a80b00ba0e31ba96198814d630a9a255ec7b427a210ab01ad5bba685038&idx=1&mid=2247490726&scene=21&sn=f8836d3e25f6496fab88258526f048a9#wechat_redirect
[70_SRE_7]: http://mp.weixin.qq.com/s?__biz=MzI2NzM1OTM4OA%3D%3D&chksm=ea815e73ddf6d76569914615095c7e5efc66c9fa603d18dbad3c6370d75b718ab01fdc6e9459&idx=1&mid=2247490432&scene=21&sn=b0ffda7d19d9d36dc646f67734531684#wechat_redirect
[600]: http://mp.weixin.qq.com/s?__biz=MzI2NzM1OTM4OA%3D%3D&chksm=ea815fa3ddf6d6b521f9a1fccaeaf2b2ed2b547c3102b18c51397ef670985f477ee102d76fe8&idx=1&mid=2247490128&scene=21&sn=3e9b7f11a1bf04b4f302830fcdbed57d#wechat_redirect