扩展的定义 · PHP知识总结

[TOC] # **扩展的基本定义**        postgresql将多个SQL对象（如新函数、新操作符或新的索引操作符）收集到一个单一的包中，这种单一包有助于简化数据库的使用和管理，postgresql称这样单一的包为扩展。        扩展的定义至少需要一个包含创建该扩展的对象的SQL命令的脚本文件以及一个指定扩展本身的一些基本属性的*控制文件*。如果扩展包括 C 代码，通常还有一个 C 代码编译而成的共享库文件。有了这些文件，则可以通过`CREATE EXTENSION`命令将这些对象加载进数据库中。        扩展机制也对打包调整一个扩展中所含 SQL 对象定义的修改脚本有规定。例如，如果一个扩展的 1.1 版本比 1.0 版本增加了一个函数并且更改了另一个函数的函数体，该扩展的作者可以提供一个更新脚本来做这两个更改。那么`ALTER EXTENSION UPDATE`命令可以被用来应用这些更改并且跟踪在给定数据库中实际安装的是该扩展的哪个版本。 # **重要概念** * 扩展只在一个数据库范围内可见，因此数据库集簇范围的对象（例如数据库、角色和表空间）不能作为扩展成员；虽然一个表可以是一个扩展的成员，它的辅助对象（例如索引）不会被直接认为是该扩展的成员。因此不能通过`ALTER EXTENSION`命令进行更改 * 模式可以属于扩展，但是扩展不属于模式，扩展所对应的模式也可以通过`ALTER EXTENSION`命令进行更改 ``` // 查看当前已安装的扩展及其对应的模式 postgres=# SELECT e.oid,e.extname,n.nspname from pg_extension e JOIN pg_namespace n on e.extnamespace = n.oid; oid | extname | nspname -------+--------------------+------------ 13566 | plpgsql | pg_catalog 16439 | first_last_agg | public 16446 | pg_trgm | public 16540 | pg_freespacemap | public 16555 | pg_visibility | public 16565 | pg_stat_statements | public (6 rows) ``` # **扩展的优点** * 扩展的使用不只是运行SQL脚本载入这些“松散”的对象到数据库，而是postgresql可以将这个扩展的成员对象理解为“一个整体”，因此也可以使用单一的`DROP EXTENSION`命令删除指定扩展的所有对象，而不需要单独去维护单个对象的删除卸载 * 可将业务查询中高频使用的业务语句或复杂字段处理方式封装成扩展进行使用，就可以像内置的特性一样在数据库中运行，避免重复造轮子。 * 支持扩展的版本升级以及扩展中的SQL命令的更新 # **扩展的基本组成** * demo--1.0.sql * 对自定义函数的声明，在pgsql启动的时候会执行这个sql。文件命名遵循：`extension--version.sql`（例如：demo--1.0.sql表示扩展demo的1.0版本） * 默认情况下，脚本文件也被放置在`SHAREDIR/extension`目录中，但是控制文件中可以为脚本文件指定一个不同的目录 * SQL脚本文件能够包含任何 SQL 命令，除了事务控制命令（`BEGIN`、`COMMIT`等）以及不能在一个事务块中执行的命令（如`VACUUM`）。这是因为脚本文件会被隐式地在一个事务块中被执行 * demo.c：自定义函数的实现，纯C语言，目录下可包含多个.c文件。 * demo.control * `CREATE EXTENSION` 命令依赖每一个扩展都有的控制文件，控制文件必须被命名为扩展的名称加上一个后缀`.control`，并且必须被放在安装的`SHAREDIR/extension`目录中 * demo-1.0.control * 二级控制文件，以`extension--version.control`的风格命名，二级控制文件遵循主要控制文件相同的格式。 * 在安装或更新该扩展的版本时，一个二级控制文件中设置的任何参数将覆盖主要控制文件中的设置，参数`directory`以及`default_version`不能在二级控制文件中设置。 * Makefile：编译文件 ``` [postgres@izwz91quxhnlkan8kjak5hz contrib]$ ls btree_gin btree_gin--1.0--1.1.sql btree_gin--1.0.sql btree_gin--1.1--1.2.sql btree_gin--1.2--1.3.sql btree_gin.c btree_gin.control expected Makefile sql ``` ## **.control文件基本格式**        一个扩展控制文件的格式与`postgresql.conf`文件相同，即是一个`parameter_name = value`赋值的列表，每行一个。允许空行和`#`引入的注释。注意对任何不是单一词或数字的值加上引号。控制文件可以设置下列参数： * **directory(string)**：包含扩展的SQL脚本文件的目录。除非给出一个绝对路径，这个目录名是相对于安装的`SHAREDIR`目录。默认行为等效于指定`directory = extension` * **default_version(string)**：扩展的默认版本，如果`create extension`中没有指定，将默认使用这个参数 * **comment(string)**：关于该扩展的注释。该注释会在初始创建扩展时应用，但是扩展更新时不会引用该注释（因为可能会覆盖用户增加的注释）。扩展的注释也可以通过在脚本文件中写上[COMMENT](http://postgres.cn/docs/13/sql-comment.html "COMMENT")命令来设置。 * **encoding(string)**：该脚本文件使用的字符集编码。当脚本文件包含任何非 ASCII 字符时，可以指定这个参数。否则文件都会被假定为数据库编码。 * **module_pathname(string)**：该参数告诉PG在执行到用户自定义函数的时候去这个路径下找库文件。 * **requires(string)：** 这个扩展依赖的其他扩展名的一个列表，例如`requires = 'foo, bar'`。被依赖的扩展必须先于这个扩展安装 * **superuser(boolean)**：默认情况下为true，只有超级用户能够创建该扩展或者将它更新到一个新版本 * **trusted(boolean)**：默认值为false，如果设置为true，则允许非超级管理员权限的用户安装superuser已设置为true的扩展，即对于在当前数据库上具有`CREATE`特权的任何人，都允许安装。当执行`CREATE EXTENSION`的用户不是超级用户，但允许通过此参数安装时，则此安装或更新脚本作为引导超级用户运行，而不是作为调用用户 * **relocatable(boolean)**：扩展的可再定位性，如果支持扩展能被重定位到另一个模式则为true，默认为false。三种支持的可定位性级别： * 一个完全可重定位的扩展能在任何时候被移动到另一个模式中，即使在它被载入到一个数据库中之后。这种移动通过`ALTER EXTENSION SET SCHEMA`命令完成，该命令会自动地把所有成员对象重命名到新的模式中，它的控制文件中需要设置`relocatable = true` * 一个扩展可能在安装过程中是可重定位的，但是安装完后就不再可重定位。典型的情况是扩展的脚本文件需要显式地引用目标模式，例如为 SQL 函数设置`search_path`属性。对于这样一种扩展，在其控制文件中设置`relocatable = false`，并且使用`@extschema@`在脚本文件中引用目标模式。在脚本被执行前，所有这个字符串的出现都将被替换为实际的目标模式名。用户可以使用`CREATE EXTENSION`的`SCHEMA`选项设置目标模式名。 * 如果扩展根本就不支持重定位，在它的控制文件中设置`relocatable = false`，并且还设置`schema`为想要的目标模式的名称。这将阻止使用`CREATE EXTENSION`的`SCHEMA`选项修改目标模式，除非它指定的是和控制文件中相同的模式。如果该扩展包括关于模式名的内部假设且模式名不能使用`@extschema@`的方法替换，这种选择通常是必须的。`@extschema@`替换机制在这种情况中也是可用的，不过由于模式名已经被控制文件所决定，它的使用受到了很大的限制。 * **schema(string) ：** 这个参数只能为非可重定位扩展设置。它强制扩展被载入到给定的模式中而非其他模式中。只有在初始创建一个扩展时才会参考`schema`参数，扩展更新时则不会参考这个参数 > **控制文件参数补充说明：** >         1、关于`relocatable`，所有的情况下，脚本文件将被用[search\_path](http://postgres.cn/docs/13/runtime-config-client.html#GUC-SEARCH-PATH)执行，它会被设置为指向目标模式，也就是说`CREATE EXTENSION`做的也是等效的工作：`SET LOCAL search_path TO @extschema@, pg_temp;` >         2、如果控制文件中给出了`schema`参数，目标模式就由该参数决定，否则目标模式由`CREATE EXTENSION`的`SCHEMA`选项给出，如果以上两者都没有给出则会用当前默认的对象创建模式（在调用者`search_path`中的第一个）。当使用扩展文件的`schema`参数时，如果目标模式还不存在将创建它，但是在另外两种情况下它必须已经存在。 >         3、如果在控制文件中的`requires`中列举了任何先导扩展，它们的目标模式会被追加到`search_path`的初始设置中，遵循新扩展的目标模式。这允许新扩展的脚本文件能够看到它们的对象。 ``` [postgres@izwz91quxhnlkan8kjak5hz contrib]$ cat btree_gin/btree_gin.control # btree_gin extension comment = 'support for indexing common datatypes in GIN' default_version = '1.3' module_pathname = '$libdir/btree_gin' relocatable = true trusted = true ``` ## **Makefile文件基本格式**        postgresql为扩展的安装提供了一种被称为PGXS的构建基础设施，因此简单的扩展模块能够在一个已经安装的服务器上简单地编译。PGXS基础设施需要应用于扩展的Makefile文件中，这三行总是相同的： ``` EXTENSION = demo # 扩展名称 DATA = demo--1.0.sql # 扩展安装的sql脚本文件 # pgsql构建扩展的相关命令，固定即可，无需更改 PG_CONFIG = pg_config PGXS := $(shell $(PG_CONFIG) --pgxs) include $(PGXS) ``` # **扩展版本更新机制**        可以通过扩展的安装脚本的每一个发行版本关联一个版本名称或者版本号来实现动态的将数据库从一个版本更新到下一个版本，脚本的名称遵循`extension--old_version--target_version.sql`模式（例如`demo--1.0--1.1.sql`包含着把扩展`demo`的版本`1.0`修改成版本`1.1`的命令）        命令`ALTER EXTENSION UPDATE`可以将把一个已安装的扩展更新到指定的新版本。此外，此命令能够根据更新脚本的版本序列实现版本更新，例如只有`demo--1.0--1.1.sql`和`demo--1.1--2.0.sql`可用，当前安装了`1.0`版本并且要求更新到版本`2.0`，`ALTER EXTENSION` 命令将将依次应用它们。        PostgreSQL不对更新脚本的版本名称的属性做任何假设，例如`demo--1.0--1.1.sql`，它不知道是否`1.1`遵循`1.0`，它只是匹配可用的版本名称并遵循需要应用最少更新脚本的路径。（版本名称实际上可以是不包含`--`或前缀或后缀的任何字符串`-`） > **Q：** 那么问题就来了，pgsql无法识别更新脚本的命名规范是否真实有效，是如何通过匹配可用的版本名称来搜索出可用的更新脚本的**最短路径**？ > **A：** 通过pgsql的内置系统函数`pg_extension_update_paths`来检索扩展版本之间的可用更新路径。 ``` // pg_extension_update_paths 函数输出显示了扩展版本的每个组合，以及从source版本升级到目标版本时将执行的扩展脚本组合 // 如果路径为空，则无法升级 postgres=# SELECT * FROM pg_extension_update_paths('first_last_agg'); source | target | path ------------+------------+----------------------------------------------- 0.1.4 | 0.1.2 | 0.1.4 | 0.1.3 | 0.1.4 | 0.1.1 | 0.1.4 | unpackaged | 0.1.4 | 0.1.0 | 0.1.2 | 0.1.4 | 0.1.2--0.1.3--0.1.4 0.1.2 | 0.1.3 | 0.1.2--0.1.3 0.1.2 | 0.1.1 | 0.1.2 | unpackaged | 0.1.2 | 0.1.0 | 0.1.3 | 0.1.4 | 0.1.3--0.1.4 0.1.3 | 0.1.2 | 0.1.3 | 0.1.1 | 0.1.3 | unpackaged | 0.1.3 | 0.1.0 | 0.1.1 | 0.1.4 | 0.1.1--0.1.2--0.1.3--0.1.4 0.1.1 | 0.1.2 | 0.1.1--0.1.2 0.1.1 | 0.1.3 | 0.1.1--0.1.2--0.1.3 0.1.1 | unpackaged | 0.1.1 | 0.1.0 | unpackaged | 0.1.4 | unpackaged--0.1.0--0.1.1--0.1.2--0.1.3--0.1.4 unpackaged | 0.1.2 | unpackaged--0.1.0--0.1.1--0.1.2 unpackaged | 0.1.3 | unpackaged--0.1.0--0.1.1--0.1.2--0.1.3 unpackaged | 0.1.1 | unpackaged--0.1.0--0.1.1 unpackaged | 0.1.0 | unpackaged--0.1.0 0.1.0 | 0.1.4 | 0.1.0--0.1.1--0.1.2--0.1.3--0.1.4 0.1.0 | 0.1.2 | 0.1.0--0.1.1--0.1.2 0.1.0 | 0.1.3 | 0.1.0--0.1.1--0.1.2--0.1.3 0.1.0 | 0.1.1 | 0.1.0--0.1.1 0.1.0 | unpackaged | (30 rows) ```        postgresql并不对更新脚本的版本名称的属性做任何假设，因此即可以实现版本升级，也可以实现“版本降级”，例如，将脚本命名为`demo--1.1--1.0.sql`。降级更新可能会导致的问题在于，降级脚本存在被意外使用的可能性，因为降级脚本会得到一个较短的路径，如果降级版本删除了任何不可替代的对象，这将会得到意想不到的结果。        一个已经存在一段时间的扩展可能存在多个版本。例如，如果你已经发布了扩展`demo`的`1.0`、`1.1`和`1.2`版本，就应该有更新脚本`demo--1.0--1.1.sql`和`demo--1.1--1.2.sql`。`CREATE EXTENSION`能够自动遵循更新链。例如，如果只有脚本文件`demo--1.0.sql`、`demo--1.0--1.1.sql`和`demo--1.1--1.2.sql`可用，那么安装版本`1.2`的请求会通过按顺序运行上述三个脚本来实现。这种处理和先安装`1.0`然后更新到`1.2`是一样的（和`ALTER EXTENSION UPDATE`一样，如果有多条路径可用则优先选择最短的） > 在PostgreSQL10之前，还有必要创建新的脚本文件`demo--1.1.sql`和`demo--1.2.sql`，它们直接构建比较新的扩展版本，或者新的版本无法被直接安装，而是通过先安装`1.0`然后更新        如果以这种风格维护的扩展中使用了二级（版本相关的）控制文件，记住每个版本都需要一个控制文件，即使它没有单独的安装脚本，因为该控制文件将决定如何执行到这个版本的隐式更新。例如，如果`demo--1.0.control`指定有`requires = 'bar'`，但`demo`的其他控制文件没有这样做，在从`1.0`更新到另一个版本时，该扩展对`bar`的依赖将被删除。