metapensiero.sphinx.patchdb 3.7

条件

该示例还显示了条件的用法，允许脚本的多个变体，例如：

.. patchdb:script:: My first script (py3)
   :description: Full example of a script
   :revision: 2
   :depends: Other script@4
   :preceeds: Yet another
   :language: python
   :conditions: python_3_x

   print("Yeah!")

:conditions:选项的值可以是单个段落，包含逗号分隔的条件列表，或者是一个项目符号列表。

作为此功能的另一个用例，以下代码段为两个不同的数据库声明了同一个表：

.. patchdb:script:: Simple table (PostgreSQL)
  :language: sql
  :mimetype: text/x-postgresql
  :conditions: postgres
  :file: postgresql/simple.sql

.. patchdb:script:: Simple table (MySQL)
  :language: sql
  :mimetype: text/x-mysql
  :conditions: mysql
  :file: mysql/simple.sql

如您所见，脚本的内容可以方便地存储在外部文件中，并且使用:mimetype:选项指定的特定方言，因此 Pygments 会正确突出显示它。

这样的条件也可以在命令行中任意定义，例如：

.. patchdb:script:: Configure for production
  :language: sql
  :conditions: PRODUCTION

  UPDATE configuration SET is_production = true

然后在这种情况下添加选项--assert PRODUCTION 。

一个条件可以被否定，前置一个！它的名字：

.. patchdb:script:: Configure for production
  :language: sql
  :conditions: !PRODUCTION

  UPDATE configuration SET is_production = false

变量

影响脚本效果的另一种方法是使用变量：脚本可能包含一个或多个使用语法{{VARNAME}}对任意变量的引用，必须在应用程序时使用--define VARNAME=VALUE命令行定义选项。或者使用语法{{name=default}}引用可以设置变量的默认值，可以从命令行覆盖。

例如，您可以使用以下脚本：

.. patchdb:script:: Create table and give read-only rights to the web user
   :language: sql

   CREATE TABLE foo (id INTEGER)
   ;;
   GRANT SELECT ON TABLE foo TO {{WEB=www}}
   ;;
   GRANT ALL ON TABLE foo TO {{ADMIN}}

要应用它，您必须指定ADMIN变量的值，例如 --define ADMIN=$USER。

变量名必须是一个标识符（即至少一个字母可能后跟字母数字或下划线），而它的值可能包含空格、字母或数字。

如果名称以ENV_ 开头，则在进程环境中查找该值。在以下示例中，用户名来自USER环境变量（必须存在），而密码来自PASSWORD环境条目，如果未设置，则来自指定的默认值：

.. patchdb:script:: Insert a default user name
   :language: sql

   INSERT INTO users (name, password) VALUES ('{{ENV_USER}}', '{{ENV_PASSWORD=password}}')

请注意，您可以使用命令行上的显式--define选项覆盖环境，例如使用--define ENV_PASSWORD=foobar。

依赖项

依赖项（即选项 :brings:、:depends:、:drops::和 :preceeds:）可能是包含逗号分隔的脚本 ID 列表的段落，例如：

.. patchdb:script:: Create master table

   CREATE TABLE some_table (id INTEGER PRIMARY KEY, tt_id INTEGER)

.. patchdb:script:: Create target table

   CREATE TABLE target_table (id INTEGER PRIMARY KEY)

.. patchdb:script:: Add foreign key to some_table
   :depends: Create master table, Create target table

   ALTER TABLE some_table
         ADD CONSTRAINT fk_master_target
             FOREIGN KEY (tt_id) REFERENCES target_table (id)

或者，它们可以作为项目符号列表输入，因此上面的最后一个脚本也可以写成：

.. patchdb:script:: Add foreign key to some_table
   :depends:
      - Create master table
      - Create target table

   ALTER TABLE some_table
         ADD CONSTRAINT fk_master_target
             FOREIGN KEY (tt_id) REFERENCES target_table (id)

使用此语法，您可以引用包含逗号的scriptid 。

与这些脚本在文档中出现的顺序无关，第三个脚本只有在前两个成功应用于数据库后才会执行。如您所见，大多数选项都是可选的：默认情况下，:language:是sql，:revision:是 1，:description:取自标题（即脚本 ID），而 :depends:和:preceeds:是空的。

仅出于说明目的，可以通过以下方式实现相同的效果：

.. patchdb:script:: Create master table
   :preceeds: Add foreign key to some_table

   CREATE TABLE some_table (id INTEGER PRIMARY KEY, tt_id INTEGER)

