在 Ent Schema 中使用数据库触发器

触发器是关系数据库中的实用工具，它允许您在表上发生特定事件时执行自定义代码。例如，当对另一个表应用新变更时，触发器可以自动填充审计日志表。通过这种方式，我们可以确保所有变更（包括由其他应用程序发起的变更）都被详细记录，从而在数据库级别实施强制规范，并减少应用程序中的额外代码需求。

本指南将介绍如何将触发器附加到您的 Ent 类型（对象）上，并配置 schema 迁移，以便使用 Atlas 将触发器和 Ent schema 作为一个完整的迁移单元进行管理。

Atlas Pro 功能

本指南中使用的 Triggers 功能仅供 Atlas Pro 用户使用。要使用此功能，请运行：

atlas login

安装 Atlas

To install the latest release of Atlas, simply run one of the following commands in your terminal, or check out the Atlas website:

macOS + Linux
Homebrew
Docker
Windows

curl -sSf https://atlasgo.sh | sh

brew install ariga/tap/atlas

docker pull arigaio/atlas
docker run --rm arigaio/atlas --help

If the container needs access to the host network or a local directory, use the --net=host flag and mount the desired directory:

docker run --rm --net=host \
  -v $(pwd)/migrations:/migrations \
  arigaio/atlas migrate apply
  --url "mysql://root:pass@:3306/test"

登录 Atlas

$ atlas login a8m
您已成功连接到 Atlas Cloud 上的 "a8m" 账户。

组合式 Schema（Composite Schema）

ent/schema 包主要用于定义 Ent 类型（对象）、字段、边（edge）及其逻辑。表触发器或任何其他数据库原生对象在 Ent 模型中并没有对应的表示。一个触发器函数可以定义一次，然后在不同表的多个触发器中重复使用。

为了扩展我们的 PostgreSQL schema 以同时包含 Ent 类型及其触发器，我们配置 Atlas 从组合式 Schema 数据源读取 schema 的状态。请按照以下步骤为您的项目进行配置：

首先，我们定义一个包含两种类型（表）的简单 schema：users 和 user_audit_logs：

ent/schema/user.go
// User 保存了 User 实体的 schema 定义。
type User struct {
    ent.Schema
}

// User 的字段。
func (User) Fields() []ent.Field {
    return []ent.Field{
        field.String("name"),
    }
}

// UserAuditLog 保存了 UserAuditLog 实体的 schema 定义。
type UserAuditLog struct {
    ent.Schema
}

// UserAuditLog 的字段。
func (UserAuditLog) Fields() []ent.Field {
    return []ent.Field{
        field.String("operation_type"),
        field.String("operation_time"),
        field.String("old_value").
            Optional(),
        field.String("new_value").
            Optional(),
    }
}

现在，假设我们希望记录对 users 表的每次更改，并将其保存到 user_audit_logs 表中。为了实现这一点，我们需要为 INSERT、UPDATE 和 DELETE 操作创建一个触发器函数，并将其附加到 users 表。

接下来，我们定义一个触发器函数 (audit_users_changes)，并使用 CREATE TRIGGER 命令将其附加到 users 表：

schema.sql
-- 用于审计 users 表变更的函数。
CREATE OR REPLACE FUNCTION audit_users_changes()
RETURNS TRIGGER AS $$
BEGIN
    IF (TG_OP = 'INSERT') THEN
        INSERT INTO user_audit_logs(operation_type, operation_time, new_value)
        VALUES (TG_OP, CURRENT_TIMESTAMP, row_to_json(NEW));
        RETURN NEW;
    ELSIF (TG_OP = 'UPDATE') THEN
        INSERT INTO user_audit_logs(operation_type, operation_time, old_value, new_value)
        VALUES (TG_OP, CURRENT_TIMESTAMP, row_to_json(OLD), row_to_json(NEW));
        RETURN NEW;
    ELSIF (TG_OP = 'DELETE') THEN
        INSERT INTO user_audit_logs(operation_type, operation_time, old_value)
        VALUES (TG_OP, CURRENT_TIMESTAMP, row_to_json(OLD));
        RETURN OLD;
    END IF;
    RETURN NULL;
