Gallery: Alter Table教程：修订间差异

2008年11月29日 (六) 16:11的版本

该教程解释Gallery2中映射表与实体表的变更方法。

在继续此教程前，你应当了解如何在Gallery2中创建表格，当然也要知道映射表和实体表究竟为何物。

对于新安装- 更新表定义

此副本涵盖了表定义的更新方法（CREATE TABLE SQL）。

映射表

打开modules/[你的模块名称]/classes/Maps.xml（不是Maps.inc）
修改映射表的定义（如通过向栏目列表添加一个新栏目）
增加表的"次"版本号1。如果之前是0，就增加为1。如果是3，则增加为4，以此类推

实体表

打开modules/[你的模块名称]/classes/GallerySomeEntity.class （如GalleryItem.class或GalleryFileSystemEntity.class）
修改实体定义，如，通过添加新成员。切记在/** */批注标记中添加必要的XML！
增加表的"次"版本号1。如果之前是0，就增加为1。如果是3，则增加为4，以此类推

对于升级 – 添加一个变更表定义

如果你想配置模块的话，就会希望使用上一个版本模块的使用者能够轻松地升级到新版本的该模块，其中一部分就是将现有表结构变更为新的定义。这是通过ALTER TABLE语句来完成的。

在Gallery2中，你无需为所有被支持的数据库系统编写ALTER TABLE SQL。你只需要编写ALTER TABLE 语句的XML描述。基于XML描述，Gallery就会为所有被支持的数据库生成必要的SQL。

1. 创建一个新文件：modules/[your module]/classes/GalleryStorage/xml-src/A_[TableName]_[old-major-version].[old-minor-version].xml （A_ 表示ALTER）

例如：GalleryFooMap版本是1.3（主号.次号，你修改了定义，而其新版本号为1.4。那么文件名就应当是A_GalleryFooMap_1.3.xml

2. In that file, describe the changes between the new table version and the old version.

例如：此例中，我们会添加一个新栏至GalleryItem表。表的旧版本号为1.1，新版本号为1.2。

 <?xml version="1.0" encoding="utf-8"?>

 <!DOCTYPE change
  SYSTEM "../../../../../lib/tools/dtd/DatabaseChangeDefinition2.0.dtd">
 <change>
  <table-name>Item</table-name>
  <schema-from>
    <schema-major>1</schema-major>
    <schema-minor>1</schema-minor>
  </schema-from>
  <schema-to>
    <schema-major>1</schema-major>
    <schema-minor>2</schema-minor>
  </schema-to>
  <add>
    <column>
      <column-name>renderer</column-name>
      <column-type>STRING</column-type>
      <column-size>MEDIUM</column-size>
    </column>
  </add>
 </change>

