Play 框架手册（19） – 管理数据库变化 Evolution


当使用关系数据库时，你需要去跟踪和安排数据库 schema（结构）变化，特别是有多个存储位置的情况下，你就需要更多的经验来跟踪数据的 schema 变化： 

  • 当处理团队合作进行开发时，每个人都需要知道数据库结构的变化
  • 当部署到生产服务器上时，就需要一个稳健的方式去更新数据库结构 
  • 如果在多台数据库服务器上工作时，就需要保持所有数据库结构同步

如果在 JPA 下工作，Hibernate 会自动为你处理好这些数据库变化。如果你不打算使用 JPA 或打算手工对数据库结构进行更好的调整，那么 Evolutions 将非常有用。

19.1. Evolutions 脚本

Play 使用 evolutions 脚本来跟踪你的数据库变化。这些脚本采用的是原始的 sql 语句来书写的，应该位于应用程序的 db/evolutions 目录。

第一个脚本名叫 1.sql,第二为 2.sql,以此类…

每个脚本包含了两部分：

  • Ups 部分用于描述必要的转换 
  • Downs 部分用于描述如何恢复他们

比如，查看第一个 evolution 脚本，这个脚本用于引导一个基本的应用：

# Users schema

# --- !Ups

CREATE TABLE User (
    id bigint(20) NOT NULL AUTO_INCREMENT,
    email varchar(255) NOT NULL,
    password varchar(255) NOT NULL,
    fullname varchar(255) NOT NULL,
    isAdmin boolean NOT NULL,
    PRIMARY KEY (id)
);

# --- !Downs

DROP TABLE User;

正如你看到的一样，必须在 sql 脚本里使用注释来界定 Ups 和 Downs 节。

如果在 applictaion.conf 里配置了数据库，那么 Evolutions 将被自动激活，而且 evolution scripts 将被显示出来。通过设置 evolutions.enabled 为 false 可以禁此显示脚本。比如，当测试他们自己的数据库里，你可以为测试环境设置为禁用模式。

当 evolutions 被激活后， 在 DEV 模式下，Play 将为每个请求检查数据库结构状态，或在 PROD 模式下启动应用程序时进行数据库结构状态检查。在 DEV 模式下，如果数据库结构不是最新的，一个错误页面会显示出来，它会建议你运行合适的 sql 脚本同步你的数据结构。

 

如果你同意推荐的 SQL 脚本，你可以点击‘Apply evolutions’按钮执行该建议脚本。

如果使用的是内存数据库(db=mem),并且数据库是空的情况下，Play 会自动运行所有的 evolutions 脚本。

19.2. 同步同时发生的改变 

现在让我们假定现在在同一项目中有两个开发者，A 开发者因工作需要必须创建一个新的数据库表，因此他将 2.sql evolution 脚本:

# Add Post

# --- !Ups
CREATE TABLE Post (
    id bigint(20) NOT NULL AUTO_INCREMENT,
    title varchar(255) NOT NULL,
    content text NOT NULL,
    postedAt date NOT NULL,
    author_id bigint(20) NOT NULL,
    FOREIGN KEY (author_id) REFERENCES User(id),
    PRIMARY KEY (id)
);

# --- !Downs
DROP TABLE Post;

Play 将应用这个 evolution 脚本到 A 开发者的数据库。

另外一方面，B 开发者因工作需要，必须删除 User 表。因此他也将创建 2.sql evolution 脚本：

# Update User

# --- !Ups
ALTER TABLE User ADD age INT;

# --- !Downs
ALTER TABLE User DROP age;

B 开发者结束开发工作后进行了提交（称为 Git)。现在，A 开发者在继续开发前必须合并他的同事的工作，因此他运行 git pull，但合并操作产生了一个冲突，如下：

Auto-merging db/evolutions/2.sql
CONFLICT (add/add): Merge conflict in db/evolutions/2.sql
Automatic merge failed; fix conflicts and then commit the result.

每个开发者都创建了一个 2.sql evolution 脚本。因此，A 开发者需要合并这个文件：

<<<<<<< HEAD
# Add Post

# --- !Ups
CREATE TABLE Post (
    id bigint(20) NOT NULL AUTO_INCREMENT,
    title varchar(255) NOT NULL,
    content text NOT NULL,
    postedAt date NOT NULL,
    author_id bigint(20) NOT NULL,
    FOREIGN KEY (author_id) REFERENCES User(id),
    PRIMARY KEY (id)
);

# --- !Downs
DROP TABLE Post;
=======
# Update User

# --- !Ups
ALTER TABLE User ADD age INT;

# --- !Downs
ALTER TABLE User DROP age;
>>>>>>> devB

这个合并操作其实很容易做:

# Add Post and update User

# --- !Ups
ALTER TABLE User ADD age INT;

CREATE TABLE Post (
    id bigint(20) NOT NULL AUTO_INCREMENT,
    title varchar(255) NOT NULL,
    content text NOT NULL,
    postedAt date NOT NULL,
    author_id bigint(20) NOT NULL,
    FOREIGN KEY (author_id) REFERENCES User(id),
    PRIMARY KEY (id)
);

# --- !Downs
ALTER TABLE User DROP age;

DROP TABLE Post;

这个 evolution 脚本显示为新修订 revision 2 的数据库，这个版本不同于 A 开发者之前已经应用的修订 2 版本。 

因此 Play 会察觉到这个情况，并要求 A 开发者通过首先恢复已经应用的旧的修订 2 版本来同步他的数据库，并应用新的修订 2 版本脚本：

 

