db-migrator 1.1.0

设置

dbmigrator 需要一些设置才能运行

• --migrations-directory: 包含所有迁移的目录

• --context: 包含迁移目录入口点的Python包名称

• --db-connection-string: 连接到postgres的数据库主机、端口、名称、用户、密码等

• --config: 包含上述设置的配置文件

查看 dbmigrator -h.

要使用入口点设置迁移目录，在 mymodule setup.py

setup(
    ...
    entry_points={
        'dbmigrator': [
            'migrations_directory = mymodule.main:migrations_directory',
            ],
        },
    )

重要提示: 在运行 dbmigrator 之前，首先运行 python setup.py develop 或 python setup.py install，以便从 setup.py 中获取设置。

然后在 mymodule/main.py

import os

migrations_directory = '{}/sql/migrations'.format(
    os.path.abspath(os.path.dirname(__file__)))

或者

import os

def migrations_directory():
    return '{}/sql/migrations'.format(
        os.path.abspath(os.path.dirname(__file__)))

或者使用配置文件，development.ini，如下所示

[app:main]
db-connection-string = postgres://dbuser@localhost/dbname

生成

在迁移目录中生成迁移脚本。

示例用法

dbmigrator generate add_id_to_users

生成一个名为 migrations/20151217170514_add_id_to_users.py 的文件，其内容为：

# Uncomment should_run if this is a repeat migration
# def should_run(cursor):
#     # TODO return True if migration should run


def up(cursor):
    # TODO migration code
    pass


def down(cursor):
    # TODO rollback code
    pass

init

初始化模式迁移表。默认情况下，假定所有迁移都已应用到数据库中。

示例用法

dbmigrator --db-connection-string='postgres://dbuser@localhost/dbname' init

可以选择手动设置数据库版本。例如，如果没有任何迁移应用到数据库中，你可以

dbmigrator --config=development.ini init --version=0

list

列出迁移版本、名称、是否已应用以及应用日期。

示例用法

$ dbmigrator --config=development.ini list
version        | name            | is applied | date applied
----------------------------------------------------------------------
20151217170514   add_id_to_users   True         2016-01-31 00:15:01.692570+01:00
20151218145832   add_karen_to_us   False*
20160107200351   blah              deferred

在“是否已应用”列中的 * 表示迁移是重复迁移。

要查看完整的迁移名称，请使用 --wide

$ dbmigrator --config=development.ini list --wide
version        | name               | is applied | date applied
----------------------------------------------------------------------
20151217170514   add_id_to_users      True         2016-01-31 00:15:01.692570+01:00
20151218145832   add_karen_to_users   False*
20160107200351   blah                 deferred

migrate

运行挂起的迁移。

例如，在迁移目录中有两个迁移

migrations/20151217170514_add_id_to_users.py:

from dbmigrator import super_user

def up(cursor):
    # TODO migration code
    pass

    # if a super user database connection is needed
    with super_user() as super_cursor:
        pass

def down(cursor):
    # TODO rollback code
    pass

和

migrations/20151218145832_add_karen_to_users.py:

def up(cursor):
    cursor.execute('ALTER TABLE users ADD COLUMN karen TEXT')

def down(cursor):
    cursor.execute('ALTER TABLE users DROP COLUMN karen')

要运行迁移

$ dbmigrator migrate
Running migration 20151217170514 add_id_to_users

Running migration 20151218145832 add_karen_to_users
---
+++
@@ -4005,21 +4005,22 @@
     first_name text,
     firstname text,
     last_name text,
     surname text,
     full_name text,
     fullname text,
     suffix text,
     title text,
     email text,
     website text,
-    is_moderated boolean
+    is_moderated boolean,
+    karen text
 );

 ALTER TABLE public.users OWNER TO rhaptos;

 --
 -- Name: abstractid; Type: DEFAULT; Schema: public; Owner: rhaptos
 --

 ALTER TABLE ONLY abstracts ALTER COLUMN abstractid SET DEFAULT nextval('abstracts_abstractid_seq'::regclass);

或要运行到特定版本的迁移

$ dbmigrator migrate version=20151217170514
Running migration 20151217170514 add_id_to_users

如果所有迁移都已运行

$ dbmigrator migrate
No pending migrations.  Database is up to date.

要编写重复迁移，确保你的迁移已定义 should_run

def should_run(cursor):
    return os.path.exists('data.txt')


def up(cursor):
    with open('data.txt') as f:
        data = f.read()
    cursor.execute('INSERT INTO table VALUES (%s)', (data,))


def down(cursor):
    pass

上述迁移将在每次调用 migrate 时运行，除非它被标记为“延迟”。如果 should_run 返回 True，则运行 up。

要编写延迟迁移，请将 @deferred 添加到 up 函数中

from dbmigrator import deferred


@deferred
def up(cursor):
    # this migration is automatically deferred

