数据库函数（Database Function）

场景介绍

建表用于数据存储，增删改查实现数据读写，行级安全控制数据按行可见可控。然而，并非所有需求都能归结为“读写某一行”：跨表统计需聚合多张表的数据，上下架需在同一事务内写入多张表，更新时间需在数据变更时自动刷新。这类逻辑难以用单条SQL表达，需流程控制或自动触发，Data API的自动接口无法覆盖；若交由应用侧实现，则前后端需反复对齐字段与逻辑，一处变更往往波及多处。

本章节介绍的数据库函数（Database Function）即存储过程，用SQL或PL/pgSQL把业务逻辑封装成可复用的过程，写入数据库、供应用按需调用。跨表聚合、事务联动、数据校验、变更自动触发、受控对外开放等，皆可一次定义、在数据侧执行，经PostgREST暴露为RPC接口、由前端.rpc()直接调用；也可绑定为触发器，在数据变更时自动执行（如updated_at自动刷新）。

相关概念

更多详细介绍，请参见参考文档。

• 数据库函数

  数据库函数（Database Function）是保存在PostgreSQL数据库中、可被调用的程序（即存储过程），接收输入参数、在数据库内执行、返回结果。它与Data API的CRUD互补：CRUD面向单表读写，函数面向难以用单条SQL表达，需流程控制、事务保障、或自动触发的场景。函数在数据库侧执行，可调用PostgreSQL全部能力（JSONB、窗口函数、事务、其他函数与触发器等）。

• 函数语言

  表1 函数语言

  语言	特点	适用
  sql	单条SQL查询即可完成，无流程控制，简单高效。	查询、计算、关联封装。
  plpgsql	支持变量、分支、循环、异常处理、事务控制。	多步骤逻辑、条件判断、批量处理。

  二者均为PostgreSQL内置语言。SQL直接以标准SQL查询作为函数体，不含控制流，适合直接封装查询；plpgsql即PL/pgSQL，是PostgreSQL的过程化语言，在SQL之上扩展变量、分支、循环与异常处理，可承载多步骤与条件逻辑，详见PostgreSQL过程语言。简单封装优先用SQL，需流程控制再用plpgsql。

• 返回类型

  表2 常用返回类型

  返回类型	说明	典型场景
  void	无返回值。	仅执行写入或更新，如批量维护。
  标量（bigint、numeric、text等）	返回单个值。	计数、最值、计算结果。
  SETOF	返回某表的若干行。	返回符合条件的数据集合。
  TABLE(字段 类型, …)	返回自定义结构的多行。	多表关联、计算列的集合结果。
  trigger	专供触发器调用。	自动维护字段、审计、校验。

  返回集合（SETOF/TABLE）的函数，其结果可经RPC查询，并支持与表相同的链式过滤、分页。

• 安全模式

  函数按“以谁的权限执行”分两种安全模式，直接决定是否受RLS约束。

  表3 安全模式

  模式	执行权限	是否受RLS约束	适用
  SECURITY INVOKER（默认）	调用者	受约束	只处理调用者本就有权访问的数据。
  SECURITY DEFINER	函数属主（通常绕过RLS）	绕过RLS	需以高权限完成特定操作，且要收口权限。

  SECURITY DEFINER以属主权限执行并可绕过RLS，虽然便捷但有一定风险。PostgreSQL默认向PUBLIC授予执行权限，位于public模式的SECURITY DEFINER函数可被anon、authenticated角色调用，等同于一个公开的高权限入口。SECURITY DEFINER仅在确实需要绕过RLS时才使用，并务必遵守以下限制：

  • REVOKE ... FROM PUBLIC收回默认执行权。
  • 仅GRANT EXECUTE给目标角色。
  • 函数体内以auth.uid()校验调用者。
  • 用SET search_path锁定模式，防止同名对象被劫持。
• 调用方式

  支持RPC与触发器（Trigger）两种调用方式。

  表4 调用方式

  方式	触发时机	调用方
  RPC	应用主动调用。	前端/服务端经SDK的.rpc()，按需传参获取结果。
  触发器（Trigger）	数据变更时自动执行。	绑定到表的INSERT/UPDATE/DELETE，无需应用介入。

  返回Trigger类型的函数专供触发器调用，不能经RPC使用；普通函数可经RPC调用，但不能直接绑定为触发器。

函数和CRUD的使用场景

数据库函数并非替代Data API的CRUD，而是承接CRUD覆盖不到的复杂逻辑。表5介绍适用于函数和CRUD的场景。

核心价值：复杂逻辑封装复用、事务一致性、自动触发、受控开放。

