搜索dlevsha / nasgrate
Nasgrate 是一款控制台实用程序，允许您以一致和简单的方式组织数据库模式迁移过程。它支持 mysql、mssql、postgresql、oracle 和其他数据库
Requires
- php: >=5.4.0
This package is not auto-updated.
Last update: 2024-09-14 18:26:11 UTC
README
什么是 Nasgrate？
Nasgrate 是一款控制台实用程序，允许您以一致和简单的方式组织数据库模式迁移过程。它支持 mysql、mssql、postgresql、oracle 和其他数据库（您可以在 这里 找到更多信息）
主要特性
- 迁移的原生 SQL 语法
- 自动根据保存的数据库状态生成迁移（对于 MySQL 数据库，您不需要自己编写迁移，但我计划稍后添加对 PostgreSQL、MS SQL 和 Oracle 数据库的支持）。
- 友好的用户界面来查看保存的迁移
要求
Nasgrate 只支持 PHP 5.3.0 及以上版本，并且需要 PDO 扩展。
使用 Docker（推荐）
使用 Nasgrate 的最简单方法是使用 Docker。
您可以使用 Dockerfile 构建自己的容器，或者使用 Docker Hub 中的镜像
$ docker run -it --rm -v $(pwd)/data:/usr/src/nasgrate/data \ -e DATABASE_DRIVER=mysql \ -e DATABASE_HOST=host.docker.internal \ -e DATABASE_NAME=[database name] \ -e DATABASE_USER=[database user] \ -e DATABASE_PASSWORD=[database password] \ -e DATABASE_PORT=[database port] \ -e VERSION_TABLE_NAME=__migrationVersions \ -e DIR_MIGRATION=data/migrations \ -e DIR_DBSTATE=data/dbstate \ -e DEFAULT_DESCRIPTION_MESSAGE='Created by CURRENT_USER, CURRENT_DATE' \ -e CURRENT_USER=[your name] \ dlevsha/nasgrate generate MyFirstMigration
您需要更改自己的变量
$(pwd)/data 将包含您的迁移文件和当前数据库状态
您还可以使用 .env 文件（请参阅 .env.example）。在这种情况下，您可以使用一条命令
$ docker run -it --rm -v $(pwd)/data:/usr/src/nasgrate/data --env-file=.env dlevsha/nasgrate generate MyFirstMigration
请记住
- 如果您想连接到本地数据库，请使用特殊的 docker 变量
host.docker.internal（适用于 Mac 和 Windows 用户）。 - 如果您想使用
Nasgrate与您现有的 docker 网络一起（例如使用 docker-compose 创建），您需要连接到 docker 网络内部的容器。要完成此操作，首先运行docker network ls命令并找到您网络的名字。
NETWORK ID NAME DRIVER SCOPE
27feae2bb848 bridge bridge local
6ef8cb27a7fd docker_default bridge local
d2f3d581bf31 host host local
318fd5030260 none null local
例如，我在我的应用程序中使用 docker_default 网络，您需要将 --net=docker_default 参数添加到您的命令中
第二件事 - 您需要知道数据库容器的 IP 地址才能连接到它。
请运行 docker exec [您的数据库容器名称] cat /etc/hosts。通常最后一行将显示 IP 地址
127.0.0.1 localhost
::1 localhost ip6-localhost ip6-loopback
fe00::0 ip6-localnet
ff00::0 ip6-mcastprefix
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters
172.25.0.3 980280f59bd3
在我的情况下 IP 是 172.25.0.3，我的命令将是
$ docker run -it --rm -v $(pwd)/data:/usr/src/nasgrate/data \ --net=docker_default \ -e DATABASE_DRIVER=mysql \ -e DATABASE_HOST=172.25.0.3 \ -e DATABASE_NAME=[database name] \ -e DATABASE_USER=[database user] \ -e DATABASE_PASSWORD=[database password] \ -e DATABASE_PORT=[database port] \ -e VERSION_TABLE_NAME=__migrationVersions \ -e DIR_MIGRATION=data/migrations \ -e DIR_DBSTATE=data/dbstate \ -e DEFAULT_DESCRIPTION_MESSAGE='Created by CURRENT_USER, CURRENT_DATE' \ -e CURRENT_USER=[your name] \ dlevsha/nasgrate generate MyFirstMigration
您可以通过运行此行来获取当前 IP
docker exec [mysql container name] cat /etc/hosts | tail -n 1 | cut -d$'\t' -f 1
您还可以运行 bin/migration.sh 脚本（请更改其中的参数）
./migration.sh help
另一个选项是您可以通过 Web 界面查看所有事务（已执行和未执行的）。只需运行命令
$ docker run -it --rm -v $(pwd)/data:/usr/src/nasgrate/data \ -e DATABASE_DRIVER=mysql \ -e DATABASE_HOST=host.docker.internal \ -e DATABASE_NAME=[database name] \ -e DATABASE_USER=[database user] \ -e DATABASE_PASSWORD=[database password] \ -e DATABASE_PORT=[database port] \ -e VERSION_TABLE_NAME=__migrationVersions \ -e DIR_MIGRATION=data/migrations \ -e DIR_DBSTATE=data/dbstate \ -e DEFAULT_DESCRIPTION_MESSAGE='Created by CURRENT_USER, CURRENT_DATE' \ -e CURRENT_USER=[your name] \ -p 9001:9000 \ --entrypoint php \ dlevsha/nasgrate -S localhost:9000
或（如果您使用 .env 文件）
docker run -it --rm -v $(pwd)/data:/usr/src/nasgrate/data --env-file=docker/nasgrate/.env -p 9001:9000 --entrypoint php dlevsha/nasgrate -S 0.0.0.0:9000
并在浏览器中输入 https://:9001/app/。
您将看到您的迁移
安装
从 GitHub 克隆项目
$ git clone https://github.com/dlevsha/nasgrate.git
$ cd nasgrate
或使用 composer
$ composer require dlevsha/nasgrate
将 .env.example 重命名为 .env 并更改您的设置
# [Primary connection params] # possible drivers: 'mysql' - MySQL database, 'sqlsrv' - MS SQL Server and SQL Azure databases # 'mssql' - FreeTDS, 'pgsql' - PostgreSQL, 'oci' - Oracle DATABASE_DRIVER=mysql # you can use special variable 'host.docker.internal' for docker DATABASE_HOST=127.0.0.1 DATABASE_NAME=testdb DATABASE_USER=testuser DATABASE_PASSWORD=testdbpass DATABASE_PORT=3306 # [Migration params] VERSION_TABLE_NAME=__migrationVersions FILE_EXTENSION=sql DIR_MIGRATION=DIR_ROOT/data/migrations DEFAULT_DESCRIPTION_MESSAGE=Created by CURRENT_USER, CURRENT_DATE # [Database version control] DIR_DBSTATE=DIR_ROOT/data/dbstate # possible values - file / database VERSION_CONTROL_STRATEGY=file # -------------------------------------------------------------------- # This params need only if you use second database as data source # to compare database structure. Please read documentation. #[Secondary connection params] DATABASE_HOST_SECONDARY=localhost DATABASE_NAME_SECONDARY=test DATABASE_USER_SECONDARY=root DATABASE_PASSWORD_SECONDARY= DATABASE_PORT_SECONDARY=
[主连接参数] 部分描述了连接设置
DATABASE_DRIVER - 设置 PHP PDO 扩展支持的驱动之一
- mysql - MySQL 数据库
- sqlsrv - MS SQL Server 和 SQL Azure 数据库
- mssql - FreeTDS
- pgsql - PostgreSQL
- oci - Oracle
您可以在官方 PHP PDO 文档 中找到更多信息
DATABASE_HOST - 数据库主机名或 IP
DATABASE_NAME - 数据库名称
DATABASE_USER 和 DATABASE_PASSWORD - 登录和密码以访问您的数据库
DATABASE_PORT - 数据库服务器监听的端口号（如果使用标准端口则不需要）
下一部分 [迁移参数] 描述了脚本如何存储有关迁移的信息
VERSION_TABLE_NAME - 存储迁移脚本中服务信息的表名
FILE_EXTENSION - 迁移文件扩展名（默认为 sql）
DIR_MIGRATION - 脚本存储迁移文件的位置。默认情况下，它存储在 migrations 目录中。
如果您计划使用版本控制系统（例如 git）在团队成员或服务器之间共享迁移，您需要将此目录移动到您的项目文件夹并更改此路径。
例如，如果您在 /var/www/project/ 中有一个项目，并计划将迁移存储在 /var/www/project/service/scripts/migrations 目录中，您需要将 DIR_MIGRATION 修改为
DIR_MIGRATION = /var/www/project/service/scripts/migrations
DEFAULT_DESCRIPTION_MESSAGE - 每个迁移都有自己的描述。
默认情况下，消息看起来像 Created by CURRENT_USER, CURRENT_DATE，其中 CURRENT_USER 和 CURRENT_DATE 是预定义的常量，分别更改为用户名和当前日期。所以在这种情况下，这个消息变成了 Created by dlevsha, 2020-12-21 17:53:41。
下一节 [数据库版本控制] 描述了版本控制设置。此脚本的最强大功能是跟踪数据库更改并自动创建包含所有迁移之间数据库更改的 diff 文件。
VERSION_CONTROL_STRATEGY - 描述您用于存储数据库更改的策略。有两个可能的值 - file 和 database。
如果您有两个数据库（例如 prod 和 test），并且您想生成描述数据库之间差异的 diff 文件，您的选择将是 database，并且您需要填写下一节 [辅助连接参数]，它描述了到参考数据库的连接设置。
或者，您可以设置 file 值，脚本将自动在创建迁移时保存数据库状态（在这种情况下，您不需要填写 [辅助连接参数] 部分）。
您可以通过简单地运行以下命令来检查您的设置
$ php bin/nasgrate
您将看到描述基本命令的帮助页面
Nasgrate is a console utility that let you organise database schema migration process at a consistent and easy way.
It supports mysql, mssql, postgresql, oracle (you can find informaton here https://php.ac.cn/manual/en/pdo.drivers.php)
Usage:
php nasgrate [command] [options]
Command:
status - displays migration status
generate - creates new migration (migration file)
diff - save current database state and create migration with database schema diff
up:show - displays (but not executes) SQL-query, executed by migration update
down:show - displays (but not executes) SQL-query, executed by migration revert
up - executes migration update
down - executes migration revert
help - shows this help page
如果您使用 Linux 或 MacOS，您可以为 nasgrate 脚本设置方便性
进入控制台并运行
$ chmod +x bin/nasgrate
现在，您可以通过简单地键入以下内容来运行 Nasgrate
$ ./bin/nasgrate
让我们检查您的数据库连接设置
$ ./bin/nasgrate status
如果一切正常，您将看到
Last Migration ID: no migrations
Available Migrations: No actual migrations
如果您有连接问题，您将看到错误描述。例如
DATABASE ERROR :: SQLSTATE[HY000] [1049] Unknown database 'test2'
文档
创建迁移
每次创建迁移时，您都会创建一个至少包含两个部分的 .sql 文件：-- UP -- 和 -- DOWN --。
-- UP -- 部分包含用于更新现有数据库模式的 SQL 查询。例如
CREATE TABLE test ( id int(11) unsigned NOT NULL AUTO_INCREMENT, PRIMARY KEY (id) ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
-- DOWN -- 部分包含用于撤销数据库模式的 SQL 查询。例如
DROP TABLE test
让我们创建我们的第一个迁移
$ ./bin/nasgrate generate CreateTestMigration
并将显示
Generate new migration ID: 20200821112753_CreateTestMigration
Please edit file: /migrations/20200821112753_CreateTestMigration.sql
默认情况下，迁移将被放置在 migrations 目录中。您可以在 .environment 文件中通过修改 DIR_MIGRATION 参数来更改此位置。
如果您仔细查看，您会发现迁移 ID 是一个时间戳
20200821112753 -> 2020-08-21 11:27:53
创建的文件看起来像
-- Skip: no -- Name: Test -- Date: 01.12.2020 20:28:08 -- Description: Created by dlevsha, 2020-12-01 20:28:08 -- UP -- -- DOWN --
Skip: - 如果迁移需要被跳过。可能的值 yes|no。默认：no。有时您可能需要因任何原因跳过某些迁移。您可以通过将 Skip: 设置为 yes 来做到这一点。
Name: - 您的迁移名称
Date: - 文件创建的日期
Description: - 描述当前迁移
-- UP -- 和 -- DOWN -- 部分包含 SQL 表达式。您可以添加任意多的 SQL 查询。每个 SQL 查询都需要在新行上。每个 -- UP -- 部分的 SQL 查询都需要在 -- DOWN -- 部分有一个对应的 SQL 查询。
例如
-- Skip: no -- Name: Test -- Date: 01.12.2020 20:28:08 -- Description: The first migration. Created by dlevsha, 2020-12-01 20:28:08 -- UP -- CREATE TABLE test ( id int(11) unsigned NOT NULL AUTO_INCREMENT, PRIMARY KEY (id) ) ENGINE=InnoDB DEFAULT CHARSET=utf8; CREATE TABLE test2 ( id int(11) unsigned NOT NULL AUTO_INCREMENT, PRIMARY KEY (id) ) ENGINE=InnoDB DEFAULT CHARSET=utf8; -- DOWN -- DROP TABLE test; DROP TABLE test2;
自动创建迁移（数据库模式 diff）
您可以自动创建数据库模式差异，因此不需要描述数据库中的更改。
如果您不知道什么是数据库模式，请阅读这篇StackOverflow回答：[什么是数据库模式的目的](http://stackoverflow.com/questions/2674222/what-is-purpose-of-database-schema)。
每次创建新的迁移时，Nasgrate都会将当前的数据库模式状态保存到dbstate目录下的一个特殊文件中。该文件包含您数据库模式的快照，作为PHP序列化数组（表、行名称和类型、索引等）。
当您稍后更改数据库模式时，您可以将其与保存的状态进行比较，并自动创建包含所有数据库更改的新迁移。
另一种选择是，如果您有两个数据库（例如prod和test），您在test数据库中进行更改，并希望创建包含所有更改的新迁移，脚本可以自动完成此操作。
您可以使用您喜欢的数据库工具来修改数据库模式（例如Sequel Pro或phpMyAdmin），无需记住自上次迁移以来在数据库中更改了什么。
默认情况下，脚本使用file策略来跟踪数据库中的更改。如果您想使用其中一个作为标准来比较两个数据库中的更改，请将.environment文件中的VERSION_CONTROL_STRATEGY更改为database，并填写[Secondary connection params]部分。
让我给您举个例子
假设您使用Sequel Pro在数据库中添加了一个新表
运行
$ ./bin/nasgrate diff AddNewTable
然后它会显示（以我的情况为例）
Generate new migration ID: 20201223133618
Please edit file: /migrations/20201223133618_AddNewTable.sql
This migration marked as executed
当您查看20201223133618_AddNewTable.sql时，您会看到该文件已经包含-- UP --和-- DOWN --部分以及SQL查询。
-- Skip: no -- Name: AddNewTable -- Date: 23.12.2020 13:36:18 -- Description: Created by dlevsha, 2020-12-23 13:36:18 -- UP -- CREATE TABLE `test` ( `id` int(11) unsigned NOT NULL auto_increment, `name` varchar(200) DEFAULT NULL , PRIMARY KEY (`id`) ) ENGINE=InnoDB AUTO_INCREMENT=1 DEFAULT CHARSET=utf8; -- DOWN -- DROP TABLE IF EXISTS `test`;
假设您决定使用程序将name字段更改为VARCHAR(255)并为name字段添加索引。
运行
$ ./bin/nasgrate generate ChangeMyTestTable diff
显示
Generate new migration ID: 20201223135246
Please edit file: /migrations/20201223135246_ChangeMyTestTable.sql
This migration marked as executed
然后它会自动创建
-- Skip: no -- Name: ChangeMyTestTable -- Date: 23.12.2020 13:52:46 -- Description: Created by dlevsha, 2020-12-23 13:52:46 -- UP -- ALTER TABLE `test` CHANGE `name` `name` varchar(255) DEFAULT NULL; ALTER TABLE `test` ADD KEY `name` (`name`); -- DOWN -- ALTER TABLE `test` CHANGE `name` `name` varchar(200) DEFAULT NULL; ALTER TABLE `test` DROP KEY `name`;
查看迁移列表
在我们运行第一个迁移之前，让我们查看迁移中的查询
$ ./bin/nasgrate up:show
并将显示
Migration :: 20200821112753_CreateTestMigration
Description: The first migration. Created by dlevsha, 2020-12-01 20:28:08
CREATE TABLE test (
id int(11) unsigned NOT NULL AUTO_INCREMENT,
PRIMARY KEY (id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8
CREATE TABLE test2 (
id int(11) unsigned NOT NULL AUTO_INCREMENT,
PRIMARY KEY (id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8
我们可以看到在迁移过程中将执行的所有查询。
另一个选项是您可以通过 Web 界面查看所有事务（已执行和未执行的）。只需运行命令
php -S localhost:9000
在脚本目录中，并在浏览器中输入https://:9000/app/。
您将看到您的迁移
更新数据库模式（运行迁移）
如果一切正常，让我们运行迁移。
./bin/nasgrate up
并将显示
Migration :: 20200821112753_CreateTestMigration
CREATE TABLE test (
id int(11) unsigned NOT NULL AUTO_INCREMENT,
PRIMARY KEY (id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8
CREATE TABLE test2 (
id int(11) unsigned NOT NULL AUTO_INCREMENT,
PRIMARY KEY (id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8
... complete
如果您查看数据库，您将看到三个表。
__migrationVersions
test
test2
__migrationVersions是由迁移脚本创建的服务表。它包含已执行的迁移ID。如果您想更改该表的名称，请编辑.environment文件中的VERSION_TABLE_NAME常量。永远不要删除此表，否则您将丢失迁移信息。
test和test2是通过迁移过程创建的表。
如果您想在某个迁移之前更新数据库模式，您需要将此迁移ID作为参数设置。
$ ./bin/nasgrate up:run 20200821132420
还原数据库模式
如果出现问题并且您想回滚更改，您需要使用还原过程。在运行此更新之前，您需要知道要将还原数据库模式过程应用于哪个迁移ID。
您可以通过运行以下命令显示数据库中的所有迁移ID
$ ./bin/nasgrate list
或使用上述描述的Web界面，它将显示
Migration list:
- [26.08.2020 19:39:39] 20200826193939_CreateFirstMigration - new
- [26.08.2020 19:30:33] 20200826193033_New_Table_Test - executed
您可以看到数据库中有两个迁移。迁移20200821112753已经执行，20200826193939_CreateFirstMigration尚未执行。
让我们假设您想还原20200821112753_CreateFirstMigration迁移。
$ ./bin/nasgrate down:show 20200821112753
或
$ ./bin/nasgrate down:show 20200821112753_CreateFirstMigration
并将显示
Migration :: 20200821112753_CreateFirstMigration
Description: The first migration. Created by dlevsha, 2020-08-21 11:27:53
DROP TABLE test
DROP TABLE test2
让我们运行还原过程
$ ./bin/nasgrate down:run 20200821112753_CreateFirstMigration
并将显示
Migration :: 20200821112753_CreateFirstMigration
DROP TABLE test
DROP TABLE test2
... complete
如果您查看数据库，您会看到test和test2表已被删除。
再次运行list命令
$ ./bin/nasgrate list
并将显示
Migration list:
- [26.08.2020 19:39:39] 20200826193939_CreateFirstMigration - new
- [26.08.2020 19:30:33] 20200826193033_New_Table_Test - new
许可证
版权所有 (c) 2021，Levsha Dmitry
本软件按“原样”提供，不提供任何形式的质量保证，包括但不限于适用性、特定用途的适用性和非侵权性保证。在任何情况下，作者或版权所有者不对任何索赔、损害或其他责任承担责任，无论这些责任是源于合同、侵权或其他原因，以及与软件或软件的使用或其他交易有关。