tencentdb_scf

tencentdb_scf 是腾讯云 PostgreSQL 专用扩展，让用户可以通过 SQL 安全、受控地调用 CloudBase 云函数，满足数据库定时任务、触发器或业务 SQL 触发云函数的场景，同时避免开放通用 HTTP 扩展带来的 SSRF、网络穿透和攻击代理风险。

扩展安装

tencentdb_scf 依赖 pgcrypto 扩展，安装前需先启用 pgcrypto：

CREATE EXTENSION IF NOT EXISTS pgcrypto;
CREATE EXTENSION IF NOT EXISTS tencentdb_scf;

扩展固定安装到 tencentdb_scf schema。如果没有设置 search_path，建议使用 schema 前缀调用，例如 tencentdb_scf.tencentdb_scf_post(...)。也可以设置搜索路径简化调用：

SET search_path = tencentdb_scf, public;

核心 API

配置 CloudBase 环境

使用前需要配置 CloudBase 环境 ID 和 API Key：

SELECT tencentdb_scf.set_cloudbase_env_id('your-env-id');
SELECT tencentdb_scf.set_cloudbase_api_key('your-cloudbase-api-key');

set_cloudbase_env_id

设置 CloudBase 环境 ID，配置持久化到 tencentdb_scf.config 表。

语法：

tencentdb_scf.set_cloudbase_env_id(env_id TEXT) RETURNS BOOLEAN

入参约束：

不能为空
长度不能超过 128
不能以 - 开头
只能包含小写字母、数字和减号

set_cloudbase_api_key

设置 CloudBase API Key，通过 pgcrypto PGP 对称加密后持久化保存。

语法：

tencentdb_scf.set_cloudbase_api_key(key TEXT) RETURNS BOOLEAN

入参约束：

不能为空
长度不能超过 4096
不能包含控制字符

发起云函数调用

向 CloudBase 云函数网关发起 POST 请求。

语法：

tencentdb_scf.tencentdb_scf_post(
    path TEXT,
    headers JSONB DEFAULT '{}'::jsonb,
    body TEXT DEFAULT '',
    sync BOOLEAN DEFAULT true,
    timeout_milliseconds INT DEFAULT 5000
) RETURNS BIGINT

参数说明：

参数	类型	默认值	说明
`path`	TEXT	必填	CloudBase 云函数路径，必须以 `/v1/functions/` 开头
`headers`	JSONB	`'{}'`	自定义请求头（敏感头会被自动过滤）
`body`	TEXT	`''`	请求体内容
`sync`	BOOLEAN	`true`	`true` 为同步调用，`false` 为异步调用
`timeout_milliseconds`	INT	`5000`	请求超时时间（毫秒）

返回值：BIGINT 类型的请求 ID，可通过此 ID 查询调用结果。

path 约束：

不能为空
必须以 /v1/functions/ 开头
总长度不能超过 512
函数名不能为空，必须以字母开头
函数名只能包含英文字母、数字、减号和下划线
函数名不能以减号或下划线结尾

正确示例：

/v1/functions/myFunction

错误示例：

/functions/myFunction                    -- 缺少 /v1 前缀
https://xxx.api.tcloudbasegateway.com/... -- 不能传完整 URL
/v1/functions/1bad                       -- 函数名不能以数字开头
/v1/functions/bad_                       -- 函数名不能以下划线结尾
/v1/functions/bad.path                   -- 函数名不能包含点号

查询调用结果

根据请求 ID 查询调用结果。

语法：

tencentdb_scf.tencentdb_scf_result(req_id BIGINT) RETURNS JSONB

返回 JSONB，包含响应状态码、响应类型、响应头、响应体、是否超时、错误信息和创建时间等字段。如果请求尚未完成或响应已被 TTL 清理，返回 NULL。

使用示例

同步调用

同步模式是默认模式，适用于需要立即确认调用结果、云函数执行时间较短的场景。