注：看看modules/*/classes/GalleryStorage/xml-src/A_*.xml，通过实例进行学习。

ALTER TABLE SQL 的XML抽象并非万能的，需要多个步骤来做一些必要修改。（如2 到3 个A_..xml文件）。

生成SQL

在修改了映射/实体定义并创建了一个A_[表名称]_[主号].[次号].xml文件之后，现在就该准备生成新SQL了。

在命令行中，输入：

  cd modules/[your module]/classes/
  make

你可能需要使用gmake而不是make

通过查看modules/[your module]/classes/GalleryStorage/schema.tpl确认SQL生成无误。 CREATE TABLE语句现在应能反映新的表结构了，而且也应当有一个新的ALTER TABLE语句。

对于升级 – 执行变更表代码

新安装的模块此时应能工作了。表格使用新的表结构在模块安装时就被创建了。

但对于具有旧的表结构模块的升级，你需要添加一点模块升级代码来进行指导，以执行ALTER TABLE代码。

1. 打开modules/[你的模块名称]/module.inc

2. 添加一个upgrade()函数。如，复制modules/comment/module.inc的代码来开始。

3. 在模块构建式中，增加版本号。

例如：如果之前为$this->setVersion('1.1.5');，就将其修改为$this->setVersion('1.2.0');

4. 在升级函数中，为之前版本添加一个case。

例如：如果之前的版本号为1.1.5，而新版本号为1.2.0，则添加

 case '1.1.5':

5. 在upgrade case，添加一个configureStore()呼叫来触发ALTER TABLE语句。

例如：此例中，我们GalleryFooMap 的变更表语句，由表架构1.1版本至1.2版本。

	case '1.1.5':
            global $gallery;
	    $storage =& $gallery->getStorage();
	    $ret = $storage->configureStore($this->getId(), array('GalleryFooMap:1.1'));
	    if ($ret) {
		return $ret;
	    }

	case 'end of upgrade path':

就是这样！

你可能还想要填入/复制升级代码中的数据，这都由你自己决定。

@@ 第1行： / 第1行： @@
-This tutorial explains how Map and Entity tables can be altered in Gallery 2.
+该教程解释Gallery2中映射表与实体表的变更方法。
-Before following this tutorial, you should have a basic understanding how to create your own tables in Gallery 2 and what Map and Entity tables are.
+在继续此教程前，你应当了解如何在Gallery2中创建表格，当然也要知道映射表和实体表究竟为何物。
-Related documentation: [[:Category:Gallery 2:Development|Development Documentation for Gallery 2]]
+相关资料：[[:Category:Gallery 2:Development|Gallery2的开发资料]]
-== For New Installations - Update the Table Definition ==
+== 对于新安装- 更新表定义 ==
-This section covers how to update the table definition (CREATE TABLE SQL).
+此副本涵盖了表定义的更新方法（CREATE TABLE SQL）。
-=== Map Tables ===
+=== 映射表 ===
-# Open modules/[your module]/classes/Maps.xml (not Maps.inc)
+# 打开modules/[你的模块名称]/classes/Maps.xml（不是Maps.inc）
-# Change the definition of your map table (e.g. by adding a new column to the column list)
+# 修改映射表的定义（如通过向栏目列表添加一个新栏目）
-# Increment the "minor" table version by 1. If it was 0 before, change it to 1. If it was 3 before, change it to 4. etc.
+# 增加表的"次"版本号1。如果之前是0，就增加为1。如果是3，则增加为4，以此类推
-=== Entity Tables ===
+=== 实体表 ===
-# Open modules/[your module]/classes/GallerySomeEntity.class (e.g. GalleryItem.class or GalleryFileSystemEntity.class)
+# 打开modules/[你的模块名称]/classes/GallerySomeEntity.class （如GalleryItem.class或GalleryFileSystemEntity.class）
-# Change the definition of your entity, e.g. by adding new members. Don't forget to add the necessary XML in the /** */ comment tags!
+# 修改实体定义，如，通过添加新成员。切记在/** */批注标记中添加必要的XML！
-# Increment the "minor" table version by 1. If it was 0 before, change it to 1. If it was 3 before, change it to 4. etc.
+# 增加表的"次"版本号1。如果之前是0，就增加为1。如果是3，则增加为4，以此类推
-== For Upgrades - Add An Alter Table Definition ==
+== 对于升级 – 添加一个变更表定义 ==
-If you want to deploy your module, you'll want that users of a previous version of your module can easily upgrade to the new version of your module and part thereof is altering the existing table structure to the new definition. This is done by ALTER TABLE statements.
+如果你想配置模块的话，就会希望使用上一个版本模块的使用者能够轻松地升级到新版本的该模块，其中一部分就是将现有表结构变更为新的定义。这是通过ALTER TABLE语句来完成的。
-In Gallery 2, you don't have to write your own ALTER TABLE SQL for all the supported database systems. Instead, you need to write a XML description of the ALTER TABLE statement. Based on the XML description, Gallery will then generate the necessary SQL for all supported database systems for you.
+在Gallery2中，你无需为所有被支持的数据库系统编写ALTER TABLE SQL。你只需要编写ALTER TABLE 语句的XML描述。基于XML描述，Gallery就会为所有被支持的数据库生成必要的SQL。
-:1. Create a new file at modules/[your module]/classes/GalleryStorage/xml-src/A_[TableName]_[old-major-version].[old-minor-version].xml (A_ means ALTER)
+:1. 创建一个新文件：modules/[your module]/classes/GalleryStorage/xml-src/A_[TableName]_[old-major-version].[old-minor-version].xml （A_ 表示ALTER）
-:: Example: GalleryFooMap was at version (major.minor) 1.3 and you changed the definition and its new version is 1.4. The filename should be A_GalleryFooMap_1.3.xml
+:: 例如：GalleryFooMap版本是1.3（主号.次号，你修改了定义，而其新版本号为1.4。那么文件名就应当是A_GalleryFooMap_1.3.xml
 :2. In that file, describe the changes between the new table version and the old version.
