编辑“Gallery:Alter Table教程”

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

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

相关资料：[[:Category:Gallery 2:Development|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. 在该文件中，描述新版本表与旧版本表之间变更之处。
:: 例如：此例中，我们会''添加一个新栏''至''GalleryItem''表。表的旧版本号为1.1，新版本号为1.2。
<pre>
 <?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>
</pre>

:'''注：''' 看看modules/*/classes/GalleryStorage/xml-src/A_*.xml，通过实例进行学习。
: ALTER TABLE SQL 的XML抽象并非万能的，需要多个步骤来做一些必要修改。（如2 到3 个A_..xml文件）。

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

在命令行中，输入：
<pre>
  cd modules/[your module]/classes/
  make
</pre>
: 你可能需要使用''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版本。
<pre>
	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':
</pre>

就是这样！

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

[[Category:Gallery 2:Development|Alter Table Tutorial]]