函数的创建方式

创建数据库函数有两种创建方式：在Dashboard的SQL Editor中编写CREATE FUNCTION语句执行，或在“Database > Functions”页面用图形表单填写创建。二者创建的是同一类数据库对象，可搭配使用。

选型建议：简单函数可在“Database > Functions”页面快速创建雏形；复杂逻辑、SECURITY DEFINER权限收口、触发器函数一律用SQL Editor。

函数调用（RPC方式）

定义在public等已暴露模式下的函数经PostgREST自动暴露为RPC接口（RPC即远程过程调用，此处指经HTTP接口调用数据库函数），前端可通过Supabase SDK来进行rpc()调用。以下示例代码以JavaScript语言进行说明。

调用权限遵循与CRUD相同的规则：以Publishable Key未登录发起时以anon身份执行（受RLS约束），登录后以authenticated执行；SECURITY DEFINER函数则按属主权限执行。

1. 无参调用

   示例场景：获取全部产品及其定价清单。

   const { data, error } = await supabase.rpc('get_products_with_pricing')
   if (error) { console.error(error); return }
   // data示例：[{ id: 1, name: '云服务器 ECS', category: '计算', tier: '包月', price: 99.00 }, ...]

   无参函数调用时第二参数可省略。返回值结构与函数RETURNS TABLE定义一一对应。

2. 带参调用

   示例场景：查询id为1的产品的最低价。

   // 按命名参数传参（推荐，参数名与定义一致）
   const { data, error } = await supabase.rpc('get_min_price', { pid: 1 })
   if (error) { console.error(error); return }
   // data为函数返回的标量，如0或99.00
   
   // 统计某分类产品数量
   const { data: count } = await supabase.rpc('get_product_count_by_category', { cat: '计算' })

   .rpc()第二参数为对象，键名对应函数的参数名；PostgREST据此按命名参数绑定，无需关注位置。

3. 结果过滤与分页

   返回集合的函数结果支持与表相同的链式过滤、排序、分页，避免将全部数据传输至前端再筛选。

   示例场景：从产品定价清单中只取计算类、按名称排序的前10条。

   // 对get_products_with_pricing()结果链式过滤、排序、分页
   const { data, error } = await supabase
     .rpc('get_products_with_pricing')
     .eq('category', '计算')
     .order('name')
     .limit(10)

   .eq()、.order()、.limit()等链式方法作用于函数返回的集合，用法与表查询一致，详见数据库API（Database Data API）中SDK基本操作。

触发器函数（数据变更自动执行）

触发器函数返回Trigger类型，在数据变更时由数据库自动执行，无需应用调用。它常用于把“数据变更、自动处理”的需求交给数据库自动完成。在数据库API（Database Data API）中提到updated_at仅在插入时取默认值、修改时不会自动刷新，要实现自动刷新需借助触发器，这正是其典型用法之一。

1. 字段自动维护

   示例场景：产品信息被修改时，自动把updated_at刷新为当前时间，避免应用每次更新都手动传值。

   先定义返回trigger的函数。

   CREATE OR REPLACE FUNCTION set_updated_at()
   RETURNS trigger
   LANGUAGE plpgsql
   AS $$
   BEGIN
     NEW.updated_at = now();   -- 将新行updated_at置为当前时间
     RETURN NEW;               -- 返回新行，使其继续写入
   END;
   $$;

   再将其绑定到目标表的UPDATE。

   CREATE TRIGGER trg_products_updated_at
     BEFORE UPDATE ON products      -- 更新前执行，改写updated_at
     FOR EACH ROW                  -- 每行触发
     EXECUTE FUNCTION set_updated_at();

   此后对products执行任何UPDATE，updated_at都会自动刷新，无需应用层干预。products表已有updated_at列，可直接绑定；product_pricings表无该列，如需同样自动维护，先为其增加列再绑定同一触发器。

   -- 为product_pricings增加updated_at列（原表仅有created_at）
   ALTER TABLE product_pricings ADD COLUMN updated_at TIMESTAMPTZ DEFAULT now();
   
   CREATE TRIGGER trg_pricings_updated_at
     BEFORE UPDATE ON product_pricings
     FOR EACH ROW
     EXECUTE FUNCTION set_updated_at();

   注意：触发器函数不能经RPC调用；BEFORE返回NEW使修改生效、返回NULL则取消该行操作。触发器也可在Dashboard的Triggers界面可视化管理，详见数据库触发器（Trigger）。