END;
$$ LANGUAGE plpgsql;

-- INSERT 操作的触发器。
CREATE TRIGGER users_insert_audit AFTER INSERT ON users FOR EACH ROW EXECUTE FUNCTION audit_users_changes();

-- UPDATE 操作的触发器。
CREATE TRIGGER users_update_audit AFTER UPDATE ON users FOR EACH ROW EXECUTE FUNCTION audit_users_changes();

-- DELETE 操作的触发器。
CREATE TRIGGER users_delete_audit AFTER DELETE ON users FOR EACH ROW EXECUTE FUNCTION audit_users_changes();

最后，我们创建一个简单的 atlas.hcl 配置文件，其中包含一个 composite_schema，该 schema 同时包含了我们的 Ent schema 和在 schema.sql 中定义的自定义触发器：

atlas.hcl
data "composite_schema" "app" {
  # 首先加载包含所有表的 ent schema。
  schema "public" {
    url = "ent://ent/schema"
  }
  # 然后，加载触发器 schema。
  schema "public" {
    url = "file://schema.sql"
  }
}

env "local" {
  src = data.composite_schema.app.url
  dev = "docker://postgres/15/dev?search_path=public"
}

使用

设置好组合式 schema 后，我们可以使用 atlas schema inspect 命令获取其表示形式，为其生成 schema 迁移，将其应用到数据库等等。以下是一些帮助您开始使用 Atlas 的命令：

检查 Schema

atlas schema inspect 命令通常用于检查数据库。但是，我们也可以使用它来检查我们的 composite_schema 并打印其 SQL 表示形式：

atlas schema inspect \
  --env local \
  --url env://src \
  --format '{{ sql . }}'

上面的命令会打印以下 SQL。请注意，audit_users_changes 函数和触发器定义在 users 和 user_audit_logs 表之后：

-- 创建 "user_audit_logs" 表
CREATE TABLE "user_audit_logs" ("id" bigint NOT NULL GENERATED BY DEFAULT AS IDENTITY, "operation_type" character varying NOT NULL, "operation_time" character varying NOT NULL, "old_value" character varying NULL, "new_value" character varying NULL, PRIMARY KEY ("id"));
-- 创建 "users" 表
CREATE TABLE "users" ("id" bigint NOT NULL GENERATED BY DEFAULT AS IDENTITY, "name" character varying NOT NULL, PRIMARY KEY ("id"));
-- 创建 "audit_users_changes" 函数
CREATE FUNCTION "audit_users_changes" () RETURNS trigger LANGUAGE plpgsql AS $$
BEGIN
    IF (TG_OP = 'INSERT') THEN
        INSERT INTO user_audit_logs(operation_type, operation_time, new_value)
        VALUES (TG_OP, CURRENT_TIMESTAMP, row_to_json(NEW));
        RETURN NEW;
    ELSIF (TG_OP = 'UPDATE') THEN
        INSERT INTO user_audit_logs(operation_type, operation_time, old_value, new_value)
        VALUES (TG_OP, CURRENT_TIMESTAMP, row_to_json(OLD), row_to_json(NEW));
        RETURN NEW;
    ELSIF (TG_OP = 'DELETE') THEN
        INSERT INTO user_audit_logs(operation_type, operation_time, old_value)
        VALUES (TG_OP, CURRENT_TIMESTAMP, row_to_json(OLD));
        RETURN OLD;
    END IF;
    RETURN NULL;
END;
$$;
-- 创建触发器 "users_delete_audit"
CREATE TRIGGER "users_delete_audit" AFTER DELETE ON "users" FOR EACH ROW EXECUTE FUNCTION "audit_users_changes"();
-- 创建触发器 "users_insert_audit"
CREATE TRIGGER "users_insert_audit" AFTER INSERT ON "users" FOR EACH ROW EXECUTE FUNCTION "audit_users_changes"();
-- 创建触发器 "users_update_audit"
CREATE TRIGGER "users_update_aud極" AFTER UPDATE ON "users" FOR EACH ROW EXECUTE FUNCTION "audit_users_changes"();

为 Schema 生成迁移

要为 schema 生成迁移，请运行以下命令：

atlas migrate diff \
  --env local

