@sequenceholdings/orm 2.9.0 → 2.11.0

package/README.md

@@ -170,6 +170,77 @@ the declaration with casts or edits to generated canonical JSON. ORM releases
 use the separate [Studio CLI chain release workflow](https://github.com/sequenceholdings/studio/blob/main/.changeset/README.md#studio-cli-chain-releases);
 chain packages do not use Changesets.
 
+## Synced table indexes (introduced in 2.11.0)
+
+A typed synced table can declare non-unique secondary btree indexes with the
+same `IndexInput` shape `defineTable` uses. The sync still owns the relation's
+columns, keys and rows; the ORM owns only these indexes.
+
+```ts
+export const links = defineSyncedTable("synced_customer_transaction_links", {
+  memberCustomerUid: t.text(), transactionUid: t.text(), postDate: t.date(),
+  relationshipManagerId: t.text(),
+}, {
+  source: "gold.customer_transaction_links_current",
+  primaryKey: ["memberCustomerUid", "transactionUid"],
+  policies: { read: "true" },
+  indexes: [
+    { columns: ["postDate", "transactionUid"], name: "ix_ctl_post_date_txn" },
+    { columns: ["relationshipManagerId", "postDate", "transactionUid"], name: "ix_ctl_rm_post_date_txn" },
+  ],
+});
+```
+
+- Only typed synced tables (declared columns) can declare indexes. Every index
+  column must be declared. `unique: true` is rejected: the primary key already
+  identifies a row, and a unique index can fail the sync.
+- Names follow `defineTable`: explicit, or `ix_<table>_<columns>`. They must fit
+  Postgres's 63-byte limit and be unique in the namespace. The index lives in
+  the physical relation's schema (for example `gold`), not `orm_<namespace>`.
+- Indexes are part of the canonical form and content hash. Adding, changing or
+  removing one produces a new committed migration whose snapshot records them
+  under `_sequenceOrm.syncedIndexes`. Its SQL has no statements for them,
+  because the physical relation is bound per environment.
+- Apply resolves each synced table's backing, the relation the serving stage
+  bound (not `source`). If the index name is free, it runs `CREATE INDEX` on that
+  relation and, in the same transaction, records the new index's OID in the
+  namespace's ledger, `orm_<namespace>._synced_index_ledger`. It drops removed or
+  changed indexes with a guarded `DROP INDEX IF EXISTS`, from the relation they
+  were on before a rebind, and deletes their ledger rows. Then it verifies each
+  index is the recorded, valid, non-unique btree on that relation with the
+  declared keys. Apply re-asserts them every time and is idempotent.
+- **Ownership:** an index is the ORM's only while a ledger row for this
+  namespace's table and relation records its current OID. Apply never drops,
+  replaces or adopts any other index: a same-named index the sync built (even a
+  unique one), another namespace's index on a shared backing, or one someone
+  dropped and recreated under the name (it has a new OID). Apply fails with
+  SQLSTATE `55000` instead; rename the declared index. A ledger row whose index
+  vanished (the pipeline recreated the table) counts as not built, so the next
+  apply or reconcile builds and records it again.
+- The index is created on the partitioned parent (never `ON ONLY`), so every
+  current partition and every partition a SNAPSHOT sync later attaches gets one.
+- **Locking:** a partitioned parent cannot build `CONCURRENTLY`. The build holds
+  a `SHARE` lock that blocks the sync's writes until it finishes. Apply on a
+  large table between sync runs.
+- **Privileges:** on Lakebase the applying identity can `CREATE INDEX` and
+  `DROP INDEX` on the sync's relation without owning it; the index belongs to
+  the relation's owner, so nothing that needs index ownership (`COMMENT ON
+  INDEX`, `ALTER INDEX`, `REINDEX`) is ever emitted. Each statement starts as
+  the applier, switches with `set_config('role', <schema owner>, true)` only to
+  read or write the ledger, and switches back before any index DDL. The ledger
+  lives in the namespace schema, belongs to its owner (`orm_exec`), and grants
+  consumers nothing; drizzle-kit convergence ignores it.
+- **Drift:** if a pipeline drops and recreates the synced table, the indexes go
+  with it. `pendingSyncedIndexStatements` reports the missing ones, and any
+  index the ledger does not record. It reads the ledger as the schema owner in
+  one transaction, so pass a drizzle database that supports `transaction`. Atlas checks
+  them in rehearsal, reports them on `GET /api/orm/namespaces/<ns>/synced-indexes`,
+  and restores them on `POST` with `{ "expected_version_id": "<active version>" }`
+  (namespace admin) or on the next schema apply.
+- `orm apply` requires a runtime that advertises `syncedIndexes` on
+  `/api/orm/runtime-capabilities`. Reviewed (controlled) and frozen namespaces
+  refuse synced indexes. v1 YAML synced tables still cannot declare indexes.
+
 ## Default read-only SQL (introduced in 2.6.0)
 
 With the matching SDK and Atlas rollout, every active v2 namespace supports