2. 变更审计

   示例场景：记录产品价格变更前后的值，便于追溯。先建审计表，再以触发器在更新时写入。

   CREATE TABLE product_price_audit (
     id          BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
     product_id  BIGINT NOT NULL,
     old_price   NUMERIC(10,2),
     new_price   NUMERIC(10,2),
     changed_at  TIMESTAMPTZ DEFAULT now()
   );
   
   CREATE OR REPLACE FUNCTION log_price_change()
   RETURNS trigger
   LANGUAGE plpgsql
   AS $$
   BEGIN
     IF NEW.price IS DISTINCT FROM OLD.price THEN   -- 仅价格变化才记录
       INSERT INTO product_price_audit (product_id, old_price, new_price)
       VALUES (NEW.product_id, OLD.price, NEW.price);
     END IF;
     RETURN NEW;
   END;
   $$;
   
   CREATE TRIGGER trg_pricing_audit
     AFTER UPDATE ON product_pricings   -- 更新后记录，确保新值已落库
     FOR EACH ROW
     EXECUTE FUNCTION log_price_change();

   注意：AFTER确保数据已写入再审计；IS DISTINCT FROM可安全比较含NULL的值；审计表可单独配RLS，仅运维可见。

管理与维护

函数与触发器创建后的查看、修改、删除、缓存刷新等日常管理，主要通过SQL Editor与Database两个入口完成。

1. 查看函数。

   进入“Database > Functions”，列出当前schema下的函数，可查看其名称、参数、返回类型与定义。界面以查看为主，同时支持可视化创建，详见方式二：用“Database > Functions”图形界面创建；函数体的修改与迭代建议在SQL Editor完成，详见方式一：用SQL Editor编写SQL创建（推荐使用、完整可控）。

2. 修改与删除函数。

   修改函数：函数用CREATE OR REPLACE FUNCTION覆写，既可在SQL Editor修改SQL重跑，也可在“Database > Functions”表单编辑。修改后须刷新schema缓存，详见3。

   删除函数：不再需要的函数通过DROP FUNCTION删除，须带参数类型以区分同名重载函数。

   DROP FUNCTION get_min_price(bigint);

3. 刷新schema缓存。

   创建或修改函数后，须刷新PostgREST的schema缓存，函数才对RPC可见（首次可能有数秒延迟）。

   NOTIFY pgrst, 'reload schema';

4. 管理触发器。

   进入“Database > Triggers”页面，可视化创建触发器：选择目标表、触发时机（BEFORE/AFTER）、事件（INSERT/UPDATE/DELETE）、绑定触发器函数。也可在该页面启用、禁用或删除已有触发器。

   注意：SECURITY DEFINER函数的权限收口（REVOKE/GRANT）须以SQL执行，详见方式一：用SQL Editor编写SQL创建（推荐使用、完整可控），界面不提供此类操作的图形入口。

综合案例

示例场景：运营需要一个“产品概览”接口，按分类汇总产品数量、最低价格及最高价格，供后台看板展示。由于涉及多表关联聚合，CRUD难以一次性表达，使用函数封装最为合适。

定义函数：按分类聚合，关联定价表取价格区间。

CREATE OR REPLACE FUNCTION get_category_summary()
RETURNS TABLE (
  category      text,
  product_count bigint,
  min_price     numeric,
  max_price     numeric
)
LANGUAGE sql
AS $$
  SELECT p.category,
         count(DISTINCT p.id),
         min(pr.price),
         max(pr.price)
  FROM products p
  LEFT JOIN product_pricings pr ON pr.product_id = p.id
  GROUP BY p.category
  ORDER BY p.category;
$$;

刷新缓存并由SDK调用（以JavaScript为例）：

NOTIFY pgrst, 'reload schema';

const { data, error } = await supabase.rpc('get_category_summary')
if (error) { console.error(error); return }
// data示例：
// [
//   { category: '计算', product_count: 2, min_price: 99.00, max_price: 588.00 },
//   { category: '存储', product_count: 1, min_price: 45.00, max_price: 45.00 }
// ]

如需只看某一类，可在结果上链式过滤，也可改造函数加分类参数：

// 复用3中的链式过滤：只看"计算"类
const { data } = await supabase.rpc('get_category_summary').eq('category', '计算')

本案例将“多表关联+聚合+排序”一次封装进数据库，前端仅需一次RPC即可获得聚合结果，无需自建后端接口，也无需将明细传输至前端再统计。

参考文档

以下为Supabase开源相关文档，仅供参考。

• Supabase数据库函数
• Supabase JavaScript SDK — rpc
• PostgreSQL — CREATE FUNCTION
• PostgreSQL — 触发器