如何现写一个简易插件

PostgreSQL插件指南

PostgreSQL是一个开源的数据库管理系统，是用于学习编程、设计和调试的一个好方式。PostgreSQL的一个主要特性便是扩展Extensions。扩展可以像pg_fincore一样足够小，用于缓存大型项目如PostGIS和Citus等数据页至操作系统的缓存中。PostgreSQL扩展是一段增强PostgreSQL服务器功能的脚本或代码。在这篇文章中，我们将了解关于扩展的方方面面。

这篇文章主要关注PostgreSQL扩展的底层原理，从创建自己扩展开始，并从其内部原理方面着手。在我们开始之前，我强烈建议你了解基本的一些知识：

• How to create and compile a C Program on Linux
• What is shared library
• How to create and run a shared Library file
• How to create a simple function in PostgreSQL

什么是PostgreSQL扩展

PostgreSQL扩展是一系列SQL对象（如函数、存储过程、表、索引）的集合。将这些相关的对象打包至一个插件中的优势是，可以很方便的管理这些对象，以一个包来管理，而不是使用一个或多个分散开的脚本。

PostgreSQL提供了一些默认开箱即用的插件，用户也可以基于需求创建自定义插件。

如何创建一个PostgreSQL扩展

我们可以使用如下命令简单的创建一个PostgreSQL扩展：

create extension extension_name;

但是在数据库内执行上述命令之前，需要有两个重要的文件放在共享目录/isntall_directory/share/extension path之下，他们是：

1. 控制文件
2. SQL脚本

控制文件：文件的格式必须是extension_name.control，它用于告诉PostgreSQL此扩展的一些基础信息

SQL脚本：格式为extension–version.sql，包含了你想要添加的函数。如果想要通过SQL修改命令更新扩展，新版本的文件应该是extension–old_version–new_version.sql

安装了一个扩展之后，PostgreSQL会将所有打包的对象放入到对应数据库模式中。如果扩展可以移动到另一个模式，则称该扩展为“可重定位”的。

让我们为add_ten函数创建一个扩展

第一步，创建一个SQL脚本文件（add_ten-1.0.sql）

[root@prim shared]# cat add_ten--1.0.sql
CREATE OR REPLACE FUNCTION add_ten(sum INTEGER)
RETURNS INTEGER AS $$
DECLARE
    result INTEGER;
BEGIN
    result = sum + 10;
RETURN result;
END; 
$$ LANGUAGE plpgsql;

add_ten-1.0.sql只是一个要在PostgreSQL中运行的普通函数。

第二步，创建一个控制文件（add_ten.control）

[root@prim shared]# cat add_ten.control
# sum_fn extension
comment = 'Add ten to given number'
default_version = '1.0'
module_pathname = '$libdir/add_ten'
relocatable = false

comment：关于扩展的描述，仅在安装时应用。

default_version：当不需要特定的版本时，作为默认安装的版本。

module_pathname：脚本文件中每次出现的module_pathname，都会被替换为该值。如果没有设置，则不进行替换。通常情况下，这个参数都会被设为 $libdir/shared_library_name，那么使用create function命令创建使用C语言编写的函数时就可以直接使用module_pathname，而不需要硬连接共享库的名称。

relocatable：一个布尔类型的标志，标志该插件是否是可重定位的。

其他的一些元信息可能还包括directory, default_version, comment, encoding, module_pathname, requires, superuser, relocatable, and schema。

第三步，创建一个Makefile文件，以在共享库目录下创建扩展

[root@prim shared]# cat Makefile
EXTENSION = add_ten
DATA = add_ten--1.0.sql

PG_CONFIG = pg_config
PGXS := $(shell $(PG_CONFIG) --pgxs)
include $(PGXS)

现在，在完成Makefile之后，安装程序就会在当前目录下查找<name-version>.sql文件和<name>.control文件，并将这些文件放到PostgreSQL共享库下。接着运行make install即可安装插件

[root@prim shared]# make install
/bin/mkdir -p '/usr/pgsql-10/share/extension'
/bin/mkdir -p '/usr/pgsql-10/share/extension'
/usr/bin/install -c -m 644 .//add_ten.control '/usr/pgsql-10/share/extension/'
/usr/bin/install -c -m 644 .//add_ten--1.0.sql  '/usr/pgsql-10/share/extension/'

安装程序会在共享库路径下创建两个文件