-:: Example: In this example, we are ''adding a new column'' (column name 'renderer' of type STRING MEDIUM (128 chars)) to the ''GalleryItem'' table. The old table version was 1.1 and the new version is 1.2.
+:: 例如：此例中，我们会''添加一个新栏''至''GalleryItem''表。表的旧版本号为1.1，新版本号为1.2。
 <pre>
   <?xml version="1.0" encoding="utf-8"?>
@@ 第52行： / 第52行： @@
 </pre>
-:'''Note:''' Take a look at modules/*/classes/GalleryStorage/xml-src/A_*.xml to learn by example.
+:'''注：''' 看看modules/*/classes/GalleryStorage/xml-src/A_*.xml，通过实例进行学习。
-: You can't do everything possible with our XML abstraction of ALTER TABLE SQL and some changes need to be done in multiple steps (e.g. 2 or 3 A_..xml files).
+: ALTER TABLE SQL 的XML抽象并非万能的，需要多个步骤来做一些必要修改。（如2 到3 个A_..xml文件）。
-== Generate SQL ==
+== 生成SQL ==
-After having changed the Map / Entity definition and having created an A_[table-name]_[major].[minor].xml file for upgrades, you're now ready to generate the new SQL.
+在修改了映射/实体定义并创建了一个A_[表名称]_[主号].[次号].xml文件之后，现在就该准备生成新SQL了。
-In the command line, you enter:
+在命令行中，输入：
 <pre>
    cd modules/[your module]/classes/
    make
 </pre>
-: You may need to use ''gmake'' instead of ''make''
+: 你可能需要使用''gmake''而不是''make''
-Verify that the SQL has been generated correctly by looking at modules/[your module]/classes/GalleryStorage/schema.tpl.
+通过查看modules/[your module]/classes/GalleryStorage/schema.tpl确认SQL生成无误。
-The CREATE TABLE statement should now reflect the new table structure and there should be a new ALTER TABLE statement too.
+CREATE TABLE语句现在应能反映新的表结构了，而且也应当有一个新的ALTER TABLE语句。
-== For Upgrades - Execute The Alter Table Code ==
+== 对于升级 – 执行变更表代码 ==
-New installations of your module should work fine at this point. The table is created with the new table structure at module installation time.
+新安装的模块此时应能工作了。表格使用新的表结构在模块安装时就被创建了。
-But for module upgrades from module versions with older table structures, you need to add a tiny bit of module upgrade code to instruct it when to execute the ALTER TABLE code.
+但对于具有旧的表结构模块的升级，你需要添加一点模块升级代码来进行指导，以执行ALTER TABLE代码。
-:1. Open modules/[your module]/module.inc
+:1. 打开modules/[你的模块名称]/module.inc
-:2. Add a upgrade() function if there is none already. E.g. copy code from modules/comment/module.inc to get started.
+:2. 添加一个upgrade()函数。如，复制modules/comment/module.inc的代码来开始。
-:3. In the module constructor, increment the version.
+:3. 在模块构建式中，增加版本号。
-:: Example: If it was $this->setVersion('1.1.5'); before, change it to $this->setVersion('1.2.0');
+:: 例如：如果之前为$this->setVersion('1.1.5');，就将其修改为$this->setVersion('1.2.0');
-:4. In the upgrade function, add a case for the previous version.
+:4. 在升级函数中，为之前版本添加一个case。
-:: Example: If the version was 1.1.5 before and the new version is 1.2.0, add
+:: 例如：如果之前的版本号为1.1.5，而新版本号为1.2.0，则添加
    case '1.1.5':
-:5. In your upgrade case, add a configureStore() call to trigger the ALTER TABLE statement.
+:5. 在upgrade case，添加一个configureStore()呼叫来触发ALTER TABLE语句。
-:: Example: In this example we're executing the alter table statement for GalleryFooMap from table schema version 1.1 to 1.2.
+:: 例如：此例中，我们GalleryFooMap 的变更表语句，由表架构1.1版本至1.2版本。
 <pre>
 	case '1.1.5':
@@ 第95行： / 第95行： @@
 </pre>
-That's it!
+就是这样！
-You may want to populate / copy data in your upgrade code as well. That's up to you.
+你可能还想要填入/复制升级代码中的数据，这都由你自己决定。
 [[Category:Gallery 2:Development|Alter Table Tutorial]]

WIKI使用导航

站长百科导航

站长专题