跳至主要内容

编解码器

一个 PgCodec（“编解码器”）代表数据库中的一个类型（数据类型）。有很多内置的编解码器用于处理 Postgres 中的内置类型，这些编解码器通过 TYPES 导出 提供，但您也可以使用各种辅助程序为其他类型创建自己的编解码器。

每个编解码器都有一个 name，它是一个方便的标识符，供您用来引用它（您可以通过 registry.pgCodecs[name] 从注册表中引用编解码器）。编解码器还有一个 identifier，它是数据库中类型的名称。

编解码器负责执行强制转换和验证；如果提供的 value 无效，它们应该抛出错误。

TYPES​

import { TYPES } from "@dataplan/pg";

const intCodec = TYPES.int;

TYPES 对象包含许多针对数据库中常见类型的内置编解码器；TYPES 上的以下键代表同名数据库类型（例如，TYPES.boolean 代表 bool 类型）

  • boolean
  • int2
  • int
  • bigint
  • float4
  • float
  • money
  • numeric
  • char
  • bpchar
  • varchar
  • text
  • name
  • json
  • jsonb
  • xml
  • citext
  • uuid
  • timestamp
  • timestamptz
  • date
  • time
  • timetz
  • inet
  • regproc
  • regprocedure
  • regoper
  • regoperator
  • regclass
  • regtype
  • regrole
  • regnamespace
  • regconfig
  • regdictionary
  • cidr
  • macaddr
  • macaddr8
  • interval
  • bit
  • varbit
  • point
  • line
  • lseg
  • box
  • path
  • polygon
  • circle
  • hstore
  • void

recordCodec(config)​

recordCodec 是一个辅助函数，它返回一个表示“复合类型”（或“记录”）的 PgCodec - 具有属性的结构化类型。这在定义表时最常使用（在这种情况下，“属性”是指它包含的列），但在其他情况下也很有用。

记录编解码器配置应包含

  • name: string - 此编解码器的名称
  • identifier: SQL - 此类型的数据库名称
  • attributes: Record<string, PgCodecAttribute> - 此编解码器的属性（列）；此对象上的键是属性名称，值是具有以下选项的对象
    • codec: PgCodec - 详细说明此属性类型的 PgCodec
    • notNull: boolean（可选） - 如果为 true，则表示该列不能为空
    • hasDefault: boolean（可选） - 如果为 true，则表示该列具有默认值（因此可以从 INSERT 操作中省略）
    • expression(alias: SQL): SQL（可选） - 表示此属性不是真正的属性，而是可以使用给定表达式计算的计算值
  • polymorphism（非常可选） - 请参阅 多态性

示例​

const forumCodec = recordCodec({
  name: "forums",
  identifier: sql`app_public.forums`,
  attributes: {
    id: {
      codec: TYPES.uuid,
      notNull: true,
      hasDefault: true,
    },
    name: {
      codec: TYPES.citext,
      notNull: true,
    },
    archived_at: {
      codec: TYPES.timestamptz,
    },
    is_archived: {
      codec: TYPES.boolean,
      expression(alias) {
        return sql`${alias}.archived_at is not null`;
      },
    },
  },
});

listOfCodec(innerCodec, config = {})​

listOfCodec 返回一个新的编解码器，它表示给定 innerCodec 的列表（数组）。您也可以选择提供有关此编解码器的详细信息

  • identifier - 此类型的数据库名称

rangeOfCodec(innerCodec, name, identifier)​

rangeOfCodec 返回一个新的编解码器，它表示给定 innerCodec 的范围。您必须指定要用于此编解码器的 name 和 identifier。

自定义标量编解码器​

如果您需要定义比 TYPES 中提供的更多标量编解码器，您可以创建一个表示它们的 PgCodec 对象。该对象可以具有以下属性

  • name: string (必填) - 用于此编解码器的名称
  • sqlType: string (必填) - 此编解码器的标识符，表示数据库中类型名称的 SQL 片段
  • fromPg - 可选的回调函数，在给定来自 postgres 的文本表示形式的情况下，返回用于在 JavaScript 中使用的值的内部表示形式
  • toPg - 可选的回调函数，在给定 JavaScript 中使用的内部表示形式的情况下，返回要插入 SQL 语句的值 - 这应该是一个简单的标量（文本等），可以由 postgres 转换
  • attributes - 请参阅 recordCodec
  • polymorphism - 请参阅 多态性