@palbase/backend 24.2.0 → 25.0.0

package/docs/schema.md

@@ -1,50 +1,108 @@
 # Schema & typed database access
 
-Declare your tables in `db/schema.ts` with `defineSchema`. This drives
+Declare your tables under `db/`, **one file per schema**: `db/public.ts` is the
+schema Palbase expects to find, `db/billing.ts` declares a second one. Each file
+default-exports a `defineSchema("<name>", { tables })` call. That drives
 [migrations](./migrations.md) (additive changes auto-apply on deploy; type
 changes need an explicit migration) and makes `Database.tables.*` typed
 everywhere — by default, with no import and no generic.
 
+> Coming from a single `db/schema.ts` with tables declared inline? That layout is
+> gone, and a push says so by name. The migration guide at
+> `/docs/backend/schema-migration` walks the four changes with before/after code.
+
 ## Defining a schema
 
-The table NAME comes from the object key under `tables`. Each table value is an
-object whose only required field is `columns`; `rls` and `policies` enable
+A table is declared with `defineTable("<name>", { … })` and is a **value that
+knows its own name**. `defineSchema` takes the schema's name and an ARRAY of
+those values — never a dictionary, because a name in a dictionary key is a second
+place the name is written, and a table built under a key does not yet know what
+to call itself when a sibling references it.
+
+Each table's only required field is `columns`; `rls` and `policies` enable
 [Row-Level Security](#row-level-security-rls), and `indexes` declares plain
 btree [indexes](#indexes).
 
 ```ts
 import {
-  defineSchema,
-  uuid, text, integer, boolean, timestamp, jsonb, enumType,
+  defineSchema, defineTable,
+  uuid, text, integer, boolean, timestamp, jsonb, enumType, ownedByUser,
 } from "@palbase/backend";
 
-export default defineSchema({
-  tables: {
-    rooms: {
-      columns: {
-        id: uuid().primaryKey().defaultRandom(),
-        name: text().notNull(),
-        capacity: integer().nullable(),
-        is_active: boolean().default(true),
-        created_at: timestamp().defaultNow(),
-      },
-    },
-    sessions: {
-      columns: {
-        id: uuid().primaryKey().defaultRandom(),
-        room_id: uuid().notNull().references("rooms", "id").onDelete("cascade"),
-        user_id: uuid().notNull(),
-        data: jsonb().nullable(),
-        started_at: timestamp().defaultNow(),
-      },
-    },
-    orders: {
-      columns: {
-        id: uuid().primaryKey().defaultRandom(),
-        status: enumType("order_status", ["pending", "paid", "shipped", "cancelled"]),
-        amount: integer().notNull(),
-      },
-    },
+export const rooms = defineTable("rooms", {
+  columns: {
+    id: uuid().primaryKey().defaultRandom(),
+    name: text().notNull(),
+    capacity: integer().nullable(),
+    is_active: boolean().default(true),
+    created_at: timestamp().defaultNow(),
+  },
+});
+
+export const sessions = defineTable("sessions", {
+  columns: {
+    id: uuid().primaryKey().defaultRandom(),
+    room_id: uuid().references(() => rooms.id).onDelete("cascade"),
+    user_id: ownedByUser(),
+    data: jsonb().nullable(),
+    started_at: timestamp().defaultNow(),
+  },
+});
+
+export const orders = defineTable("orders", {
+  columns: {
+    id: uuid().primaryKey().defaultRandom(),
+    status: enumType("order_status", ["pending", "paid", "shipped", "cancelled"]),
+    amount: integer().notNull(),
+  },
+});
+
+export default defineSchema("public", {
+  tables: [rooms, sessions, orders],
+});
+```
+
+A `defineTable` value **is its columns** — `rooms.id` is the `id` builder, which
+is what makes `references(() => rooms.id)` an ordinary expression. The table's own
+metadata hangs off a symbol rather than a plain field, so a column may be called
+`name`, `columns`, `rls` or `indexes` without shadowing the table's identity.
+
+### One file per schema, and `exposed`
+
+The schema name comes from the declaration; the file name must agree with it. A
+`db/billing.ts` declaring `defineSchema("accounts", …)` is refused at push with
+both names in the error.
+
+`exposed` decides whether a schema is served over `/v1/db`, and the default is
+NOT uniform: **`public` defaults to `true`**, every other schema to `false`. The
+asymmetry is deliberate — `public` is reachable today and stays reachable, because
+a uniform default would silently 404 every existing project's `/v1/db` traffic on
+upgrade, while a schema you add later is not on the internet just because you
+declared it.
+
+```ts
+// db/public.ts — reachable, and you write nothing to get that
+export default defineSchema("public", { tables: [rooms, sessions] });
+
+// db/billing.ts — declared and typed, but not reachable from a client
+export default defineSchema("billing", { tables: [invoices] });
+```
+
+Write the field only to go against the grain — `exposed: false` closes `public`,
+`exposed: true` opens a second schema. Server-side `Database.*` ignores it either
+way: your controllers, jobs and hooks read every schema you declared.
+
+A foreign key may cross schemas: import the table binding and point at it.
+
+```ts
+// db/billing.ts
+import { lists } from "./public";
+
+export const invoices = defineTable("invoices", {
+  columns: {
+    id: uuid().primaryKey().defaultRandom(),
+    list_id: uuid().references(() => lists.id),
+    amount: numeric(),
   },
 });
 ```
@@ -63,27 +121,202 @@ export default defineSchema({
 
 Chainable modifiers: `.primaryKey()`, `.notNull()` (default), `.nullable()`,
 `.default(value)`, `.defaultRandom()` (uuid → `gen_random_uuid()`),
-`.defaultNow()` (timestamp → `now()`), `.references(table, column)`,
-`.onDelete("cascade" | "set null" | "restrict" | "no action")`.
+`.defaultNow()` (timestamp → `now()`), `.references(() => table.column, opts?)`,
+`.selfReferences("column", opts?)`,
+`.onDelete("cascade" | "set null" | "restrict" | "no action")`, `.ignored()`.
+
+## Foreign keys
+
+The target of `references` is a **thunk**, not a direct reference. The callback is
+invoked inside `defineSchema`, where every binding exists and every table already
+knows its name — which is what makes a cycle expressible at all: in `x → y, y → x`
+the second table does not exist yet when the first is built.
+
+```ts
+list_id: uuid().references(() => lists.id),
+```
+
+**Pointing at this same table** takes no thunk and no annotation — the target
+table is the one being declared, so there is nothing to defer:
+
+```ts
+parent_id: uuid().nullable().selfReferences("id"),
+```
+
+Naming a column the table does not have is refused where you declare it.
+
+**Two tables that point at each other** need an explicit return type on ONE side,
+and one is enough — measured. Without it TypeScript chases its own tail (TS7022):
+
+```ts
+import { type AnyColumn } from "@palbase/backend";
+
+export const users = defineTable("users", {
+  columns: {
+    id: uuid().primaryKey().defaultRandom(),
+    primary_org_id: uuid().nullable().references((): AnyColumn => orgs.id),
+  },
+});
+
+export const orgs = defineTable("orgs", {
+  columns: {
+    id: uuid().primaryKey().defaultRandom(),
+    owner_id: uuid().nullable().references(() => users.id),
+  },
+});
+```
+
+**Two foreign keys to the same table** would derive the same relation name from
+their columns, so name one of them:
+
+```ts
+billing_address_id:  uuid().references(() => addresses.id, { as: "billing_address" }),
+shipping_address_id: uuid().references(() => addresses.id, { as: "shipping_address" }),
+```
+
+## Rows that belong to a user
+
+There is no `public.users` table: auth users live in the `auth` schema of the same
+Postgres. Three column factories declare a real foreign key onto it. They are
+factories rather than chain methods because the column type, its nullability and
+its `ON DELETE` are part of what each one MEANS — so they cannot be written wrong.
+
+```ts
+user_id:    ownedByUser(),                              // text, NOT NULL, ON DELETE CASCADE
+edited_by:  userRef({ onDelete: "set null" }).nullable(),
+device_id:  installationRef({ onDelete: "cascade" }),
+```
+
+| | `ownedByUser()` | `userRef({ onDelete })` | `installationRef({ onDelete })` |
+|---|---|---|---|
+| References | `auth.users(id)` | `auth.users(id)` | `auth.installations(id)` |
+| Means | the row **belongs to** that user | the row **points at** a user | the row is scoped to an app install |
+| `ON DELETE` | `cascade`, no argument | required: `cascade` / `set null` | required: `cascade` / `set null` |
+| Account erasure follows it | yes | no | no |
+| Per table | **at most one** | unlimited | unlimited |
+
+`ownedByUser()` takes no `onDelete` because there is only one correct answer:
+ownership is what account erasure walks, so a row owned by an account has to go
+when the account does. `"set null"` on a `userRef` needs a `.nullable()` column.
+
+**One `ownedByUser()` per table, enforced.** Two on one table are refused at push
+with both column names in the error. The rule exists because the alternative was
+worse than a refusal: when several columns could reference `auth.users`, the owner
+was whichever came FIRST IN DECLARATION ORDER — so moving a `created_by` above a
+`user_id` silently changed which rows an account deletion took with it.
+
+An installation reference is **not** ownership. A user-owned row still needs its
+own `ownedByUser()`, or erasing the account leaves it behind.
+
+## Removing a column
+
+A deploy applies the schema while the PREVIOUS release is still answering requests, so
+dropping a column that release still names breaks it the instant the change lands. The
+gate therefore refuses the drop — and until now it refused every drop, with no way
+through: deleting the code that used the column changed nothing, because the gate never
+read your code.
+
+`.ignored()` is how you tell it. The mark is a PROMISE about the release that carries
+it: **this release neither reads nor writes this column, and never names it in a filter,
+a sort or a SET.**
+
+Removing a column is therefore two deploys:
+
+```ts
+// 1. Mark it. The column stays; nothing breaks; no DDL is produced.
+const notes = defineTable("notes", {
+  columns: { id: uuid().primaryKey(), old_body: text().ignored() },
+});
+export default defineSchema("public", { tables: [notes] });
+```
+
+```ts
+// 2. Ship that. Then delete the column and ship again — this time the gate passes,
+//    because the release now serving promised it does not name the column.
+const notes = defineTable("notes", { columns: { id: uuid().primaryKey() } });
+export default defineSchema("public", { tables: [notes] });
+```
+
+`palbase db plan` tells you which step you are on before you push. Locally,
+`palbase db apply` is not restricted — local is where you experiment, and there is no
+traffic to protect.
+
+### When you cannot wait two deploys
+
+There is an escape, and it is deliberately loud:
+
+```
+palbase push --accept-breaking
+```
+
+It opens the gate for one push. Use it when the running release is ALREADY broken and
+the fix is the very change the gate refuses — an incident, not an inconvenience. Outside
+that, two deploys cost less than the one this can break.
+
+It is not silent, and that is the whole design: the push prints the consents it is
+sending, and the server records a `BREAK-GLASS` line naming the digest that was serving
+and every object the gate had refused. So the decision has an author and a time, and
+whoever asks later why a column disappeared finds the answer instead of a normal-looking
+push.
+
+Two things it will not do. It does not apply to a cloud push — `--accept-breaking` there
+is refused by name rather than ignored, because the gate needs to know what is serving
+and only a linked checkout can tell it. And it does not skip the data-loss consent:
+`--approve` is a separate question about erasing rows, and answering one does not answer
+the other.
+
+The word is `ignored` and not `deprecated` on purpose: deprecation is defined, in
+RFC 9745 and in the GraphQL spec alike, as changing NO behaviour. This changes what a
+deploy will accept.
+
+**What the mark cannot do.** No static mark can PROVE your code does not name the
+column — that question is only answerable from traffic. `.ignored()` is your promise.
+What the gate adds is that it reads the promise from the release that is ACTUALLY
+SERVING, not from the file in front of you.
+
+## Renaming an enum value
+
+There is no `renamedFrom` for enum values, and the reason is measured rather than
+stylistic: on PostgreSQL 16, `ALTER TYPE … RENAME VALUE` is an **atomic cutover**. While
+the rename is uncommitted a writer using the OLD label succeeds and one using the NEW
+label fails; at commit that flips. The two names are never both valid, so there is no
+window in which a running release can be migrated across — the instant the rename
+commits, that release's writes fail with `invalid input value for enum`.
+
+Add a value instead, and let the old one die:
+
+```sql
+-- 1. Add the new label. This IS safe while the previous release serves.
+--    (Declare it in db/public.ts; the rail emits ALTER TYPE … ADD VALUE.)
+-- 2. Move the data:
+UPDATE posts SET status = 'review' WHERE status = 'onay';
+-- 3. Stop naming the old value in the next release.
+```
+
+Postgres cannot delete an enum label, so `'onay'` stays — unused and harmless.
+
+**One trap, measured.** A rename is followed automatically by everything Postgres stores
+as a parse tree: column defaults, enum-typed CHECKs, views, materialized-view
+definitions, partial-index predicates, RLS policies, partition bounds, generated columns.
+It is NOT followed by anything stored as TEXT. A constraint written
+`CHECK (status::text = 'onay')` keeps its text after a rename and now checks a label that
+no longer exists — a dead constraint, silently. Measured on PG16: an INSERT the check
+used to reject passed after the rename.
 
 ## Indexes
 
 `indexes` declares plain (non-unique) btree indexes over an ordered column list:
 
 ```ts
-export default defineSchema({
-  tables: {
-    sessions: {
-      columns: {
-        id:         uuid().primaryKey().defaultRandom(),
-        room_id:    uuid().notNull().references("rooms", "id"),
-        started_at: timestamp().defaultNow(),
-      },
-      indexes: [
-        { name: "sessions_room_started_idx", columns: ["room_id", "started_at"] },
-      ],
-    },
+export const sessions = defineTable("sessions", {
+  columns: {
+    id:         uuid().primaryKey().defaultRandom(),
+    room_id:    uuid().references(() => rooms.id),
+    started_at: timestamp().defaultNow(),
   },
+  indexes: [
+    { name: "sessions_room_started_idx", columns: ["room_id", "started_at"] },
+  ],
 });
 ```
 
@@ -95,7 +328,7 @@ name and every column are identifier-validated before any SQL is built.
 knowing before you name an index:
 
 - An index that exists in the database but is not in `indexes` is never dropped.
-  `db/schema.ts` does not own the database's indexes; it only adds the ones it
+  Your schema file does not own the database's indexes; it only adds the ones it
   names.
 - Removing an entry from `indexes` therefore does **not** drop the index. Drop it
   in an explicit [migration](./migrations.md).
@@ -121,10 +354,9 @@ nothing. Rather than ship a half-working partial-index path, the typed field
 stays columns-only and `raw()` carries the rest:
 
 ```ts
-import { defineSchema, raw, uuid, text, timestamp } from "@palbase/backend";
+import { defineTable, raw, uuid, text, timestamp } from "@palbase/backend";
 
-// …
-orders: {
+export const orders = defineTable("orders", {
   columns: {
     id:         uuid().primaryKey().defaultRandom(),
     status:     text().notNull(),
@@ -137,7 +369,7 @@ orders: {
       { down: "DROP INDEX IF EXISTS orders_pending_idx" },
     ),
   ],
-},
+});
 ```
 
 `raw()`'s `up` is emitted verbatim on the privileged DDL connection and, like
@@ -147,12 +379,34 @@ and an index is not one.
 
 ## Typed DB access — by default
 
-You do **not** wire anything per endpoint. Saving `db/schema.ts` regenerates
+You do **not** wire anything per endpoint. Saving a file under `db/` regenerates
 `palbase-env.d.ts`, which types `Database.tables.<name>` everywhere — no import
 of the schema, no generic, no cast:
 
 ```ts
-import { Controller, Post, Body, Database, z } from "@palbase/backend";
+// services/room.service.ts — the layer that touches the database.
+import { Database } from "@palbase/backend";
+
+type RoomsTable = typeof Database.tables.rooms;   // typed from db/schema.ts
+
+export class RoomService {
+  private readonly rooms: RoomsTable;
+  constructor(rooms: RoomsTable) { this.rooms = rooms; }
+
+  async create(name: string) {
+    const room = await this.rooms.insert({ name });
+    return { id: room.id, name: room.name };      // room.id: string ✓
+    // room.nope ← compile error
+  }
+}
+
+export const roomService = new RoomService(Database.tables.rooms);
+```
+
+```ts
+// controllers/rooms.controller.ts — HTTP only; no `Database` import here.
+import { Controller, Post, Body, z } from "@palbase/backend";
+import { roomService } from "../services/room.service.js";
 
 const CreateRoomBody = z.object({ name: z.string() });
 const RoomOut = z.object({ id: z.string(), name: z.string() });
@@ -162,10 +416,8 @@ export default class RoomsController {
   @Post("")
   // The return type names the 200 schema — `z.infer<typeof RoomOut>` works
   // inline, no separate `export type` needed.
-  async create(@Body(CreateRoomBody) body: z.infer<typeof CreateRoomBody>): Promise<z.infer<typeof RoomOut>> {
-    const room = await Database.tables.rooms.insert({ name: body.name });
-    return { id: room.id, name: room.name }; // room.id: string ✓
-    // room.nope ← compile error
+  create(@Body(CreateRoomBody) body: z.infer<typeof CreateRoomBody>): Promise<z.infer<typeof RoomOut>> {
+    return roomService.create(body.name);
   }
 }
 ```
@@ -263,36 +515,37 @@ rows.
 ### Owner-scoped `todos` example
 
 ```ts
-import { defineSchema, policy, uuid, text, boolean, timestamp } from "@palbase/backend";
-
-export default defineSchema({
-  tables: {
-    todos: {
-      columns: {
-        id:         uuid().primaryKey().defaultRandom(),
-        owner:      text().notNull(),        // palauth user id (TEXT)
-        title:      text().notNull(),
-        done:       boolean().default(false),
-        created_at: timestamp().defaultNow(),
-      },
-      // `policies` non-empty ⇒ RLS is enabled + FORCEd automatically.
-      policies: [
-        // Read: a user sees only their own todos.
-        policy("pb_todos_owner_select")
-          .for("select")
-          .to("authenticated")
-          .using("owner = (select auth.uid())"),
-
-        // Write: a user can insert/update/delete only rows they own.
-        policy("pb_todos_owner_write")
-          .for("all")
-          .to("authenticated")
-          .using("owner = (select auth.uid())")
-          .withCheck("owner = (select auth.uid())"),
-      ],
-    },
+import {
+  defineSchema, defineTable, policy, ownedByUser,
+  uuid, text, boolean, timestamp,
+} from "@palbase/backend";
+
+export const todos = defineTable("todos", {
+  columns: {
+    id:         uuid().primaryKey().defaultRandom(),
+    owner:      ownedByUser(),           // text FK onto auth.users(id), NOT NULL, CASCADE
+    title:      text().notNull(),
+    done:       boolean().default(false),
+    created_at: timestamp().defaultNow(),
   },
+  // `policies` non-empty ⇒ RLS is enabled + FORCEd automatically.
+  policies: [
+    // Read: a user sees only their own todos.
+    policy("pb_todos_owner_select")
+      .for("select")
+      .to("authenticated")
+      .using("owner = (select auth.uid())"),
+
+    // Write: a user can insert/update/delete only rows they own.
+    policy("pb_todos_owner_write")
+      .for("all")
+      .to("authenticated")
+      .using("owner = (select auth.uid())")
+      .withCheck("owner = (select auth.uid())"),
+  ],
 });
+
+export default defineSchema("public", { tables: [todos] });
 ```
 
 With this in place, `await Database.tables.todos.findMany({})` returns only the
@@ -311,4 +564,3 @@ so they apply without the `acceptDataLoss` confirmation that column drops need.
 > Changing a policy's body (its `USING`/`WITH CHECK` SQL) in place is not yet
 > auto-applied — rename the policy (new `(table, name)`) or drop the old one in
 > a hand-written migration. Policy DROP/rewrite churn is a documented TODO.
-

package/docs/services.md

@@ -273,16 +273,51 @@ stand-in and never needs a database.
 
 ```ts
 // services/note.service.test.ts — `npm test`, no database
-import assert from "node:assert/strict";
 import { test } from "node:test";
+import assert from "node:assert/strict";
+
 import { NoteService } from "./note.service.ts";
 
-test("list filters by owner", async () => {
+// WHY THIS TEST NEEDS NO DATABASE
+//
+// `NoteService` is handed the table it works on rather than reaching for the
+// singleton itself. That constructor is the seam: a stand-in goes in here, and
+// the logic — which rows, whose, in what order — is exercised without a
+// database. Test your own services the same way.
+//
+// When you want the whole database surface instead of one table, `fakeDatabase()`
+// from `@palbase/backend/test` is the stand-in.
+//
+// Node's ESM resolver wants the extension on a relative import inside a test
+// (`./note.service.ts`); this scaffold's `tsconfig.json` allows it.
+
+test("list asks only for the caller's notes", async () => {
   const seen: unknown[] = [];
-  const fake = { findMany: async (q: unknown) => (seen.push(q), []) };
-  await new NoteService(fake as never).list("u_1");
+  const notes = {
+    findMany: async (where: unknown) => {
+      seen.push(where);
+      return [];
+    },
+  };
+
+  await new NoteService(notes as never).list("u_1");
+
   assert.deepEqual(seen, [{ user_id: "u_1" }]);
 });
+
+test("create writes ownership from the argument, never from the body", async () => {
+  const written: unknown[] = [];
+  const notes = {
+    insert: async (row: unknown) => {
+      written.push(row);
+      return row;
+    },
+  };
+
+  await new NoteService(notes as never).create("u_1", "hello");
+
+  assert.deepEqual(written, [{ user_id: "u_1", body: "hello" }]);
+});
 ```
 
 Node's ESM resolver wants the extension on a relative import inside a test

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palbase/backend",
-  "version": "24.2.0",
+  "version": "25.0.0",
   "description": "Palbase Backend SDK — class controllers (@Controller/@Get/@Post + @Body/@QueryParams/@Param), error classes, schema DSL",
   "license": "MIT",
   "repository": {