[root@prim extension]# ls -lrt add_ten*
-rw-r--r--. 1 root root 136 May 13 21:50 add_ten.control
-rw-r--r--. 1 root root 157 May 13 21:50 add_ten--1.0.sql
[root@prim extension]# pwd
/usr/pgsql-10/share/extension

如果安装失败，请确保pg_config命令指向了正确的路径

[root@prim extension]# pg_config | grep SHAREDIR
SHAREDIR = /usr/pgsql-10/share
[root@prim extension]#

也可以在调用Makefile之前设置路径

export PATH=/usr/pgsql-10/bin:$PATH

现在，在库里通过create extension add_ten命令创建并测试扩展

postgreshelp=# create extension add_ten;
CREATE EXTENSION
postgreshelp=# select add_ten(17);
 add_ten
---------
      27
(1 row)

通过 \dx 命令检查插件的版本

postgreshelp=# \dx
                 List of installed extensions
  Name   | Version |   Schema   |         Description
---------+---------+------------+------------------------------
 add_ten | 1.0     | public     | Add ten to given number
 plpgsql | 1.0     | pg_catalog | PL/pgSQL procedural language
(2 rows)

ok，假如我需要增强插件的功能，我该如何升级现有插件？

如何更新现有插件？

上面的插件只能接受一个值，再加10。如果我想接受两个值呢？

postgreshelp=# select add_ten(17,14);
ERROR:  function add_ten(integer, integer) does not exist
LINE 1: select add_ten(17,14);
               ^
HINT:  No function matches the given name and argument types. 
You might need to add explicit type casts.
postgreshelp=#

如您所见，该函数不能接受两个值。现在我们更新现有的扩展以接受两个值。要更新现有的扩展，我们需要再次创建两个必需的文件，控制文件和SQL文件。

第一步，创建一个SQL脚本文件 (add_ten–1.0–1.1.sql)

[root@prim extension]# cat add_ten--1.0--1.1.sql
CREATE OR REPLACE FUNCTION add_ten(sum INTEGER,sum2 INTEGER)
RETURNS INTEGER AS $$
DECLARE
      result INTEGER;
BEGIN
      result = sum + sum2;
RETURN result;
END; 
$$ LANGUAGE plpgsql;

第二步，创建一个控制文件 (add_ten.control)

[root@prim extension]# cat add_ten.control
# sum_fn extension
comment = 'Accept two values and add them'
default_version = '1.1'
module_pathname = '$libdir/add_ten'
relocatable = false

第三步，创建一个Makefile文件，以在共享库目录下创建扩展

[root@prim shared]# cat Makefile
EXTENSION = add_ten
DATA = add_ten--1.0--1.1.sql

PG_CONFIG = pg_config
PGXS := $(shell $(PG_CONFIG) --pgxs)
include $(PGXS)

第四步，运行make install

[root@prim shared]# make install
/bin/mkdir -p '/usr/pgsql-10/share/extension'
/bin/mkdir -p '/usr/pgsql-10/share/extension'
/usr/bin/install -c -m 644 .//add_ten.control '/usr/pgsql-10/share/extension/'
/usr/bin/install -c -m 644 .//add_ten--1.0--1.1.sql  '/usr/pgsql-10/share/extension/'
[root@prim shared]#

[root@prim shared]#
[root@prim shared]# cd /usr/pgsql-10/share/extension
[root@prim extension]#
[root@prim extension]# ls -lrt add_ten*
-rw-r--r--. 1 root root 143 May 13 22:28 add_ten.control
-rw-r--r--. 1 root root 172 May 13 22:28 add_ten--1.0--1.1.sql
[root@prim extension]#

第五步，更新现有插件

你可以通过如下SQL命令更新现有插件 ALTER EXTENSION <NAME> UPDATE TO ‘<VERSION>’;

postgreshelp=# ALTER EXTENSION add_ten UPDATE TO '1.1';
ALTER EXTENSION
postgreshelp=# select add_ten(17,14);
 add_ten
---------
      31
(1 row)

检查设置

postgreshelp=# \dx
                 List of installed extensions
  Name   | Version |   Schema   |         Description
---------+---------+------------+------------------------------
 add_ten | 1.1     | public     | Accept two values and add them
 plpgsql | 1.0     | pg_catalog | PL/pgSQL procedural language
(2 rows)

现在PostgreSQL扩展的更新路径应该是这样的

postgreshelp=# select * from pg_extension_update_paths('add_ten');
 source | target |   path
