41、PostgreSQL扩展开发：C语言编写扩展、CREATE EXTENSION、自定义数据类型、自定义操作符

说实话，PostgreSQL最让我着迷的地方，就是它的扩展能力。你想想看，一个数据库系统，居然允许你用C语言给它“加料”——定义自己的数据类型、自己的操作符，甚至自己的索引方法。这就像给你一把瑞士军刀，你还能自己打造刀片装上去。

我记得刚接触PG扩展开发那会儿，心里还挺怵的。毕竟要用C语言跟数据库内核打交道，万一写崩了，整个库都可能挂掉。但后来我发现，只要遵循一套固定的模板，这事儿其实比想象中简单。今天我就带你走一遍完整的流程。

扩展开发的基本骨架

每个PG扩展，本质上就是一个动态链接库（.so文件），加上一组控制文件。我习惯把扩展项目组织成下面这样：

my_extension/
├── my_extension.c      # C源码，实现核心逻辑
├── my_extension.control # 控制文件，告诉PG扩展的元信息
├── my_extension--1.0.sql # SQL脚本，定义数据类型、操作符、函数
└── Makefile            # 编译规则

这个结构很固定。你只要照着这个架子搭，基本不会出错。我曾经因为忘记写.control文件，折腾了半小时才找到原因——嗯，这种低级错误犯过一次就记住了。

第一步：写C代码

假设我们要定义一个叫complex的复数类型，支持加法和乘法。先看C代码：

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

PG_MODULE_MAGIC;  // 必须，声明这是一个PG扩展模块

// 复数结构体
typedef struct Complex {
    double x;  // 实部
    double y;  // 虚部
} Complex;

// 输入函数：从字符串解析复数
PG_FUNCTION_INFO_V1(complex_in);
Datum complex_in(PG_FUNCTION_ARGS) {
    char *str = PG_GETARG_CSTRING(0);
    double x, y;
    Complex *result;

    // 简单解析 "x,y" 格式
    if (sscanf(str, "%lf,%lf", &x, &y) != 2)
        ereport(ERROR, (errmsg("invalid input syntax for complex: \"%s\"", str)));

    result = (Complex *)palloc(sizeof(Complex));
    result->x = x;
    result->y = y;
    PG_RETURN_POINTER(result);
}

// 输出函数：将复数转为字符串
PG_FUNCTION_INFO_V1(complex_out);
Datum complex_out(PG_FUNCTION_ARGS) {
    Complex *c = (Complex *)PG_GETARG_POINTER(0);
    char *result = palloc(64);
    snprintf(result, 64, "%.2f,%.2f", c->x, c->y);
    PG_RETURN_CSTRING(result);
}

// 加法操作符
PG_FUNCTION_INFO_V1(complex_add);
Datum complex_add(PG_FUNCTION_ARGS) {
    Complex *a = (Complex *)PG_GETARG_POINTER(0);
    Complex *b = (Complex *)PG_GETARG_POINTER(1);
    Complex *result = (Complex *)palloc(sizeof(Complex));

    result->x = a->x + b->x;
    result->y = a->y + b->y;
    PG_RETURN_POINTER(result);
}

这里有几个关键点：

• PG_MODULE_MAGIC 是必须的，少了它PG加载时会报错。
• 所有暴露给SQL的函数，都要用 PG_FUNCTION_INFO_V1 宏声明。
• 内存分配用 palloc，不要用 malloc。palloc分配的内存由PG的内存上下文管理，不会泄漏。
• 输入/输出函数是自定义类型的“门面”——PG通过它们把字符串和内部结构互相转换。

第二步：写控制文件和SQL脚本

控制文件很简单，告诉PG这个扩展叫什么、版本号多少：

# my_extension.control
comment = 'Complex number extension'
default_version = '1.0'
module_pathname = '$libdir/my_extension'
relocatable = true

SQL脚本才是重头戏。它定义了数据类型、操作符、以及它们与C函数的映射关系：

-- my_extension--1.0.sql
CREATE TYPE complex (
    internallength = 16,      -- 两个double，共16字节
    input = complex_in,       -- 输入函数
    output = complex_out,     -- 输出函数
    alignment = double        -- 按double对齐
);

-- 定义加法操作符
CREATE OPERATOR + (
    leftarg = complex,
    rightarg = complex,
    function = complex_add,
    commutator = +           -- 交换律，优化器会用
);

-- 为了方便，再定义一个构造函数的SQL函数
CREATE FUNCTION complex_make(double, double)
RETURNS complex
AS 'MODULE_PATHNAME', 'complex_make'
LANGUAGE C IMMUTABLE STRICT;

注意看 CREATE TYPE 的语法。我刚开始写的时候，总搞不清 internallength 该填多少。其实很简单——你C结构体多大，就填多大。对于 Complex 结构体，两个double是16字节，所以填16。

第三步：编译和安装

Makefile 可以复用PG官方提供的模板：

# Makefile
MODULES = my_extension
EXTENSION = my_extension
DATA = my_extension--1.0.sql
PG_CONFIG = pg_config
PGXS := $(shell $(PG_CONFIG) --pgxs)
include $(PGXS)

然后执行：

make
make install

安装完成后，在数据库中执行：

CREATE EXTENSION my_extension;

如果一切顺利，你就可以像使用内置类型一样使用 complex 了：

SELECT (1.0,2.0)::complex + (3.0,4.0)::complex;
-- 结果: (4.00,6.00)

自定义操作符的进阶玩法

除了基本的加减乘除，你还可以定义一些“花哨”的操作符。比如，我想让复数支持取模运算 @>：

-- C函数
PG_FUNCTION_INFO_V1(complex_abs);
Datum complex_abs(PG_FUNCTION_ARGS) {
    Complex *c = (Complex *)PG_GETARG_POINTER(0);
    double result = sqrt(c->x * c->x + c->y * c->y);
    PG_RETURN_FLOAT8(result);
}

-- SQL定义
CREATE OPERATOR @> (
    rightarg = complex,
    function = complex_abs
);

然后就可以这样用：

SELECT @> (3.0,4.0)::complex;  -- 返回 5.0

操作符的符号可以自己选，但最好别跟PG内置的操作符冲突。我一般用一些特殊符号组合，比如 #@、|> 之类的，避免歧义。

知识体系总览

下面这张图概括了PG扩展开发的完整流程和各个组件的关系：

避坑指南

做了这么多年扩展开发，我踩过的坑能写满一页纸。挑几个最常见的说说：

• 内存泄漏：C代码里用了 malloc 而不是 palloc。palloc由PG管理，事务结束自动释放。malloc不会，时间长了内存就爆了。
• 版本兼容性：不同PG主版本之间，内部API可能有变化。我建议你针对目标PG版本编译，不要拿PG14的.so文件放到PG15上用。
• 操作符优先级：自定义操作符的优先级默认是最低的。如果你想让操作符有更高的优先级，需要在 CREATE OPERATOR 里指定 PRIORITY 参数。
• 并行安全：如果你的函数不是线程安全的，记得在SQL定义里加上 PARALLEL UNSAFE，否则PG可能会在并行查询中调用它，导致数据错乱。

PostgreSQL的扩展机制，说白了就是让你用C语言给数据库“开外挂”。一旦掌握了这套流程，你就能把任何业务逻辑塞进数据库内核里。我个人觉得，这是PG相比其他数据库最大的优势之一。下次遇到复杂的数据类型需求，别犹豫，自己写个扩展吧。

---