19.3. 数据不一致状态 

某些时候可能会在 evolution 脚本里犯错，那么这些脚本就会失效。在这种情况下，play 将标记数据库结构为数据不一致状态，同时要求你在继续工作前手工解决这个问题。

比如，Evolution 脚本的 Ups 存在一个错误：

# Add another column to User

# --- !Ups
ALTER TABLE Userxxx ADD company varchar(255);

# --- !Downs
ALTER TABLE User DROP company;

因此，试着应用这个 evolution 将导致失败，play 将把数据库结构标记为 inconsistent:

 

现在要继续工作前，你必须解决这个不一致的问题，因此你就运行了 fixed SQL 命令:

ALTER TABLE User ADD company varchar(255);

… 之后，通过单击按钮，手工解决了这个标记的问题。

但是由于你的 evolution 脚本存在错误，你或许希望修复这个错误。因此你修改了 3.sql 脚本：

# Add another column to User

# --- !Ups
ALTER TABLE User ADD company varchar(255);

# --- !Downs
ALTER TABLE User DROP company;

Play 检测到这个新的 evolution，然后替换了之前的 3 版， 之后将运行下面的脚本：

现在所有的问题都已处理好，你又可以继续工作了。

在开发模式里，处理这样的问题非常简单，可以直接丢弃现在的开发数据库，然后再次重头申请所有的 evolutions 脚本即可。

19.4. Evolutions 命令 

在 DEV 模式里，evolutions 是交互式执行的。然而在 PROD 模式里，在运行应用程序前，你就必须使用 evolutions 命令来修订你的数据库结构。

在生产模式下如果你试着运行一个数据库不是最新版的应用程序时， 应用程序将不能启动。

~        _            _
~  _ __ | | __ _ _  _| |
~ | '_ \| |/ _' | || |_|
~ |  __/|_|\____|\__ (_)
~ |_|            |__/
~
~ play! master-localbuild, http://www.playframework.org
~ framework ID is prod
~
~ Ctrl+C to stop
~
13:33:22 INFO  ~ Starting ~/test
13:33:22 INFO  ~ Precompiling ...
13:33:24 INFO  ~ Connected to jdbc:mysql://localhost
13:33:24 WARN  ~
13:33:24 WARN  ~ Your database is not up to date.
13:33:24 WARN  ~ Use `play evolutions` command to manage database
evolutions.
13:33:24 ERROR ~

@662c6n234
Can't start in PROD mode with errors

Your database needs evolution!
An SQL script will be run on your database.

play.db.Evolutions$InvalidDatabaseRevision
     at play.db.Evolutions.checkEvolutionsState(Evolutions.java:323)
     at play.db.Evolutions.onApplicationStart(Evolutions.java:197)
     at play.Play.start(Play.java:452)
     at play.Play.init(Play.java:298)
     at play.server.Server.main(Server.java:141)

Exception in thread "main" play.db.Evolutions$InvalidDatabaseRevision
     at play.db.Evolutions.checkEvolutionsState(Evolutions.java:323)
     at play.db.Evolutions.onApplicationStart(Evolutions.java:197)
     at play.Play.start(Play.java:452)
     at play.Play.init(Play.java:298)
     at play.server.Server.main(Server.java:141)

错误消息要求你运行 play evolutions 命令：

$ play evolutions
~        _            _
~  _ __ | | __ _ _  _| |
~ | '_ \| |/ _' | || |_|
~ |  __/|_|\____|\__ (_)
~ |_|            |__/
~
~ play! master-localbuild, http://www.playframework.org
~ framework ID is gbo
~
~ Connected to jdbc:mysql://localhost
~ Application revision is 3 [15ed3f5] and Database revision is 0 [da39a3e]
~
~ Your database needs evolutions!

# ----------------------------------------------------------------------------

# --- Rev:1,Ups - 6b21167

CREATE TABLE User (
    id bigint(20) NOT NULL AUTO_INCREMENT,
    email varchar(255) NOT NULL,
    password varchar(255) NOT NULL,
    fullname varchar(255) NOT NULL,
    isAdmin boolean NOT NULL,
    PRIMARY KEY (id)
);

# --- Rev:2,Ups - 9cf7e12

ALTER TABLE User ADD age INT;
CREATE TABLE Post (
    id bigint(20) NOT NULL AUTO_INCREMENT,
    title varchar(255) NOT NULL,
    content text NOT NULL,
    postedAt date NOT NULL,
    author_id bigint(20) NOT NULL,
    FOREIGN KEY (author_id) REFERENCES User(id),
    PRIMARY KEY (id)
);
138

# --- Rev:3,Ups - 15ed3f5

ALTER TABLE User ADD company varchar(255);

# ----------------------------------------------------------------------------

~ Run `play evolutions:apply` to automatically apply this script to the db
~ or apply it yourself and mark it done using `play evolutions:markApplied`
~

如果你打算让 Play 自动为你运行 evolution，那么要使用如下命令：

$ play evolutions:apply

如果你喜欢在你的生产数据库上手工运行脚本，那么你需要告诉 play 你的数据库是最新的：

$ play evolutions:markApplied

如果在自动运行 evolution 脚本时存在错误， 在 DEV 模式下， 可以手工解决他们，之后标记数据库结构为已修正状态：

$ play evolutions:resolve

前一篇:
后一篇:

发表评论

 

2014 © Biliyu.com. ALL Rights Reserved.
鄂公网安备 42010202002526号
备案/许可证编号为：鄂ICP备14004565号