编写Postgres扩展之一：基础

其他 2019-08-05 14:28:03 阅读次数: 0

Postgres提供了广泛的数据类型、函数、操作符以及聚合功能。但有时它仍然不能满足你的某个特定需求， 幸运的是，通过"扩展"可以很容易地扩展Postgres的功能。 那么为什么不写一个自己的Postgresql扩展呢？

这是编写Postgres扩展系列文章中的第一篇。 你可以按照分支part_i上的代码示例进行操作。

base36

你可能已经知道url缩短器使用的技巧——使用一些特殊的随机字符（如http://goo.gl/EAZSKW）指向其他内容。当然，你必须记住它指向何处，因此你需要将其存储在数据库中。但是，与其使用varchar(6)保存6个字符(从而浪费7个字节)，为什么不使用一个包含4个字节的整数并将其表示为base36呢?

Postgresql扩展的骨架

要在数据库中运行CREATE EXTENSION命令，你的扩展最少需要两个文件：一个格式化的控制文件extension_name.control，用于告诉Postgresql关于你的扩展的一些基础信息；一个是格式化的扩展SQL脚本extension--version.sql。因此，我们先在工程目录中添加这两个文件。

控制文件的一个很好的起点可以像下面这样：

文件名:base32.control

# base36 extension
comment = 'base36 datatype'
default_version = '0.0.1'
relocatable = true

到目前为止，我们的扩展还没有任何功能。让我们在SQL脚本文件中添加一些:

文件名：base32--0.0.1.sql

-- complain if script is sourced in psql, rather than via CREATE EXTENSION
\echo Use "CREATE EXTENSION base36" to load this file. \quit
CREATE FUNCTION base36_encode(digits int)
RETURNS text
LANGUAGE plpgsql IMMUTABLE STRICT
  AS $$
    DECLARE
      chars char[];
      ret varchar;
      val int;
    BEGIN
      chars := ARRAY[
                '0','1','2','3','4','5','6','7','8','9','a','b','c','d','e','f','g','h',
                'i','j','k','l','m','n','o','p','q','r','s','t', 'u','v','w','x','y','z'
              ];

      val := digits;
      ret := '';

    WHILE val != 0 LOOP
      ret := chars[(val % 36)+1] || ret;
      val := val / 36;
    END LOOP;

    RETURN(ret);
    END;
  $$;

第二行确保文件不会直接加载到数据库中，而只能通过CREATE EXTENSION加载。

这个简单的pl/pgsql函数允许我们将任何整数编码到它的base36表示形式中。如果我们将这两个文件复制到postgres 的SHAREDIR/extension目录中（译者注：可以通过pg_config命令获取），我们就可以通过CREATE EXTENSION使用这个扩展了。但是我们不会麻烦用户去弄清楚这些文件放在哪里，以及如何手动复制它们，这是makefile该做的事。现在让我们在项目中添加一个makefile。

Makefile

从9.1版本开始，每个PostgreSQL安装都为扩展提供了一个名为PGXS的构建基础设施，允许在已经安装的服务器上轻松构建扩展。构建扩展所需的大多数环境变量都是在pg_config中设置的，可以简单地重用。

对于我们的示例，下面这个Makefile就符合我们的需求。

文件名：Makefile

EXTENSION = base36        # 扩展名称
DATA = base36--0.0.1.sql  # 要安装的脚本文件

# postgres build stuff
PG_CONFIG = pg_config
PGXS := $(shell $(PG_CONFIG) --pgxs)
include $(PGXS)

现在我们可以开始使用扩展了。 在你的工程运行make install。并在数据库中执行如下操作：

test=# CREATE EXTENSION base36;
CREATE EXTENSION
Time: 3,329 ms
test=# SELECT base36_encode(123456789);
 base36_encode
---------------
 21i3v9
(1 row)

Time: 0,558 ms

HiaHiaHia，太棒了！

编写测试

如今，每个认真的开发人员都会编写测试 作为处理数据的数据库开发人员（可能是贵公司最有价值的东西），你也应该这样做。