.. patchdb:script:: Create target table

   CREATE TABLE target_table (id INTEGER PRIMARY KEY)

.. patchdb:script:: Add foreign key to some_table
   :depends: Create target table

   ALTER TABLE some_table
         ADD CONSTRAINT fk_master_target
             FOREIGN KEY (tt_id) REFERENCES target_table (id)

错误处理

默认情况下， patchdb在无法应用一个脚本时停止。有时您可能希望放宽该规则，例如，在使用其他方法创建的数据库上进行操作时，您无法依靠特定脚本的存在来做出决定。在这种情况下，可以使用选项:onerror: ：

.. patchdb:script:: Remove obsoleted tables and functions
   :onerror: ignore

   DROP TABLE foo
   ;;
   DROP FUNCTION initialize_record_foo()

当:onerror:设置为ignore时，脚本中的每个语句都会被执行，如果发生错误，它将被忽略，patchdb会继续执行下一个语句。在像 PostgreSQL 和 SQLite 这样的优秀数据库上，即使 DDL 语句也是事务性的，每个语句都在嵌套的子事务中执行，因此后续错误不会破坏正确应用先前语句的效果。

此选项的另一个可能设置是skip：在这种情况下，每当发生错误时，整个脚本的效果都会被撤消并被视为已应用。例如，假设旧版本的SomeProcedure接受一个参数，而新版本需要两个参数，您可以执行以下操作：

.. patchdb:script:: Fix stored procedure signature
   :onerror: skip

   SELECT somecol FROM SomeProcedure(NULL, NULL)
   ;;
   ALTER PROCEDURE SomeProcedure(p_first INTEGER, p_second INTEGER)
   RETURNS (somecol INTEGER) AS
   BEGIN
     somecol = p_first * p_second;
     SUSPEND;
   END

过时的补丁

这种脚本的另一个特点是它们可以引用不存在的脚本 而不会产生警告或错误。

基本原理是，在数据库演进中，一个给定的脚本可能会被删除，可能会被一些后续补丁替换为不同的脚本。考虑一下您曾经有一张名为customers的表的情况：

.. patchdb:script:: Create table customers
   :revision: 2

   CREATE TABLE customers (
     id SERIAL PRIMARY KEY,
     name VARCHAR(80),
     street_address VARCHAR(80),
     city VARCHAR(80),
     telephone_number VARCHAR(80)
   )

.. patchdb:script:: Add telephone number to customers table
   :depends: Create table customers@1
   :brings: Create table customers@2

   ALTER TABLE customers ADD COLUMN telephone_number VARCHAR(80)

然后需要多个地址，因此您决定将其拆分为两个不同的关系，一个people和一个person_addresses：

.. patchdb:script:: Create table persons

   CREATE TABLE persons (
     id SERIAL PRIMARY KEY,
     name VARCHAR(80)
   )

.. patchdb:script:: Create table person_addresses
   :depends: Create table persons

   CREATE TABLE person_addresses (
     id SERIAL PRIMARY KEY,
     person_id INTEGER REFERENCES persons (id),
     street_address VARCHAR(80),
     city VARCHAR(80),
     telephone_number VARCHAR(80)
   )

.. patchdb:script:: Migrate from customers to persons and person_addresses
   :depends:
      - Create table customers@2
      - Create table persons
      - Create table person_addresses
   :drops:
      - Create table customers
      - Add telephone number to customers table

   INSERT INTO persons (id, name) SELECT id, name FROM customers
   ;;
   INSERT INTO person_addresses (person_id, street_address, city, telephone_number)
     SELECT id, street_address, city, telephone_number
     FROM customers
   ;;
   DROP TABLE customers

那时，引入原始客户表的脚本从文档中消失了，但您很可能希望保留迁移补丁一段时间，至少在您确定所有生产数据库都已升级之前。

假数据域

作为使用这种脚本的一个特例，以下示例说明了 MySQL数据域的近似值，但缺少它们：

.. patchdb:script:: Define data domains (MySQL)
   :language: sql
   :mimetype: text/x-mysql
   :conditions: mysql
   :always: first

   CREATE DOMAIN bigint_t bigint
   ;;
   CREATE DOMAIN `Boolean_t` char(1)

.. patchdb:script:: Create some table (MySQL)
   :language: sql
   :mimetype: text/x-mysql
   :conditions: mysql
   :always: first

   CREATE TABLE `some_table` (
       `ID` bigint_t NOT NULL,
     , `FLAG` `Boolean_t`

     , PRIMARY KEY (`ID`)
   )