上述迁移将不会运行，除非你使用 migrate --run-deferred。

rollback

回滚迁移。

例如，在迁移目录中有两个迁移

migrations/20151217170514_add_id_to_users.py:

def up(cursor):
    # TODO migration code
    pass

def down(cursor):
    # TODO rollback code
    pass

和

migrations/20151218145832_add_karen_to_users.py:

def up(cursor):
    cursor.execute('ALTER TABLE users ADD COLUMN karen TEXT')

def down(cursor):
    cursor.execute('ALTER TABLE users DROP COLUMN karen')

确保数据库是最新的

$ dbmigrator migrate
No pending migrations.  Database is up to date.

现在回滚最后一个迁移

$ dbmigrator rollback
Rolling back migration 20151218145832 add_karen_to_users
---
+++
@@ -4005,22 +4005,21 @@
     first_name text,
     firstname text,
     last_name text,
     surname text,
     full_name text,
     fullname text,
     suffix text,
     title text,
     email text,
     website text,
-    is_moderated boolean,
-    karen text
+    is_moderated boolean
 );

 ALTER TABLE public.users OWNER TO rhaptos;

 --
 -- Name: abstractid; Type: DEFAULT; Schema: public; Owner: rhaptos
 --

 ALTER TABLE ONLY abstracts ALTER COLUMN abstractid SET DEFAULT nextval('abstracts_abstractid_seq'::regclass);

要回滚最后两个迁移

$ dbmigrator rollback --steps=2
Rolling back migration 20151218145832 add_karen_to_users
---
+++
@@ -4005,22 +4005,21 @@
     first_name text,
     firstname text,
     last_name text,
     surname text,
     full_name text,
     fullname text,
     suffix text,
     title text,
     email text,
     website text,
-    is_moderated boolean,
-    karen text
+    is_moderated boolean
 );

 ALTER TABLE public.users OWNER TO rhaptos;

 --
 -- Name: abstractid; Type: DEFAULT; Schema: public; Owner: rhaptos
 --

 ALTER TABLE ONLY abstracts ALTER COLUMN abstractid SET DEFAULT nextval('abstracts_abstractid_seq'::regclass);

Rolling back migration 20151217170514 add_id_to_users

mark

将迁移标记为已完成、未完成或延迟。

示例用法

$ dbmigrator --config=development.ini --migrations-directory=migrations/ list
name                      | is applied | date applied
----------------------------------------------------------------------
20151217170514_add_id_to_   True         2016-01-31 00:15:01.692570+01:00
20151218145832_add_karen_   False
20160107200351_blah         False

要将迁移标记为未完成

$ dbmigrator --config=development.ini --migrations-directory=migrations/ mark -f 20151217170514
Migration 20151217170514 marked as not been run

$ dbmigrator --config=development.ini --migrations-directory=migrations/ list
name                      | is applied | date applied
----------------------------------------------------------------------
20151217170514_add_id_to_   False
20151218145832_add_karen_   False
20160107200351_blah         False

要将迁移标记为已完成

$ dbmigrator --config=development.ini --migrations-directory=migrations/ mark -f 20151217170514
Migration 20151217170514 marked as completed

$ dbmigrator --config=development.ini --migrations-directory=migrations/ list
name                      | is applied | date applied
----------------------------------------------------------------------
20151217170514_add_id_to_   True         2016-06-13 16:39:58.777893+01:00
20151218145832_add_karen_   False
20160107200351_blah         False

要将迁移标记为延迟意味着在运行 migrate 或 rollback 时忽略迁移

$ dbmigrator --config=development.ini --migrations-directory=migrations/ mark -d 20151217170514
Migration 20151217170514 marked as deferred

$ dbmigrator --config=development.ini --migrations-directory=migrations/ list
name                      | is applied | date applied
----------------------------------------------------------------------
20151217170514_add_id_to_   deferred     None
20151218145832_add_karen_   False
20160107200351_blah         False

CHANGELOG

1.1.0 (2018-01-03)

• 将 db-config-ini-key 添加到 CLI 选项中

• 将 --sort（版本或已应用）添加到 dbmigrator list

• 允许 mark 接受多个时间戳

• 在运行 utils 测试之前设置 dbmigrator 设置

• 添加静音开关

• 添加无回滚迁移的测试

• 将大多数输出转换为日志

• 显式关闭所有 postgres 数据库连接

1.0.2 (2017-09-25)

• 在 should_run 附近创建一个 savepoint - 回滚到 false 以恢复数据库状态

• 将 __version__ 添加到 dbmigrator

1.0.1 (2017-09-14)

• 更新 psycopg2 所需的最小版本

1.0.0 (2017-08-24)

• 在 list 中添加“*”以指示重复迁移

• 当找不到标记迁移时引发 SystemExit

• 添加延迟迁移

• 添加重复条件迁移