你可以很容易地向项目中添加一些回归测试，这些测试可以在完成make install之后通过make installcheck调用。为此，你可以将测试脚本文件放在名为sql/的子目录中。对于每个测试文件，在名为expected/的子目录中也应该有一个对应包含预期输出的文件，该文件具有与测试脚本相同的名称，只不过后缀是.out。make installcheck命令使用psql执行每个测试脚本，并将结果输出与匹配的预期文件进行比较。任何差异都将写入文件regression.diffs。我们开始吧：
文件名：sql/base36_test.sql

CREATE EXTENSION base36;
SELECT base36_encode(0);
SELECT base36_encode(1);
SELECT base36_encode(10);
SELECT base36_encode(35);
SELECT base36_encode(36);
SELECT base36_encode(123456789);

我们还需要告诉我们的Makefile关于测试的信息(第3行):

文件名：Makefile

EXTENSION = base36     
DATA = base36--0.0.1.sql  
REGRESS = base36_test     # 我们的测试脚本文件(没有后缀名)

# postgres build stuff
PG_CONFIG = pg_config
PGXS := $(shell $(PG_CONFIG) --pgxs)
include $(PGXS)

如果我们现在运行make install && make installcheck，那么我们的测试将失败。这是因为我们没有指定预期的输出。但是，我们将找到包含base36_test.out和base36 test.out.diff的新目录result。前者包含测试脚本文件的实际输出。让我们将它移动到所需的目录中。:

mkdir expected
mv results/base36_test.out expected

如果现在重新运行我们的测试，我们会看到类似的结果:

============== running regression test queries        ==============
test base36_test              ... ok

=====================
 All 1 tests passed.
=====================

太好了！ 但是，嘿，我们在这里作弊了。 如果我们看一下我们的期望，我们会注意到这不是我们所期望的。

cat expected/base36_test.out
CREATE EXTENSION base36;
SELECT base36_encode(0);
 base36_encode
---------------

(1 row)

SELECT base36_encode(1);
 base36_encode
---------------
 1
(1 row)

SELECT base36_encode(10);
 base36_encode
---------------
 a
(1 row)

SELECT base36_encode(35);
 base36_encode
---------------
 z
(1 row)

SELECT base36_encode(36);
 base36_encode
---------------
 10
(1 row)

SELECT base36_encode(123456789);
 base36_encode
---------------
 21i3v9
(1 row)

你会注意到在第6行，base36_encode(0)返回一个空字符串，而我们期望的是0。如果我们修正我们的期望，我们的测试将再次失败。

============== running regression test queries        ==============
test base36_test              ... FAILED

======================
 1 of 1 tests failed.
======================

The differences that caused some tests to fail can be viewed in the
file "regression.diffs".  A copy of the test summary that you see
above is saved in the file "regression.out".

make: *** [installcheck] Error 1

我们可以通过查看前面提到的regression.diffs轻松地检查失败的测试.

*** 2,8 ****
  SELECT base36_encode(0);
   base36_encode
  ---------------
!  0
  (1 row)

  SELECT base36_encode(1);
--- 2,8 ----
  SELECT base36_encode(0);
   base36_encode
  ---------------
!
  (1 row)

  SELECT base36_encode(1);

你可以按照“预期的0已获得”来阅读它。

现在让我们在编码函数中实现修复，使测试再次通过(第12-14行):

文件名：base36-0.0.1.sql

-- complain if script is sourced in psql, rather than via CREATE EXTENSION
\echo Use "CREATE EXTENSION base36" to load this file. \quit
CREATE FUNCTION base36_encode(digits int)
RETURNS character varying
LANGUAGE plpgsql IMMUTABLE STRICT
  AS $$
    DECLARE
      chars char[];
      ret varchar;
      val int;
    BEGIN
      IF digits = 0
        THEN RETURN('0');
      END IF;
      chars := ARRAY[
                '0','1','2','3','4','5','6','7','8','9','a','b','c','d','e','f','g','h',
                'i','j','k','l','m','n','o','p','q','r','s','t', 'u','v','w','x','y','z'
              ];

      val := digits;
      ret := '';

    WHILE val != 0 LOOP
      ret := chars[(val % 36)+1] || ret;
      val := val / 36;
    END LOOP;

    RETURN(ret);
    END;
  $$;

