@Lenciel

Integrate schemaSpy with Sphinx build

schemaSpy

在做项目的时候,客户或者合作的部门常常问研发要“数据库设计”。在古代,瀑布式开发的第一个阶段是做架构设计和写文档,所以这样的需求一般都能被“充分满足”。而在我们现在的项目节奏和迭代速度都很快,数据库的设计在项目初期经常也在变化,如何能够比较方便的文档化这些变更?

对开发团队内部来说,我个人觉得Django的South或者是1.7之后加入的Migration里面每次变更生成的migration文件就已经足够开发人员了解底层的设计发生了什么变化。

而对外提供的文档,主要是在更高层级进行设计的沟通,所以之前我们一般是通过django-extension里面的graph_models命令来生成简单的关系图:

# Create a PNG image file called my_project_visualized.png with application grouping
$ ./manage.py graph_models -a -g -o my_project_visualized.png

效果如下:

django-extension-sample

这里的图是通过graphviz来完成的,可以看到一般的了解也足够了,但是缺点主要是:

  1. 生成的关系图比较简陋
  2. 由于是图片,一旦表比较多浏览起来并不是那么灵活

使用schemaSpy

于是在新的项目里面本座选用了看起来更美好的schemaSpy,因为:

  1. 轻量但支持多种数据库(jdbc),针对Django的test/stage/prod环境都可以使用
  2. 功能非常强大,并且有命令行支持,可以集成到CI

不过和大多数开源工具一样,它的文档也是乱糟糟的。以开发环境为例,我们一般使用sqlite作为数据库,要在Mac下面成功运行schemaSpy连接sqlite,你需要:

  1. 下载最新的SchemaSpy jar包
  2. 下载最新的Xerial Sqlite JDBC jarsqlite-xerial.jar
  3. 创建一个sqlite-xerial.properties文件,内容如下:
# Use -dp to override.
description=SQLite
connectionSpec=jdbc:sqlite:<db>
db=database name
driver=org.sqlite.JDBC
#you may need to put the full path to the driver depending on your setup
driverPath=sqlite-jdbc-3.8.7.jar
selectTablesSql=.tables
  1. 运行命令:
java -jar schemaSpy_5.0.0.jar -t  sqlite-xerial.properties -db ../src/default.db  -o django-testbird -sso

会看到有warning,但是无需惊慌,我看了一下是schemaSpy的作者没有正确的处理[]

集成到Sphinx

因为我们的项目都使用了Jenkins自动启动Sphinx来生成文档,所以理想的情况当然是:

  1. 修改Django下某个app的models.py
  2. make migration生成migrations文件
  3. 代码提交并push到gitlab
  4. Jenkins调用django management command完成表结构的变更
  5. Jenkins自动更新包括数据库设计在内的文档

要实现#5,最简单的办法是在Sphinx文档目录下的Makefile里面加一个target

dbv:
    java -jar schemaSpy_5.0.0.jar -t sqlite-xerial.properties -db ../src/default.db  -o _db_virtualization/django-testproject -sso

然后在Jenkins调用的脚本里面加上make dbv就可以了。

How I use Evernote

其实之前也分享了一些自己使用的工具,只是更偏重研发。今天跟另外一个也用Evernote的同事交流了一下我怎么用Evernote,效果还可以,干脆在年关将至的时候分享一下自己日常使用的一些软件。

从Evernote开始。

进入互联网时代,特别是移动互联网时代之后,获取各种信息变得越来越便捷了,如何管理这些纷繁的信息也自热而然成为一个需求。大多数像我一样的老人,一开始是用digdelicious这样基于书签的工具。因为在有google和云笔记本这种东西之前,大家都是靠装满了各种书签的”收藏夹”过活(年轻人是不能理解重装机器没有备份收藏夹的伤痛的)。

但是这样的系统坏处就是它是”lazy-loading”的,你每次需要的时候,需要打开网页(如果你还能想起叫啥并且它们还健在的话)去找原来看到的信息,所以更适合用来做reference的整理。对于你真正希望梳理成自己知识的东西,更好的选择当然是使用所谓的PIM(Personal Information Management)软件。

我2010年开始用Evernote,一直用的是免费版(空间对我来说够了,而且我也没有太多分享的需求),它的优点包括:

  • 多(liang)种(you)多(bu)样(qi)的记录手段
  • 丰富灵活的管理方式
  • 跨平台跨设备云同步
  • 颜色还真水嫩啊

但时间久了,Evernote里面的东西也多了起来。每次要找点儿什么基本上都是靠全文搜索,一直到我读到Michael Hyatt的这篇文章

简单来说,大多数人用Evernote都是以”笔记本(Notebook)”为容器来整理Note的。Michael的意思是Notebook和Tag比有这么几个弱点:

  1. Notebook数量有限制(个人版250,企业版5000),Tag可以有100000个
  2. Notebook和Note是一对一的,Tag和Note是多对一的
  3. Notebook只能建一级嵌套(基本上就是说可以Group一下),Tag可以无限制多层级嵌套

所以他推荐了使用Tag来进行Note的管理。

除此之外他那篇文章里面还有个很重要的概念就是所有的文章先收到一个叫Inbox的Notebook,处理了之后再放到Cabinet里面去。这其实非常像我们使用邮箱:所有的邮件先被邮件系统放到Inbox,然后我们处理了之后打上相应的标签(ToDo, Later, …),最后归档。

所以我现在是这么Evernote的。

首先,把Notebook减少到两个,一个是Inbox,一个是Archive。它们的作用跟我们的邮箱里面的Inbox和Archive是完全一样的。

然后,如果在网上看到觉得还挺有意思的文章,就用Evernote收录到Inbox

注意,收录的时候我都习惯用下面的选项,去掉所有的样式:

Evernote Clipper

最后,在整理Inbox的时候,对每篇文章做一些修修剪剪,给Note加上合适的Tag,然后放到Archive。可以看到,因为tag可以嵌套和展开,要找到自己感兴趣的文章变得容易很多:

Evernote Clipper