-- 发起同步调用，记录返回的请求 ID
SELECT tencentdb_scf.tencentdb_scf_post(
    path := '/v1/functions/sendNotification',
    headers := jsonb_build_object('X-Custom-Header', 'value'),
    body := json_build_object('action', 'sendEmail', 'to', 'admin@example.com')::text,
    sync := true,
    timeout_milliseconds := 5000
) AS request_id;
-- 使用上一步返回的 request_id 查询结果
SELECT tencentdb_scf.tencentdb_scf_result(<request_id>);

异步调用

异步模式适用于触发器、批量任务、定时任务等不希望阻塞主流程的场景。异步请求先写入 tencentdb_scf.request_queue，由 Background Worker 消费执行，事务提交后唤醒 worker。

如果事务回滚，未提交的请求不会被 worker 消费。

-- 发起异步调用，记录返回的请求 ID
SELECT tencentdb_scf.tencentdb_scf_post(
    path := '/v1/functions/heavyTask',
    headers := '{}'::jsonb,
    body := json_build_object('dataset', 'large')::text,
    sync := false,
    timeout_milliseconds := 30000
) AS request_id;
-- 稍后使用上一步返回的 request_id 查询结果
SELECT tencentdb_scf.tencentdb_scf_result(<request_id>);

配合 pg_cron 定时调用

CREATE OR REPLACE FUNCTION trigger_daily_cleanup()
RETURNS void AS $$
BEGIN
    PERFORM tencentdb_scf.tencentdb_scf_post(
        path := '/v1/functions/dailyCleanup',
        headers := '{}'::jsonb,
        body := json_build_object(
            'action', 'cleanup',
            'timestamp', now()::text
        )::text,
        sync := false,
        timeout_milliseconds := 15000
    );
END;
$$ LANGUAGE plpgsql;

SELECT cron.schedule(
    'daily-cleanup',
    '0 2 * * *',
    'SELECT trigger_daily_cleanup()'
);

安全设计

URL 收敛

用户 SQL 只接收 path，完整 URL 由扩展拼接：

https://<env_id>.api.tcloudbasegateway.com<path>

由于 env_id 只允许小写字母、数字和减号，用户无法通过 env_id 注入协议、端口、路径或其他 URL 结构字符。

请求校验

请求执行前调用 checkurl SDK 校验，仅允许 HTTPS 协议和 api.tcloudbasegateway.com 及其子域名
同步和异步路径均限制协议为 HTTPS，禁止 30x 自动重定向
服务端固定注入 Authorization: Bearer <api_key> 和 Content-Type: application/json

请求头保护

用户可以通过 headers JSONB 传入自定义请求头，但以下敏感或协议语义相关请求头会被过滤：

Authorization
Host
Cookie
X-Forwarded-For
X-Forwarded-Host
X-Forwarded-Proto
Content-Type

用户不需要、也不应在 headers 中重复传入认证信息或 Content-Type。当前版本固定使用 Content-Type: application/json，不允许用户填写、追加或覆盖 Content-Type，避免重复请求头导致网关或云函数侧请求体解析语义不一致。

内部对象

扩展在 tencentdb_scf schema 下创建以下内部表：

表	用途
`config`	保存 CloudBase 环境 ID 与 API Key（API Key 经 pgcrypto 加密）
`request_queue`	异步请求队列，由 `tencentdb_scf_post(..., sync := false)` 写入
`_http_response`	保存同步和异步请求结果，`tencentdb_scf_result` 从此表查询

注意事项

默认不影响已有实例，需要显式安装扩展并配置 CloudBase 环境 ID 与 API Key
当前仅支持 POST 方法，不支持 GET、PUT、DELETE 等其他 HTTP 方法
当前仅允许 CloudBase 网关域名，不支持任意外网域名访问
当前版本尚未实现并发、QPS、请求体大小、响应体大小等资源限制 GUC
当前版本尚未实现专用审计日志接入

扩展安装​

核心 API​

配置 CloudBase 环境​

set_cloudbase_env_id​

set_cloudbase_api_key​

发起云函数调用​

查询调用结果​

使用示例​

同步调用​

异步调用​

配合 pg_cron 定时调用​

安全设计​

URL 收敛​

请求校验​

请求头保护​

内部对象​

注意事项​