README

Ruckusing 是一个用 PHP5 编写的框架，用于生成和管理“数据库迁移”。数据库迁移是声明性文件，代表数据库在特定时间点的状态（其表、列、索引等）。通过使用数据库迁移，多个开发者可以共同工作在同一个应用上，并确保应用在所有远程开发者机器上保持一致状态。

该框架的灵感来自 Ruby on Rails 内置的迁移系统。任何熟悉 RoR 迁移的开发者都会感到非常熟悉。

入门 & 文档

请参阅 Wiki 了解支持的迁移方法和如何入门的完整文档。

支持的数据库

• Postgres
• MySQL
• Sqlite

特性

• 便携性：描述要创建的表、列、索引等的迁移文件本身是用纯 PHP5 编写的，然后在运行时转换为适当的 SQL。这允许用户通过单一套迁移文件（假设存在相应的适配器）透明地支持任何 RDBMS。

• 类似 "rake" 的基本任务支持。该框架有一个“任务”的概念（实际上，框架的主要关注点是迁移，它只是一个普通的任务），这是一个实现了接口的 PHP5 类。可以自由编写任务，只要它们遵循特定的命名约定并实现了特定的接口，框架就会自动注册它们并允许执行。

• 能够向上或向下移动到特定的迁移状态。

• 生成骨架迁移文件的代码生成器。

• 支持基于模块的迁移目录，可以从指定的模块目录生成/运行迁移文件。

• 内置对基本任务的支持，如初始化数据库模式信息表（db:setup）、请求当前版本（db:version）和导出当前模式（db:schema）。

限制

• PHP 5.2+ 是硬性要求。该框架广泛使用了 PHP5 的面向对象特性。没有计划使框架向后兼容。

配置

• 将 /path/to/ruckusing-migrations/config/database.inc.php 复制到 /path/to/mycodebase/ruckusing.conf.php 并更新 development 键以包含您的数据库凭据

type 是 pgsql、mysql 或 sqlite 之一，具体取决于您的数据库，以及 migrations_dir、db_dir、log_dir、ruckusing_base 路径。

• 如果您想使用模块迁移目录，请编辑 /path/to/mycodebase/ruckusing.conf.php 并更新 migrations_dir 如下所示：array('default' => '/default/path', 'module_name' => '/module/migration/path') 路径。

• 将 /path/to/ruckusing-migrations/ruckus.php 复制到 /path/to/mycodebase/ruckus.php。

自定义任务

默认启用了 lib/Task 中的所有任务。如果您想实现自定义任务，则可以在覆盖的 ruckusing.conf.php 中的 tasks_dir 键中指定您的任务目录。

# ruckusing.conf.php

return array(
 /* ... snip ... */,
 'tasks_dir' => RUCKUSING_WORKING_BASE . '/custom_tasks'
);

生成骨架迁移文件

从代码库的顶级目录运行

$ php ruckus.php db:generate create_users_table

Created OK
Created migration: 20121112163653_CreateUsersTable.php

模块迁移目录示例

$ php ruckus.php db:generate create_items_table module=module_name

Created OK
Created migration: 20121112163653_CreateItemsTable.php

生成的文件位于 migrations 目录下。打开该文件，你会看到它看起来像这样

class CreateUsersTable extends Ruckusing_Migration_Base {

	public function up() {

	}//up()

	public function down() {

	}//down()
}

以下所有方法都应在 up() 和 down() 方法中实现。

环境

您可以通过命令行参数 ENV 来切换环境。默认环境是 development。

要指定附加环境，请将其添加到 ruckusing.conf.php 中的 db 键下。

使用不同环境运行

$ ENV=test php db:migrate

运行迁移

运行所有挂起的迁移

$ php ruckus.php db:migrate

回滚最新迁移

$ php ruckus.php db:migrate VERSION=-1

回滚到特定迁移（在要回滚的迁移文件名中指定时间戳）

$ php ruckus.php db:migrate VERSION=20121114001742

可用的迁移方法概述

可用的方法如下（以下为简要列表，详细用法见下文）

数据库级别操作

• create_database
• drop_database

表级别操作

• create_table
• drop_table
• rename_table

列级别操作

• add_column
• remove_column
• rename_column
• change_column
• add_timestamps

索引级别操作

• add_index
• remove_index

查询执行

• execute
• select_one
• select_all

数据库级别操作

这里有两组数据库级别操作，分别是 create_database 和 drop_database。在这个高度上操纵数据库的迁移很少使用。

创建新的数据库