--------+--------+----------
 1.0    | 1.1    | 1.0--1.1
 1.1    | 1.0    |
(2 rows)

好了，现在已经知道如果我们有一个控制文件和SQL文件，就可以配置扩展。由于PostgreSQL是用C语言编写的，如果你想在扩展中有一个用C语言编写的函数该怎么办？

基于C语言函数的扩展

要想在扩展中运行标准C代码，你需要一个由 PGXN 提供的可移植构建系统。我们将在这篇文章的后面了解更多关于 PGXN 的内容。

已安装好的PostgreSQL为扩展提供了一个基础的构建架构，称之为 PGXS，它提供了一个全局变量 USE_PGXS，以包含全局的 PGXS makefiles，这样的话，就可以基于已经安装好的服务器，简易地构建出PostgreSQL扩展模块。PGXS主要用于C代码的扩展，不过也可以用于纯SQL的扩展。

现在，写一个相同的C函数，给出一个值并加10，以此构建扩展。

当您用C编写函数时，除了控制文件和SQL文件外，也需要一个动态共享库文件 (.so)

第一步，创建一个SQL脚本文件 (add_cfun–1.0.sql)

CREATE OR REPLACE FUNCTION add_cfun(arg INTEGER) RETURNS INTEGER  AS
'MODULE_PATHNAME','add_cfun'
LANGUAGE C STRICT;

第二步，创建一个控制文件 (add_cfun.control)

# demo extension
comment = 'add cfun'
default_version = '1.0'
module_pathname = '$libdir/add_cfun'
relocatable = true

第三步，创建一个C程序 (add_cfun.c)

#include "/usr/pgsql-10/include/server/postgres.h"
#include "/usr/pgsql-10/include/server/fmgr.h"
#include "/usr/pgsql-10/include/server/utils/errcodes.h"

PG_MODULE_MAGIC;
PGDLLEXPORT Datum add_cfun(PG_FUNCTION_ARGS);
PG_FUNCTION_INFO_V1(add_cfun);
Datum
add_cfun(PG_FUNCTION_ARGS)
{
    int32   arg = PG_GETARG_INT32(0);
    PG_RETURN_INT32(arg + 10);
}

第四步，创建一个Makefile文件，以在共享库目录下创建扩展

MODULES = add_cfun
EXTENSION = add_cfun
DATA = add_cfun--1.0.sql

PG_CONFIG = pg_config
PGXS := $(shell $(PG_CONFIG) --pgxs)
include $(PGXS)

现在，我们有4个文件。

[root@prim s6]# ls -lrt
total 16
-rw-r--r--. 1 root root 117 May 13 23:07 add_cfun--1.0.sql
-rw-r--r--. 1 root root 356 May 13 23:08 add_cfun.c
-rw-r--r--. 1 root root 145 May 13 23:09 Makefile
-rw-r--r--. 1 root root 116 May 13 23:13 add_ten.control

第五步，使用make install安装扩展

[root@prim s6]# make install
gcc -Wall -Wmissing-prototypes -Wpointer-arith -Wdeclaration-after-statement 
-Wendif-labels -Wmissing-format-attribute -Wformat-security -fno-strict-aliasing 
-fwrapv -O2 -g -pipe -Wall -Wp,-D_FORTIFY_SOURCE=2 -fexceptions -fstack-protector 
--param=ssp-buffer-size=4 -m64 -mtune=generic -fPIC -I. -I./ 
-I/usr/pgsql-10/include/server -I/usr/pgsql-10/include/internal -I/usr/include 
-D_GNU_SOURCE -I/usr/include/libxml2  -I/usr/include  -c -o add_cfun.o add_cfun.c
gcc -Wall -Wmissing-prototypes -Wpointer-arith -Wdeclaration-after-statement 
-Wendif-labels -Wmissing-format-attribute -Wformat-security -fno-strict-aliasing 
-fwrapv -O2 -g -pipe -Wall -Wp,-D_FORTIFY_SOURCE=2 -fexceptions -fstack-
protector 
--param=ssp-buffer-size=4 -m64 -mtune=generic -fPIC -L/usr/pgsql-10/lib -Wl,
--as-needed  
-L/usr/lib64 -Wl,--as-needed -Wl,-rpath,'/usr/pgsql-10/lib',--enable-new-dtags  
-shared -o add_cfun.so add_cfun.o
/bin/mkdir -p '/usr/pgsql-10/share/extension'
/bin/mkdir -p '/usr/pgsql-10/share/extension'
/bin/mkdir -p '/usr/pgsql-10/lib'
/usr/bin/install -c -m 644 .//add_cfun.control '/usr/pgsql-10/share/extension/'
/usr/bin/install -c -m 644 .//add_cfun--1.0.sql  '/usr/pgsql-10/share/extension/'
/usr/bin/install -c -m 755  add_cfun.so '/usr/pgsql-10/lib/'