优化速度，写一些C代码

虽然在扩展中提供相关功能是共享代码的一种方便方法，但真正有趣的是用c语言实现。让我们获得第一个1M base36数字。

test=# SELECT i, base36_encode(i) FROM generate_series(1,1e6::int) i;
Time: 11289,610 ms

11秒？ ......好吧，不是那么快。

让我们看看我们是否能在c语言中做得更好。编写c语言函数并没有那么难。

文件名base36.c

#include "postgres.h"
#include "fmgr.h"
#include "utils/builtins.h"

PG_MODULE_MAGIC;

PG_FUNCTION_INFO_V1(base36_encode);
Datum
base36_encode(PG_FUNCTION_ARGS)
{
    int32 arg = PG_GETARG_INT32(0);
    char base36[36] = "0123456789abcdefghijklmnopqrstuvwxyz";

    /* max 6 char + '\0' */
    char *buffer = palloc(7 * sizeof(char));
    unsigned int offset = sizeof(buffer);
    buffer[--offset] = '\0';

    do {
        buffer[--offset] = base36[arg % 36];
    } while (arg /= 36);


    PG_RETURN_TEXT_P(cstring_to_text(&buffer[offset]));
}

你可能已经注意到实际的算法是维基百科提供的。让我们看看我们添加了什么来使它与Postgres一起使用
。

#include "postgres.h"包括与Postgres接口所需的大部分基本内容。 这行必须包含在声明Postgres函数的每个C文件中。

#include "fmgr.h"需要包含以使用PG_GETARG_XXX和PG_RETURN_XXX宏。

#include "utils/builtins.h"在Postgres的内置数据类型上定义了一些操作（稍后使用cstring_to_text）

PG_MODULE_MAGIC 是PostgreSQL 8.2中包含头文件fmgr.h后，模块源文件中的一个(且仅一个)中需要的魔法块。

PG_FUNCTION_INFO_V1(base36_encode);将该函数作为版本1调用约定引入Postges，只有在希望用到函数->Postgres接口时才需要。

Dtum是每个c语言Postgres函数的返回类型，可以是任何数据类型。你可以把它想象成类似于void *的东西。

base36_encode(PG_FUNCTION_ARGS) 我们的函数名，PG_FUNCTION_ARGS可以接受任何数字和任何类型的参数。

int32 arg = PG_GETARG_INT32(0);获取第一个参数，参数的编号从0开始。必须使用fmgr.h中定义的PG GETARG XXX宏来获取实际的参数值。

har *buffer = palloc(7 * sizeof(char));为了在分配内存时防止内存泄漏，总是使用PostgreSQL函数palloc和pfree，而不是相应的C库函数malloc和free。palloc分配的内存将在每个事务结束时自动释放。你也可以使用palloc0来确保字节清零。

PG_RETURN_TEXT_P(cstring_to_text(&buffer[offset]));要将一个值返回给Postgres，你必须使用一个PG_RETURN_XXX宏。cstring_to_text将cstring转换为Postgres文本类型。

完成c语言代码部分之后，需要修改SQL函数。

文件名：base36-0.0.1.sql

-- complain if script is sourced in psql, rather than via CREATE EXTENSION
\echo Use "CREATE EXTENSION base36" to load this file. \quit
CREATE FUNCTION base36_encode(integer) RETURNS text
AS '$libdir/base36'
LANGUAGE C IMMUTABLE STRICT;

为了能够使用该函数，我们还需要修改Makefile(第4行)

文件名：Makefile

EXTENSION = base36        # 扩展名称
DATA = base36--0.0.1.sql  # 要安装的脚本文件
REGRESS = base36_test     # 测试脚本文件 (没有后缀名)
MODULES = base36          # 要构建的c模块文件