• 将打印语句更改为 logger.debug

• 在安装测试包时减少测试中的噪音

• 添加回滚 CLI 测试

• 添加迁移 CLI 测试

• 添加超级用户数据库连接

• 将 logger 从 __init__.py 移动到 utils.py

• 在 .travis.yml 中将 python 3.4 更改为 3.5

0.2.0 (2016-06-24)

• 添加 psycopg2 等待回调，以便按 Ctrl-C 停止迁移

• 实现将迁移标记为延迟： mark -d

• 为 list 添加 –wide 选项以显示完整的迁移名称

• 更新 README 中的命令用法

• 向 dbmigrator 命令添加帮助信息

• 如果模式迁移不存在，使用 dbmigrator init --help 警告用户

• 添加生成迁移的 CLI 测试

0.1.4 (2016-05-12)

• 将 dbmigrator list 更改为分别列出版本和迁移名称

0.1.3 (2016-04-19)

• 将 CLI 测试分成不同的测试用例

• 将测试配置更改为使用travis数据库

• 将logger.warn更改为logger.warning

• 添加测试用例以测试CLI的verbose选项

• 添加对dbmigrator list的测试

• 添加针对多个上下文的CLI init测试用例

• 将travis和coveralls徽章添加到README中

• 将cli.main导入移动到基本测试用例

• 重构代码，以标记迁移为完成或未完成

• 添加标记迁移为完成或未完成的mark命令

• 添加对mark命令的测试

• 更新README，包含mark命令的示例用法

0.1.2 (2016-03-18)

• bug:

  修复当未提供迁移目录时list不会崩溃的问题

• 如果schema_migrations表不存在，则对list记录警告消息

• 将--verbose更改为将记录器级别设置为调试

• 添加对utils.timestamp的测试

• 添加对utils.rollback_migration的测试

• 添加对utils.run_migration的测试

• 添加对utils.get_pending_migrations的测试

• 添加对utils.get_migrations的测试

• 添加对utils.import_migration的测试

• 使dbmigrator generate生成符合PEP8的代码

• 修复dbmigrator generate迁移目录查找问题

• 添加对utils.with_cursor的测试

• 添加对utils.get_settings_from_config的测试

• 添加与测试包的集成测试

• 将PEP8添加到travis

• 为dbmigrator添加一个记录器，该记录器将写入stdout

• 将版本信息选项更改为-V

• 按文件名而不是完整路径对迁移进行排序

0.1.1 (2016-02-24)

• 如果表已存在，则停止更改schema_migrations数据

• 重写--version以使用argparse版本操作

• 添加对--version的单元测试

• 添加travis CI配置文件

• 修复默认上下文（工作目录）是字符串而不是列表的问题

0.1.0 (2016-02-12)

• 允许指定多个迁移目录/上下文

• 添加–verbose，它将打印dbmigrator使用的配置

• 使用datetime utcnow而不是now进行时间戳

• 添加--version以显示安装的db-migrator版本

0.0.7 (2016-02-10)

• 添加选项--context到dbmigrator以加载入口点

• 如果指定了配置文件但找不到，则引发错误

0.0.6 (2016-02-08)

• 修复“init”命令中缺失迁移目录的问题

0.0.5 (2016-02-08)

• 将CHANGELOG包含在分发清单中

0.0.4 (2016-02-08)

• 如果迁移目录未定义，则显示警告消息而不是错误

• 添加CHANGELOG

0.0.3 (2016-02-08)

• 如果迁移目录未定义，则返回错误

0.0.2 (2016-02-03)

• 修复README中的无效rst

• 更新setup.py描述和long_description

• 更新setup.py以包括README作为描述并修复url

• 在删除配置文件的默认值后更新README和cli

• 删除默认配置路径（development.ini）

• 添加dbmigrator list命令

• 修复dbmigrator rollback以在没有迁移可以回滚时停止

• 在初始化schema_migrations后打印消息

• 如果使用入口点，请添加运行python setup.py install的注释

• 在README中添加从setup.py入口点设置迁移目录设置的注释

• 更新README中的init和generate命令名称

• 从setup.py入口点获取设置

• 在迁移目录中删除__init__.py的生成

• 为dbmigrator init添加选项version以设置初始版本

• 将“generate_migration”命令重命名为“generate”

• 将“init_schema_migrations”命令重命名为“init”

• 更改导入迁移的方式，使其在python2中工作

• 向schema_migrations表添加“applied”时间戳

• 在生成的迁移文件顶部添加# -*- coding: utf-8 -*-

• 添加README

• 添加“rollback”命令以回滚迁移

• 添加“migrate”命令以运行挂起的迁移

• 在运行init_schema_migrations时向表中添加迁移

• 添加创建模式迁移表的命令

• 创建dbmigrator cli和“generate_migration”命令

• 创建dbmigrator Python包