上面的命令安装了扩展，并将SQL文件和控制文件复制到了共享位置，.so文件复制到了共享库。

[root@prim s6]# cd /usr/pgsql-10/share/extension/
[root@prim extension]# ls -lrt add_cfun*
-rw-r--r--. 1 root root 118 May 13 23:14 add_cfun.control
-rw-r--r--. 1 root root 117 May 13 23:14 add_cfun--1.0.sql
[root@prim extension]#
[root@prim extension]#
[root@prim extension]# cd /usr/pgsql-10/lib/
[root@prim lib]# ls -lrt add_cfun*
-rwxr-xr-x. 1 root root 10522 May 13 23:14 add_cfun.so

第六步，创建扩展并测试

postgreshelp=# create extension add_cfun;
CREATE EXTENSION
postgreshelp=# select add_cfun(16);
 add_cfun
----------
       26
(1 row)

到目前为止，现有的插件

postgreshelp=# \dx
                  List of installed extensions
   Name   | Version |   Schema   |         Description
----------+---------+------------+------------------------------
 add_cfun | 1.0     | public     | add cfun
 add_ten  | 1.1     | public     | Add ten to given number
 plpgsql  | 1.0     | pg_catalog | PL/pgSQL procedural language
(3 rows)

如何删除一个已有插件？

postgreshelp=# drop extension add_ten;
DROP EXTENSION

重温：pg_stat_statements

让我们通过著名的pg_stat_statements插件，重温一下到目前为止我们所学的。

第一步，创建扩展

postgres=# create extension pg_stat_statements;
CREATE EXTENSION

插件创建好之后，意味着：

• 有两个文件，一个叫 xxx.control，一个叫 xxx.SQL，位于 share/extension目录下
• 如果是使用的C程序，在 lib/ 目录下还会有一个 .so文件

第二步，使用扩展

postgres=# select * from pg_stat_statements;
ERROR: pg_stat_statements must be loaded via shared_preload_libraries

报了一个错误，因为该插件需要在系统启动过程中预先加载。

[postgres@prim ~]$ cat /u01/pgsql/data/postgresql.conf | grep shared_preload_libraries
shared_preload_libraries = ‘pg_stat_statements,repmgr’ # (change requires restart)

重启之后

postgres=# \x
Expanded display is on.
postgres=# select * from pg_stat_statements;
-[ RECORD 1 ]-------+---------------------------------
userid              | 10
dbid                | 13164
queryid             | 3314984744
query               | select * from pg_stat_statements
calls               | 1
total_time          | 0.119963
min_time            | 0.119963
..
..

检查一下这个插件的后台文件，包括SQL和控制文件

[postgres@prim extension]$ ls -lrt pg_stat_statements*
…
-rw-r–r–. 1 root root 191 Feb 12 02:47 pg_stat_statements.control
-rw-r–r–. 1 root root 376 Feb 12 02:47 pg_stat_statements–1.5–1.6.sql
-rw-r–r–. 1 root root 1427 Feb 12 02:47 pg_stat_statements–1.4.sql

这里，1.4是最开始的版本，最新的是1.6

一小块pg_stat_statements - 1.4.sql 的代码如下：

— Register functions.
CREATE FUNCTION pg_stat_statements_reset()
RETURNS void
AS ‘MODULE_PATHNAME’
LANGUAGE C PARALLEL SAFE;

意味着是使用的C语言编写的代码，所以在/lib目录下会有一个.so文件

[postgres@prim lib]$ pwd
/usr/pgsql-10/lib

[postgres@prim lib]$ ls -lrt pg_stat*
-rwxr-xr-x. 1 root root 33928 Feb 12 02:47 pg_stat_statements.so
[postgres@prim lib]$

因为它是一个共享对象文件，所以我们看不到.so文件的具体内容，但是pg_stat_statements.c的其中一小段代码如下：

