概念

库是隔离单元，表定义记录的结构，字段定义值的类型，行保存实际记录。

库、表、字段、行

API Key 决定你能访问哪些库。表和字段可用 ID 或名称寻址；关联字段使用表 ID，因此改名不会改变关联目标。库的标签用于分类和筛选。

默认行只包含主键 id 和用户字段，select=*、return=representation 及 RPC 都遵循这一规则。字段保留名只有 id；新字段不能以 _ 开头。created_at、updated_at、version 可作为普通字段。字段名以小写字母开头，后续只含小写字母、数字和下划线，最多 63 字；表名也允许下划线开头。已有下划线用户字段仍可读写，且优先于同名系统元数据；这时该表无法访问同名元数据。

系统元数据只读，需显式取用：select=*,_version,_created_at,_updated_at。* 不会展开它们。可用 _version=eq.3 过滤，或 order=_created_at.desc 排序。不指定 order 时，仍按内部创建时间再按 id 排序。过滤或排序使用旧元数据名且没有同名用户字段时返回 400：details 为 use _created_at（或对应的新名字），hint 为 system metadata moved to underscore columns。

时间字段可定义为 {"name":"created_at","type":"datetime","default":"now()"}。插入时省略该字段，就保存服务器当前 UTC 时间；读回字段定义仍显示 "now()"。显式 null 和 PATCH 中省略的字段不使用默认值。string/json 字段的 "now()" 默认值仍为字面量字符串。给已有表新增这个字段时，回填也会求值。

七种字段类型

类型	保存的值
`string`	字符串
`integer`	整数
`number`	数值
`boolean`	`true` 或 `false`
`datetime`	RFC 3339 日期时间，例如 `2026-10-11T08:30:00+08:00`；不存在的日期（如 2 月 30 日）返回 400。值统一按 UTC、3 位毫秒保存和读出，例如 `2026-10-11T00:30:00.000Z`；精度为毫秒，超过 3 位的小数秒四舍五入
`json`	满足指定 JSON Schema 的 JSON 值
`link`	同一库中另一张表的行 ID，或多个行 ID

required 要求写入非空值。新增带 default 的字段时，已有行一律用它回填；不带 default 的新字段在已有行上为空。在已有行的表上新增 required 字段时必须提供 default；把已有字段改为 required 时，若仍有行在该列为空则返回 400 VALIDATION_FAILED 并说明空行数，先补齐这些行再修改。unique 要求值唯一。前五种类型默认建立索引；不需要的字段可以设 indexed: false。json 和 link 不能设为索引字段。字段类型创建后不可修改。

批量写入与事务

一次 POST 最多插入 500 行。单次请求是原子的：任何一行失败，整批回滚。跨请求没有事务；需要一起成功的行应放在一次批量 POST 中。有关联依赖时先查询目标，再插入引用它的行；先查后插不能保证并发期间目标不变，仍需处理插入时的关联错误。

同一批次会按所有行的键的并集补齐缺失值为 null（PostgREST 行为），因此某行省略必填字段可能导致整批失败。发送 Prefer: missing=default 可让缺失的键使用字段默认值；显式传入的 null 仍为 null，没有默认值的必填字段仍必须提供。

默认 return=minimal：成功返回 201，body 为空。需要读回新增行时发送 Prefer: return=representation，或在 supabase-js 的 .insert(...) 后调用 .select()。

JSON Schema

json 字段必须在 options.schema 中提供 JSON Schema。例如，下面的字段只接受包含字符串 summary 的对象。

{
  "name": "detail",
  "type": "json",
  "options": {
    "schema": {
      "type": "object",
      "properties": { "summary": { "type": "string" } },
      "required": ["summary"],
      "additionalProperties": false
    }
  }
}

更新 schema 约束之后的写入，不会重写已有行。查询时可用 detail->>summary 读取字符串值。

关联与删除保护

link 的 options.linked_table_id 指向同一库中的目标表，multiple 决定保存单个行 ID 还是行 ID 数组。关联目标创建后不可更改。

{
  "name": "project",
  "type": "link",
  "options": { "linked_table_id": "tbl_example", "multiple": false }
}

把 tbl_example 换成已创建表的 ID。引用不存在的行会被拒绝；删除仍被其它行引用的行也会被拒绝；同一次删除中的行互相引用时可以一起删除。先解除引用，再删除目标，不会自动级联删除。

用 _version 避免覆盖他人的更新

新行的 _version 为 1，每次更新递增。更新时同时过滤行 ID 和读到的版本；没有返回行表示该条件不再匹配，需要重新读取后决定下一步。

const { data: row, error: readError } = await supabase.from("tasks")
  .select("*,_version").eq("id", rowId).single();
if (readError) throw readError;

const { data, error } = await supabase.from("tasks")
  .update({ done: true })
  .eq("id", row.id)
  .eq("_version", row._version)
  .select();
if (error) throw error;
if (data.length === 0) throw new Error("Read the row again before updating");

删除库后 7 天内恢复

删除库后不能再读写其中的行。在 7 天内调用恢复库可以重新使用库及保留的表和行；超过窗口无法恢复。此恢复能力针对整个库，不是单独删除的表、字段或行。

API 参考 → · 限制与错误 →

概念