请注意，这会创建一个新的迁移文件，其内容如下：

migrations/20240712090543.sql
-- 创建 "user_audit_logs" 表
CREATE TABLE "user_aud极 logs" ("id" bigint NOT NULL GENERATED BY DEFAULT AS IDENTITY, "operation_type" character varying NOT NULL, "operation_time" character varying NOT NULL, "old_value" character varying NULL, "new_value" character varying NULL, PRIMARY KEY ("id"));
-- 创建 "users" 表
CREATE TABLE "users" ("极" bigint NOT NULL GENERATED BY DEFAULT AS IDENTITY, "name" character varying NOT NULL, PRIMARY KEY ("id"));
-- 创建 "audit_users_changes" 函数
CREATE FUNCTION "audit_users_changes" () RETURNS trigger LANGUAGE plpgsql AS $$
BEGIN
    IF (TG_OP = 'INSERT') THEN
        INSERT INTO user_audit_logs(operation_type, operation_time, new_value)
        VALUES (TG_OP, CURRENT_TIMESTAMP, row_to_json(NEW));
        RETURN NEW;
    ELSIF (TG_OP = 'UPDATE') THEN
        INSERT INTO user_audit_logs(operation_type, operation极, old_value, new_value)
        VALUES (TG_OP, CURRENT_TIMESTAMP, row_to_json(OLD), row_to_json(NEW));
        RETURN NEW;
    ELSIF (TG_OP = 'DELETE') THEN
        INSERT INTO user_audit_logs(operation_type, operation_time, old_value)
        VALUES (TG_OP, CURRENT_TIMESTAMP, row_to_json(OLD));
        RETURN OLD;
    END IF;
    RETURN NULL;
END;
$$;
-- 创建触发器 "users_delete_audit"
CREATE TRIGGER "users_delete_audit" AFTER DELETE ON "users" FOR EACH ROW EXECUTE FUNCTION "audit_users_changes"();
-- 创建触发器 "users_insert_audit"
CREATE TRIGGER "users_insert_audit" AFTER INSERT ON "users" FOR EACH ROW EXECUTE FUNCTION "audit_users_changes"();
-- 创建触发器 "users_update_audit"
CREATE TRIGGER "users_update_audit" AFTER UPDATE ON "users" FOR EACH ROW EX极CUTE FUNCTION "audit_users_changes"();

应用迁移

要将上面生成的迁移应用到数据库，请运行以下命令：

atlas migrate apply \
  --env local \
  --url "postgres://postgres:pass@localhost:5432/database?search_path=public&sslmode=disable"

直接将 Schema 应用到数据库

有时，需要将 schema 直接应用到数据库而不生成迁移文件。例如，在试验 schema 变更、为测试启动数据库等情况下。在这种情况下，您可以使用以下命令将 schema 直接应用到数据库：

atlas schema apply \
  --env local \
  --极rl "postgres://postgres:pass@localhost:5432/database?search_path=public&sslmode=disable"

或者，使用 Atlas Go SDK：

ac, err := atlasexec.NewClient(".", "atlas")
if err != nil {
    log.Fatalf("failed to initialize client: %w", err)
}
// 使用期望的 schema 自动更新数据库。
// 另一种选择是手动使用 'migrate apply' 或 'schema apply'。
if _, err := ac.SchemaApply(ctx, &atlasexec.SchemaApplyParams{
    Env: "local",
    URL: "postgres://postgres:pass@localhost:5432/database?search_path=public&sslmode=disable",
    AutoApprove: true,
}); err != nil {
    log.Fatalf("failed to apply schema changes: %w", err)
}

::>

本指南的代码可以在 GitHub 上找到。

注意：翻译中力求技术术语准确，符合中文技术文档的表达习惯。对于代码块和特定格式（如注释、URL、路径、命令等）均保持原样，未作翻译。对于自然语言部分，采用了符合中文阅读习惯的翻译方式，同时保留了必要的技术术语（如 Ent, Atlas, schema, trigger 等）。

安装 Atlas​

登录 Atlas​

组合式 Schema（Composite Schema）​

使用​

检查 Schema​

为 Schema 生成迁移​

应用迁移​