这个命令有点无用了，因为通常你会在一个现有的数据库上运行迁移（使用你传统的 RDMBS 创建方法创建和设置）。然而，如果你想从一个迁移中创建另一个数据库，这个方法可用

方法调用： create_database

参数 name：新数据库的名称

示例

    $this->create_database("my_project");

删除数据库

要完全删除数据库及其所有表（以及数据）！

方法调用： drop_database

参数 name：现有数据库的名称

示例

    $this->drop_database("my_project");

这个方法可能是所有方法中最复杂的，但也是使用最广泛的方法之一。

方法调用： create_table

参数

name：新表的名称

options：创建新表时可选的关联数组

支持的选项键/值对是

id：布尔值 - 框架是否应该自动生成主键。对于 MySQL，该列将称为 id，类型为整数，并自动递增。

options：表示最终参数的字符串，该参数将逐字传递给创建表的命令尾部。通常这用于指定 MySQL 的存储引擎，例如 'options' => 'Engine=InnoDB'

假设 最终此方法委托给适当的 RDMBS 适配器，MySQL 适配器对表的结构的假设很重要。

表级别操作

数据库迁移框架提供了创建、删除和重命名表的高级设施。

创建表

对 $this->create_table(...) 的调用实际上返回一个 TableDefinition 对象。框架的这个方法是少数几个实际返回结果供用户交互的方法之一。

创建新表的步骤如下

• 使用名称和任何可选选项创建表，并将返回值存储以供以后使用

    $users = $this->create_table("users");

• 向表定义中添加列

    $users->column("first_name", "string");
    $users->column("last_name", "string");

• 调用 finish() 实际上使用定义及其列创建表

    $users->finish();

默认情况下，表类型将与数据库默认类型相同。要指定不同的表类型（例如 InnoDB），将 options 键传递到 $options 数组中，例如

示例 A： 创建一个名为 users 的新 InnoDB 表。

    $this->create_table('users', array('options' => 'Engine=InnoDB'));

• 此命令还假定您想要一个id列。此列不需要指定，它将自动生成，除非通过$options数组中的id键明确告知不要生成。

示例B：创建一个名为users的新表，但不要自动创建主键。

    $this->create_table('users', array('id' => false));

主键列将创建为具有属性int(11) unsigned auto_increment。

示例C：指定名为'guid'的自定义主键

    $t = $this->create_table('users', array('id' => false, 'options' => 'Engine=InnoDB'));
    $t->column('guid', 'string', array('primary_key' => true, 'limit' => 64));
    $t->finish();

删除表

可以通过使用drop_table方法调用删除表。正如预期的那样，删除表也会删除其所有列和索引。

方法调用： drop_table

参数： table_name：要删除的表名。

示例

   $this->drop_table("users");

重命名表

可以使用rename_table方法重命名表。

方法调用： rename_table

参数： table_name：现有表名。new_name：新表名。

示例

   // rename from "users" to "people"
   $this->rename_table("users", "people");

列级别操作

向表中添加新列

有关添加新列的完整文档，请参阅添加列

删除列

删除数据库列非常简单，但请注意，与该列关联的任何索引也将被删除。

方法调用： remove_column

参数： table_name：从其中删除列的表名。

column_name：要删除的列。

示例A：从users表中删除age列。

    $this->remove_column("users", "age");

重命名列

可以重命名数据库列（假设底层RDMBS/适配器支持它）。

方法调用： rename_column

参数： table_name：要重命名列的表名。

column_name：现有列名。

new_column_name：新列名。

示例A：将users表中的first_name重命名为fname

    $this->rename_column("users", "first_name", "fname");

修改现有列

可以修改现有列的类型、默认值或对NULL的支持。如果要仅重命名列，则使用rename_column方法。此方法接受列类型的通用类型以及影响列定义的选项数组。有关可用类型和选项，请参阅添加新列的文档，AddingColumns。

方法调用： change_column

参数： table_name：要修改列的表名。

column_name：要更改的列名。

type：列的期望通用类型。

options：（可选）影响列定义的关联数组。

示例A：从users表中更改first_name列的长度为128。

    $this->change_column("users", "first_name", "string", array('limit' => 128) );

添加时间戳列

我们经常需要列来标记创建时间和更新时间操作。这里有一个方便的方法，可以轻松为您生成它们。

方法调用：add_timestamps

参数： table_name：要添加列的表名。

created_name：希望创建时间列的名称，默认为created_at

updated_name：希望更新时间列的名称，默认为updated_at

示例A：向users表添加时间戳列。

    $this->add_timestamps("users");

示例B：以created和updated列名向users表添加时间戳列。

    $this->add_timestamps("users", "created", "updated");

索引级别操作