# postgres build stuff
PG_CONFIG = pg_config
PGXS := $(shell $(PG_CONFIG) --pgxs)
include $(PGXS)

幸运的是，我们已经进行了测试，可以使用make install && make installcheck进行测试。 打开数据库控制台也证明它的速度要快很多（30倍）：

test=# SELECT i, base36_encode(i) FROM generate_series(1,1e6::int) i;
Time: 361,054 ms

返回错误

你可能已经注意到，我们的简单实现无法处理负数。就像之前处理0一样，它将返回一个空字符串。我们可能想要为负值添加一个负号，或者仅仅是错误输出。我们选后者吧。(12-20行)：
文件名：base36.c

#include "postgres.h"
#include "fmgr.h"
#include "utils/builtins.h"

PG_MODULE_MAGIC;

PG_FUNCTION_INFO_V1(base36_encode);
Datum
base36_encode(PG_FUNCTION_ARGS)
{
    int32 arg = PG_GETARG_INT32(0);
    if (arg < 0)
        ereport(ERROR,
            (
             errcode(ERRCODE_NUMERIC_VALUE_OUT_OF_RANGE),
             errmsg("negative values are not allowed"),
             errdetail("value %d is negative", arg),
             errhint("make it positive")
            )
        );
    char base36[36] = "0123456789abcdefghijklmnopqrstuvwxyz";

    /* max 6 char + '\0' */
    char *buffer = palloc(7 * sizeof(char));
    unsigned int offset = sizeof(buffer);
    buffer[--offset] = '\0';

    do {
        buffer[--offset] = base36[arg % 36];
    } while (arg /= 36);


    PG_RETURN_TEXT_P(cstring_to_text(&buffer[offset]));
}

这将会导致：

test=# SELECT base36_encode(-10);
ERROR:  negative values are not allowed
DETAIL:  value -10 is negative
HINT:  make it positive

Postgres内置了一些不错的错误报告功能。虽然对于这个用例来说，一个简单的错误消息就足够了，但是你可以(但不一定需要)添加细节、提示等等。

对于简单的调试，使用下面的形式也很方便：

elog(INFO, "value here is %d", value);

INFO级别错误只会产生日志消息，而不会立即停止函数调用。 严重级别从DEBUG到PANIC不等。

更多

既然我们已经了解了编写扩展和c语言函数的基础知识，在下一篇文章中，我们将进行下一步：实现一个全新的数据类型。

猜你喜欢

转载自www.cnblogs.com/taceywong/p/11269408.html
今日推荐
TIOBE 5 月榜单：Fortran “复活”进入 Top 10
GCC 14.1 发布
面壁智能发布 Eurux-8x22B 开源大模型 —— 堪称「理科状元」
开源日报 | 谷歌扶持鸿蒙上位；开源Rabbit R1；Docker加持的安卓手机；微软的焦虑和野心；海尔电器把开放平台关了
中国码农的“35岁魔咒”
蘭雅 CorelDRAW 插件 2024.5.1 国际劳动节版，免费下载
Arc Browser for Windows 1.0 正式 GA
90后程序员开发视频搬运软件、不到一年获利超 700 万，结局很刑！
周排行
Java自定义时间格式
同步整形电路
在开发中最最最常用的字符串的属性大集合
Linux 查看端口占用并杀掉
Java基础四：ArrayList
多线程之死锁就是这么简单
mysql 基础命令集
awk 命令详解
Centos6.3编译安装nginx+php步骤
OCR （Optical Character Recognition，光学字符识别）
每日归档
更多
2024-05-08(42)
2024-05-07(14)
2024-05-06(40)
2024-05-05(0)
2024-05-04(7)
2024-05-03(19)
2024-05-02(0)
2024-05-01(4)
2024-04-30(1)
2024-04-29(40)

代码天地 © 2018 codetd.com

境外服务器   最新电视剧2022