{
/*
* In order to create our shared memory area, we have to be loaded via
* shared_preload_libraries. If not, fall out without hooking into any of
* the main system. 
*/
if (!process_shared_preload_libraries_in_progress)
return;

社区版本已提供的插件

postgreshelp=# select name, comment from pg_available_extensions ;
        name        |                               comment
--------------------+----------------------------------------------------------------------
 plpgsql            | PL/pgSQL procedural language
 add_ten_1          | Add ten to given number
 Nvlfunc            | Oracle compatible nvl function
 cube               | data type for multidimensional cubes
 nvlfunc            | Oracle compatible nvl function
 file_fdw           | foreign-data wrapper for flat file access
 btree_gist         | support for indexing common datatypes in GiST
 fuzzystrmatch      | determine similarities and distance between strings
 add_ten            | Accept two values and add them
 pgstattuple        | show tuple-level statistics
 plperl             | PL/Perl procedural language
 pg_trgm            | text similarity measurement and index searching based 
                      on trigrams
 btree_gin          | support for indexing common datatypes in GIN
 pg_buffercache     | examine the shared buffer cache
 intarray           | functions, operators, and index support for 1-D arrays 
                      of integers
 pltclu             | PL/TclU untrusted procedural language
 sslinfo            | information about SSL certificates
 chkpass            | data type for auto-encrypted passwords
 intagg             | integer aggregator and enumerator (obsolete)
 seg                | data type for representing line segments or floating-point
                      intervals
 ltree_plpythonu    | transform between ltree and plpythonu
 repmgr             | Replication manager for PostgreSQL
 dblink             | connect to other PostgreSQL databases from within a 
                      database
 timetravel         | functions for implementing time travel
 amcheck            | functions for verifying relation integrity
 plpythonu          | PL/PythonU untrusted procedural language
 ltree              | data type for hierarchical tree-like structures
 hstore_plpythonu   | transform between hstore and plpythonu
 pageinspect        | inspect the contents of database pages at a low level
 dict_xsyn          | text search dictionary template for extended synonym 
                      processing
 autoinc            | functions for autoincrementing fields
 prog               | Demo Extension for Postgres Conference
 pgcrypto           | cryptographic functions
 uuid-ossp          | generate universally unique identifiers (UUIDs)
 citext             | data type for case-insensitive character strings
 hstore_plperlu     | transform between hstore and plperlu
 postgres_fdw       | foreign-data wrapper for remote PostgreSQL servers
 bloom              | bloom access method - signature file based index
 tablefunc          | functions that manipulate whole tables, including 
                      crosstab
 tsm_system_time    | TABLESAMPLE method which accepts time in milliseconds
 as a limit
 hstore             | data type for storing sets of (key, value) pairs
 pgrowlocks         | show row-level locking information
 insert_username    | functions for tracking who changed a table
 pg_prewarm         | prewarm relation data
 pltcl              | PL/Tcl procedural language
 refint             | functions for implementing referential integrity 
 hstore_plpython2u  | transform between hstore and plpython2u
 moddatetime        | functions for tracking last modification time
 isn                | data types for international product numbering standards
 add_cfun           | add cfun
 plpython2u         | PL/Python2U untrusted procedural language
 tcn                | Triggered change notifications
 dict_int           | text search dictionary template for integers
 lo                 | Large Object maintenance
 unaccent           | text search dictionary that removes accents
 plperlu            | PL/PerlU untrusted procedural language
 ltree_plpython2u   | transform between ltree and plpython2u
 tsm_system_rows    | TABLESAMPLE method which accepts number of rows as 
                      a limit
 demo               | Demo Extension for Postgres Conference
 pg_freespacemap    | examine the free space map (FSM)
 pg_stat_statements | track execution statistics of all SQL statements executed
 sum_fn             | sum of two numbers
 earthdistance      | calculate great-circle distances on the surface of 
                      the Earth
 adminpack          | administrative functions for PostgreSQL
 pg_visibility      | examine the visibility map (VM) and page-level 
                      visibility info
 hstore_plperl      | transform between hstore and plperl
 xml2               | XPath querying and XSLT
(67 rows)

Azure for PostgreSQL提供的插件

DigitalOcean提供的插件

小结

通过前文介绍的，就可以快速现写一个简易的插件，Extension我觉得和Oracle中的schema有点类似，打包打包 ~ 另外，对更新插件的流程也有了一个简单的认知 👍

译自：https://postgreshelp.com/postgresql-extension/