可以使用框架方法创建和删除索引。

添加新索引

方法调用: add_index

参数: table: 要添加索引的表名。

column: 要创建索引的列。如果这是一个字符串，那么它被认为是列名，索引将是一个单列索引。如果它是一个数组，那么它被认为是列名列表，索引将是一个多列索引，在指定的列上。

options: （可选）一个关联数组，用于控制索引生成。键/值对

unique: values: true 或 false。是否为该列创建唯一索引。默认为 false。

name : values: 用户定义。索引的名称。如果没有指定，将根据表名和列名生成默认名称。

已知问题/解决方案：MySQL当前对标识符名称的限制为64个字符。当使用add_index时，如果未指定索引名称，Ruckusing将根据表名和列（s）生成一个合适的名称。例如，如果有一个users表，并在username列上生成索引，则生成的索引名称将是：idx_users_username。如果尝试添加多列索引，则生成的名称可能会超过MySQL的64个字符限制。在这种情况下，Ruckusing将引发错误，建议您通过name选项参数使用自定义索引名称。请参阅示例C。

示例A: 在users表的email列上创建索引。

    $this->add_index("users", "email");

示例B: 在users表的ssn列上创建唯一索引。

    $this->add_index("users", "ssn", array('unique' => true)));

示例C: 在posts表的blog_id列上创建索引，但指定索引的特定名称。

    $this->add_index("posts", "blog_id", array('name' => 'index_on_blog_id'));

示例D: 在users表的email和ssn列上创建多列索引。

    $this->add_index("users", array('email', 'ssn') );

删除索引

很简单。如果索引是使用此方法（add_index）的兄弟方法创建的，那么只需要指定相同的方法参数（但调用remove_index）。

方法调用: remove_index

参数: table_name: 要从中删除索引的表名。

column_name: 从中删除索引的列名。

options: （可选）一个关联数组，用于控制索引删除过程。键/值对：name : values: 用户定义。要删除的索引的名称。如果没有指定，将根据表名和列名生成默认名称。如果在索引创建过程中（使用add_index方法）指定了name，则在这里也需要这样做，并指定相同的名称。否则，生成的默认名称可能不会与实际的索引名称匹配。

示例A: 从users表的email列中删除（单列）索引。

    $this->remove_index("users", "email");

示例B: 从users表的email和ssn列中删除（多列）索引。

    $this->remove_index("users", array("email", "ssn") );

示例C: 从users表的email列中删除（单列）命名的索引。

    $this->remove_index("users", "email", array('name' => "index_on_email_column") );

查询执行

可以通过一系列方法执行任意查询。

执行方法

execute()方法用于执行不返回数据的查询，例如INSERT、UPDATE或DELETE。

示例A: 根据某些条件更新所有行

    $this->execute("UPDATE foo SET name = 'bar' WHERE .... ");

返回结果的查询

对于返回结果的查询，例如SELECT查询，则根据返回的内容使用select_one或select_all。

这两个方法都返回一个关联数组，数组的每个元素本身又是另一个关联数组，包含列名及其值。

select_one() 用于查询期望获得单个结果集的情况，而 select_all() 用于所有其他情况（可能不确定将获得多少行）。

注意： 由于这些方法以原始SQL查询作为输入，它们可能无法在所有关系型数据库管理系统（RDBMS）中通用。

示例A（《select_one》）： 获取某列的总和

    $result = $this->select_one("SELECT SUM(total_price) AS total_price FROM orders");
    if($result) {
     echo "Your revenue is: " . $result['total_price'];
    }

**示例B（《select_all》）**： 获取所有行并遍历每行，执行一些操作

    $result = $this->select_all("SELECT email, first_name, last_name FROM users WHERE created_at >= SUBDATE( NOW(), INTERVAL 7 DAY)");

    if($result) {
      echo "New customers: (" . count($result) . ")\n";
      foreach($result as $row) {
        printf("(%s) %s %s\n", $row['email'], $row['first_name'], $row['last_name']);
      }
    }

测试

单元测试需要安装 phpunit：http://www.phpunit.de/manual/current/en/installation.html

运行完整的测试套件

$ vi config/database.inc.php
$ mysql -uroot -p < tests/test.sql
$ psql -Upostgres -f tests/test.sql
$ phpunit

将在 tests/unit 运行所有测试类。

运行单个测试文件

$ vi config/database.inc.php
$ mysql -uroot -p < tests/test.sql
$ phpunit tests/unit/MySQLAdapterTest.php

一些测试需要定义 mysql_test 或 pg_test 数据库配置。如果需要但未满足，测试将适当地报错。