@palbase/backend 25.1.0 → 27.1.0

package/docs/README.md

@@ -35,14 +35,16 @@ service the controllers call.
 
 ### The 7 rules (checklist)
 
-1. **A controller needs NO export at all.** `@Controller` records the class into a
-   `globalThis` registry as it decorates it, and the bundler imports the file for
-   that side effect alone — the shipped scaffold's own `HealthController` and
-   `NotesController` are not exported. Exporting is harmless and reads well, so
-   these examples do it; it is not a requirement. (`export default` **is**
+1. **A controller is exported by NAME and listed in a module.** `@Controller`
+   records the class as it decorates it, but that registration only says the
+   class EXISTS — a module's `controllers` list is what decides it should be
+   served. So the module imports it by name, which means the class is exported;
+   an unexported one is registered, owned by nothing, and refused at build with
+   `unowned class`. Nothing is default-exported here. (`export default` **is**
    required for `jobs/`, `webhooks/`, `hooks/` and every `db/*.ts`, one class per
-   file.) What IS fatal is a `@Controller` class that collected zero routes —
-   usually `experimentalDecorators` missing from `tsconfig.json`.
+   file — those are read off disk by name, not through a module.) What IS fatal
+   is a `@Controller` class that collected zero routes — usually
+   `experimentalDecorators` missing from `tsconfig.json`.
 2. **Methods that call a service are `async` and return `Promise<T>`.** Services
    `await Database`, so they return promises; a sync return type on an async body
    is a tsc error. Annotate `: Promise<TodoSchema>`, not `: TodoSchema`, whenever
@@ -71,7 +73,7 @@ service the controllers call.
 
 > **Never** emit `defineController`, `defineHandler`, `defineEndpoint`, `route.get(...)`,
 > `req.input`, `req.params`, or `req.errors` — those are the removed legacy model
-> and will not compile against `@palbase/backend` 25.
+> and will not compile against `@palbase/backend` 27.
 
 ### Complete CRUD example (copy-pasteable, compiles)
 
@@ -95,13 +97,14 @@ export type CreateTodoBody = z.infer<typeof CreateTodoBody>;
 
 ```ts
 // services/todo.service.ts — plain class + singleton. The real work.
-import { Database, NotFound } from "@palbase/backend";
+import { Database, Injectable, NotFound } from "@palbase/backend";
 import type { TodoSchema } from "../models/todos/shared.js";
 
 /** The typed surface of ONE table. Naming it keeps the seam one table wide:
  * a test fake implements five methods, not the whole `Database`. */
-type TodosTable = typeof Database.tables.todos;
+type TodosTable = typeof Database.public.todos;
 
+@Injectable()
 export class TodoService {
   private readonly todos: TodosTable;
 
@@ -115,7 +118,7 @@ export class TodoService {
   }
 
   list(userId: string): Promise<TodoSchema[]> {
-    return this.todos.findMany({ user_id: userId });
+    return this.todos.findMany({ where: { user_id: userId } });
   }
   create(userId: string, title: string): Promise<TodoSchema> {
     return this.todos.insert({ user_id: userId, title });
@@ -131,14 +134,26 @@ export class TodoService {
   }
 }
 
-/** The wired instance. Controllers import THIS, never the class. It is also the
- * ONLY supported way to hold a dependency: a controller, job, hook or webhook is
- * constructed with no arguments, and one that declares a constructor parameter is
- * refused with the class named — at decoration time for jobs/hooks/webhooks, and
- * when the route table is built at boot for a controller. */
-export const todoService = new TodoService(Database.tables.todos);
 ```
 
+```ts
+// todos.module.ts — ONE module says what exists, who owns it, and what it may reach.
+import { Module, type Token } from "@palbase/backend";
+import { TodosController } from "./controllers/todos.controller.ts";
+import { TodoService } from "./services/todo.service.ts";
+
+@Module({
+  controllers: [TodosController as Token],
+  providers: [TodoService as Token],
+})
+export class TodosModule {}
+```
+
+A class no module lists does not exist: it is refused at build, by name, and it
+never reaches the route table or the OpenAPI document. Nothing is wired by hand
+— a controller names `TodoService` as a constructor parameter and the container
+supplies it. See [services.md](./services.md#your-own-service-layer).
+
 ```ts
 // controllers/todos.controller.ts — class controller. Thin: delegates to the service.
 import { Controller, Get, Post, Delete, Body, Param, User } from "@palbase/backend";
@@ -219,7 +234,7 @@ generated client surface) changes; the verb/path do not affect it.
   (stage, bundle, extract controller metadata). Exits non-zero on a decorator,
   return-type or version-skew error, so a push that would deploy zero endpoints
   fails on your machine instead. It also regenerates `palbase-env.d.ts` from
-  your `db/*.ts` files, which is what types `Database.tables.*` (no import, no
+  your `db/*.ts` files, which is what types `Database.public.*` (no import, no
   generic) — so run it after editing the schema. There is no separate command
   for that: `build` regenerates everything derived.
 - `palbase push` — deploy the current backend to the selected Environment. For a

package/docs/auth.md

@@ -176,4 +176,4 @@ single-use and expire; a used or expired one fails closed with a `400`.
 
 - [Row-Level Security](./schema.md#row-level-security-rls) — pushing per-user
   access rules into Postgres, where `auth.uid()` is this same verified user.
-- [Database](./database.md) — how `Database.asService()` steps outside RLS.
+- [Database](./database.md) — how `Database.$asService()` steps outside RLS.

package/docs/background.md

@@ -26,8 +26,8 @@ import { Database, Job, Log, type JobMeta } from "@palbase/backend";
 @Job({ schedule: "0 3 * * *", timeout: 120 }) // schedule: standard cron; timeout: optional, seconds
 export default class CleanupJob {
   async run(meta: JobMeta) {
-    const expired = await Database.findMany("sessions", { expired: true });
-    for (const s of expired) await Database.delete("sessions", s.id as string);
+    const expired = await Database.$findMany("sessions", { expired: true });
+    for (const s of expired) await Database.$delete("sessions", s.id as string);
     Log.info(`cleaned ${expired.length} sessions in ${meta.environmentId}`);
   }
 }

package/docs/database.md

@@ -10,19 +10,19 @@ import { Database } from "@palbase/backend";
 Only **middleware** still uses `ctx.db` (see [background.md](./background.md)
 and [events.md](./events.md) for worker/job/hook/webhook examples).
 
-## Typed by default — `Database.tables`
+## Typed by default — `Database.<şema>.<tablo>`
 
-When you declare a schema under `db/*.ts`, `Database.tables.<name>` is typed everywhere
+When you declare a schema under `db/*.ts`, `Database.public.<name>` is typed everywhere
 with no import and no generic. `insert` demands the right columns; rows come
 back typed; nullable columns are `T | null`. This is the path you should use:
 
 ```ts
-const todo = await Database.tables.todos.insert({ title: "buy milk" });
+const todo = await Database.public.todos.insert({ title: "buy milk" });
 todo.id;       // string ✓
 todo.done;     // boolean ✓
-const open = await Database.tables.todos.findMany({ done: false });
-await Database.tables.todos.update(todo.id, { done: true });
-await Database.tables.todos.delete(todo.id);
+const open = await Database.public.todos.findMany({ where: { done: false } });
+await Database.public.todos.update({ where: { id: todo.id }, set: { done: true } });
+await Database.public.todos.delete(todo.id);
 // todo.nope ← compile error
 ```
 
@@ -35,18 +35,18 @@ cover, the string-keyed ops are still available:
 
 | Method | Returns |
 |--------|---------|
-| `Database.insert(table, data)` | the inserted row (`Record<string, unknown>`) |
-| `Database.upsert(table, data, { onConflict })` | the inserted-or-updated row |
-| `Database.update(table, id, data)` | the updated row, or `null` if none matched |
-| `Database.delete(table, id)` | `void` |
-| `Database.updateMany(table, where, set)` | every row the filter matched, updated |
-| `Database.deleteMany(table, where)` | how many rows went |
-| `Database.findById(table, id)` | the row or `null` |
-| `Database.findMany(table, where?, opts?)` | matching rows (array) |
-| `Database.count(table, where?)` | how many rows match |
-| `Database.query(sql, params?)` | rows from a SQL query, in the request's own transaction |
-| `Database.transaction(fn)` | runs a whole transaction plan in one request |
-| `Database.attempt(fn)` | a savepoint: a failure inside rolls back only its own writes |
+| `Database.$insert(table, data)` | the inserted row (`Record<string, unknown>`) |
+| `Database.$put(table, data, { onConflict })` | the inserted-or-updated row |
+| `Database.$update(table, id, data)` | the updated row, or `null` if none matched |
+| `Database.$delete(table, id)` | `void` |
+| `Database.$updateMany(table, where, set)` | every row the filter matched, updated |
+| `Database.$deleteMany(table, where)` | how many rows went |
+| `Database.$findById(table, id)` | the row or `null` |
+| `Database.$findMany(table, where?, opts?)` | matching rows (array) |
+| `Database.$count(table, where?)` | how many rows match |
+| `Database.$query(sql, params?)` | rows from a SQL query, in the request's own transaction |
+| `Database.$transaction(fn)` | runs a whole transaction plan in one request |
+| `Database.$attempt(fn)` | a savepoint: a failure inside rolls back only its own writes |
 
 ### Filters
 
@@ -54,26 +54,137 @@ A filter's keys are ANDed. Each value is either a plain value (equality) or an
 operator object:
 
 ```ts
-await Database.tables.entries.findMany({
-  household_id: hid,                 // equality
-  amount_kurus: { gte: 1000 },       // >=
-  category: { in: ["food", "rent"] },
-  status: { neq: "void" },
+await Database.public.entries.findMany({
+  where: {
+    household_id: hid,               // equality
+    amount_kurus: { gte: 1000 },     // >=
+    category: { in: ["food", "rent"] },
+    status: { neq: "void" },
+  },
 });
 ```
 
-Operators: `gt` · `gte` · `lt` · `lte` · `neq` · `in`. The same filter language
-works for `updateMany`, `deleteMany` and `count` — one language, so two spellings
-cannot drift apart. An empty `in` list means NO rows (written into the SQL as
-`false`), never a silent full scan.
+Operators: `gt` · `gte` · `lt` · `lte` · `neq` · `in` · `contains` ·
+`icontains` · `startsWith` · `endsWith` · `isNull`, plus `OR` / `AND` / `NOT`
+for composition. A branch of `OR` / `AND` / `NOT` may also be a `sqlFragment`,
+so one hand-written predicate does not force the whole query into raw SQL:
+
+```ts
+await Database.public.crew_presence.findMany({
+  where: {
+    city: "IST",
+    AND: [sqlFragment`expires_at > now()`],
+  },
+});
+``` The same filter language works for `updateMany`, `deleteMany`,
+`count` and `search` — one language, so two spellings cannot drift apart. An
+empty `in` list means NO rows (written into the SQL as `false`), never a silent
+full scan.
+
+### Comparing against server time — `now()`
+
+`expires_at > now()` is one of the most-written predicates in any backend, and
+the answer must come from the DATABASE's clock: sending `new Date()` from
+JavaScript silently switches to the client's clock, and two machines do not
+agree.
+
+```ts
+import { now } from "@palbase/backend";
+
+await Database.public.sessions.findMany({
+  where: { user_id, expires_at: { gt: now() } },
+});
+```
+
+It renders as `now()` with NO bound parameter. The bare form is equality
+(`{ last_seen: now() }`), exactly like `col()`.
+
+`increment()` / `decrement()` are refused here by name: they are WRITE
+expressions, and a comparison against one would silently match nothing. And a
+`{ "$expr": { "fn": "now" } }` object arriving in a request body is not `now()`
+— only the `now()` call produces one, so spreading untrusted input into a filter
+cannot forge a server-time comparison.
+
+### Comparing one column with another — `col()`
+
+The right-hand side of a comparison is normally a VALUE. `col()` puts a COLUMN
+there, which is otherwise a reason to drop to raw SQL:
+
+```ts
+import { col } from "@palbase/backend";
+
+// Invoices that are not fully paid.
+await Database.public.invoices.findMany({ where: { total: { gt: col("amount_paid") } } });
+```
+
+The name is checked at COMPILE time against the row type: `col("amont_paid")`
+does not compile. It is legal in `gt` / `gte` / `lt` / `lte` / `neq` and as a
+bare value (which means equality); anywhere else — inside `in`, in a `set`, in
+`orderBy` — it is refused by name.
+
+`col()` is only ever produced by the `col()` call. A `{ "$col": "…" }` object
+that arrives in a request body is NOT a column reference and is refused as an
+unknown operator, so spreading untrusted input into a filter cannot turn a
+tenant predicate into a tautology.
+
+### Filtering through a relation — `has`
+
+A filter on the row next to yours is the most common reason to drop to raw SQL,
+and it is the one the schema already knows how to answer. Every foreign key you
+declare produces a named relation on BOTH sides, and `has` filters through it:
+
+```ts
+// Interests that THIS user picked.
+await Database.public.interests.findMany({
+  where: { has: { user_interests: { user_id: userId } } },
+  orderBy: { column: "sort_order", direction: "asc" },
+});
+```
+
+That compiles to a correlated `IN (SELECT …)` — one statement, one round trip,
+the RLS policies of BOTH tables still applied. The hand-written alternative was
+a `sqlFragment` carrying a subquery, or two queries and a `Set` in JavaScript.
+
+The relation names come from the schema, so `has: { user_intrests: … }` is a
+compile error, and so is a column that the OTHER table does not have. A table
+that declares no foreign key at all has no `has` — the key is absent, not empty.
+
+Both directions work. From the child, the relation is the parent:
+
+```ts
+await Database.public.user_interests.findMany({
+  where: { has: { interest: { name: { icontains: "yoga" } } } },
+});
+```
+
+The inner filter is the SAME language: operators, `OR` / `AND` / `NOT`, `col()`,
+and a nested `has` one table further (three levels — the relation graph points
+both ways, so it is a cycle, and an unbounded type would follow it forever).
+
+`has` is available wherever a filter is: `findMany`, `count`, `updateMany`,
+`deleteMany`, and inside `$transaction`. In a transaction the update still takes
+its rows in primary-key order under `FOR NO KEY UPDATE`, exactly as a plain
+filter does:
+
+```ts
+await Database.$transaction((tx) => {
+  tx.public.interests.updateWhere(
+    { has: { user_interests: { user_id: userId } } },
+    { last_seen_at: now() },
+  );
+  return [];
+});
+```
 
 ### Ordering and paging
 
 ```ts
-await Database.tables.entries.findMany(
-  { household_id: hid },
-  { orderBy: { column: "created_at", direction: "desc" }, limit: 20, offset: 40 },
-);
+await Database.public.entries.findMany({
+  where: { household_id: hid },
+  orderBy: { column: "created_at", direction: "desc" },
+  limit: 20,
+  offset: 40,
+});
 ```
 
 `orderBy.column` is checked against the row type: a mistyped column name is a
@@ -97,7 +208,7 @@ It runs in **the request's own transaction**, not a read-only one: a write insid
 it commits with the rest of the request.
 
 ```ts
-const rows = await Database.query(
+const rows = await Database.$query(
   "SELECT c.name, count(*) FROM entries e JOIN categories c ON c.id = e.category_id" +
   " WHERE e.household_id = $1 GROUP BY c.name",
   [hid],
@@ -114,7 +225,7 @@ Inside a transaction, `insertMany` takes an optional conflict rule — which is
 per row with a `23505` caught around each:
 
 ```ts
-await Database.transaction((tx) => {
+await Database.$transaction((tx) => {
   tx.tables.merchants.insertMany(rows, { onConflict: ["name"], action: "ignore" });
   return null;
 });
@@ -141,7 +252,7 @@ carrying the constraint Postgres named:
 import { UniqueViolation, Conflict } from "@palbase/backend";
 
 try {
-  return await Database.tables.users.insert({ email });
+  return await Database.public.users.insert({ email });
 } catch (e) {
   if (UniqueViolation.is(e) && e.constraint === "users_email_key") {
     throw new Conflict("That email is taken", "email_taken");
@@ -171,7 +282,7 @@ middle, so nothing holds a database connection open while your code thinks.
 ```ts
 import { Database, NotFound } from "@palbase/backend";
 
-const { orderId } = await Database.transaction((tx) => {
+const { orderId } = await Database.$transaction((tx) => {
   const order = tx.tables.orders
     .insert({ amount: 1000, status: "pending" })
     .expectOne(new NotFound("order could not be created"));
@@ -220,9 +331,9 @@ does not write is not part of the transaction:
 
 ```ts
 // Before the transaction: an ordinary value you can branch on.
-const overrides = await Database.tables.category_overrides.findMany({ household_id });
+const overrides = await Database.public.category_overrides.findMany({ where: { household_id } });
 
-const stmt = await Database.transaction((tx) => { /* … */ });
+const stmt = await Database.$transaction((tx) => { /* … */ });
 ```
 
 ### Writing conditions as filters
@@ -253,19 +364,113 @@ Three expressions may appear in the values you write:
 
 | Expression | Where | Meaning |
 |---|---|---|
-| `now()` | anywhere | the server's clock |
-| `inc(n)` | `updateWhere`'s `set` | `column = column + n`, atomically |
-| `dec(n)` | `updateWhere`'s `set` | `column = column - n`, atomically |
+| `now()` | any `set` — `updateMany` and `updateWhere` | the server's clock |
+| `increment(n)` | any `set` | `column = column + n`, atomically |
+| `decrement(n)` | any `set` | `column = column - n`, atomically |
+
+`inc` / `dec` are the OLD names for `increment` / `decrement`. They are the same
+factory (`inc === increment`), kept as deprecated aliases; write the long names.
+
+The expressions work on BOTH surfaces — the direct `updateMany` and the plan's
+`updateWhere` — because they are one object:
+
+```ts
+// Direct: one statement, no transaction needed.
+await Database.public.accounts.updateMany({
+  where: { id: accountId },
+  set: { balance: decrement("5.00") },
+});
+
+// Inside a plan: the same expression, the same meaning.
+await Database.$transaction((tx) => {
+  tx.tables.accounts.updateWhere({ id: accountId }, { balance: decrement("5.00") });
+  return null;
+});
+```
+
+**Give money a STRING amount.** `increment(0.1)` binds a JS number and
+`0.1 + 0.2` is `0.30000000000000004`; `increment("0.1")` binds the decimal and
+Postgres adds it exactly. Measured: `12345678901234567890` as a number becomes
+`12345678901234600000`, as a string it stays whole.
+
+**The amount is a magnitude, not a signed number.** `decrement("-5")` is
+refused: a negative amount would ADD money through a call that reads as a
+withdrawal, and the guard names `increment()` as the way to say the other
+direction.
+
+`increment` / `decrement` read the column's current value, which an inserted row
+does not have — using one in an `insert` is a compile error, and the engine
+refuses it by name if it arrives untyped.
+
+### Zero rows is not silent success
+
+`updateMany` returns EVERY row it matched, and matching nothing is an answer the
+caller has to read:
+
+```ts
+const [row] = await Database.public.accounts.updateMany({
+  where: { id: accountId, balance: { gte: amount } },   // the guard IS the filter
+  set: { balance: decrement(amount) },
+});
+if (row === undefined) throw new Conflict("insufficient balance");
+```
+
+The filter carries the condition, so the check and the write are ONE statement —
+there is no window between reading a balance and spending it. An empty array
+means the balance was too low, or the row does not exist, or RLS hides it from
+this caller. None of those is "the transfer happened".
+
+### Append-only tables — a record that cannot be rewritten
+
+`appendOnly: true` on a table declaration means a row can be INSERTED and read,
+never updated and never deleted. A correction is a COMPENSATING ENTRY: a new row
+carrying the opposite sign.
+
+```ts
+export const entries = defineTable("entries", {
+  appendOnly: true,
+  columns: { /* … */ },
+});
+```
+
+**Three locks, because the first two are not enough on their own:**
+
+| Lock | Stops | Does not stop |
+|---|---|---|
+| The TYPE | `update` / `updateMany` / `delete` / `deleteMany` / `put` / `supersede` are not on the table | untyped `$`-prefixed calls, anything off the wire |
+| The ENGINE | those same operations refused by name, whichever door they come through | SQL that never passes through this SDK |
+| The DATABASE | `REVOKE UPDATE, DELETE`, a RESTRICTIVE policy, and two triggers — `BEFORE UPDATE OR DELETE` per row and `BEFORE TRUNCATE` per statement | the table's OWNER, who can `ALTER TABLE … DISABLE TRIGGER` first (measured) — as an owner can also simply drop the table |
+
+The triggers are not belt-and-braces. Measured on a live stack: the platform
+re-grants table privileges on every boot, which quietly undid the REVOKE, and
+the service role carries `BYPASSRLS`, so the policy never applied to it either.
+With both gone the row really was deletable. The triggers are what actually
+hold, and they say so:
+
+```
+ERROR:  table entries is append-only: a row cannot be updated or deleted.
+        Write a COMPENSATING ENTRY instead (an INSERT carrying the opposite sign).
+```
+
+`SELECT` and `INSERT` are untouched — append-only means the history is kept, not
+that it is unreadable, and the correction path has to stay open.
+
+**TRUNCATE needs its own trigger, and finding that out took a measurement.** A
+row-level trigger never sees a `TRUNCATE` — Postgres truncates without touching
+rows — so the owner could empty the whole ledger in one statement while every
+other door was shut. The statement-level `BEFORE TRUNCATE` trigger closes it.
 
-`inc`/`dec` read the column's current value, which an inserted row does not
-have — using them in an `insert` is a compile error.
+What is NOT closed: the table's owner can `ALTER TABLE … DISABLE TRIGGER` and
+then write freely. That is not a hole this can fix — the same owner can drop the
+table — and saying otherwise would be the kind of claim this table exists to
+avoid.
 
 ### Limits
 
 A plan may carry at most 1000 operations, 5000 rows in one `insertMany`, and
 8 MiB of JSON. Exceeding any of them is reported before the request is sent.
 
-## Bypassing RLS — `Database.asService()`
+## Bypassing RLS — `Database.$asService()`
 
 When a table has [Row-Level Security](./schema.md#row-level-security-rls)
 policies, every `Database.*` call runs as the request's verified user, so the
@@ -282,7 +487,7 @@ nothing your code does. See
 
 Sometimes you need to read or write **across all users** — an admin endpoint, a
 background job that fans out notifications, a cleanup task. For that, call
-`Database.asService()`. It returns a sibling client that runs as
+`Database.$asService()`. It returns a sibling client that runs as
 **`backend_service_role`** (the role that carries `BYPASSRLS`), exposing the
 exact same surface — `tables`, the raw string ops, and `transaction`:
 
@@ -290,14 +495,14 @@ exact same surface — `tables`, the raw string ops, and `transaction`:
 import { Database } from "@palbase/backend";
 
 // RLS-enforced (default): only the caller's own rows.
-const mine = await Database.tables.todos.findMany({});
+const mine = await Database.public.todos.findMany({});
 
 // Service-role bypass: every user's rows. Explicit and greppable.
-const all  = await Database.asService().tables.todos.findMany({});
-const rows = await Database.asService().query("SELECT count(*) FROM todos");
+const all  = await Database.$asService().tables.todos.findMany({});
+const rows = await Database.$asService().query("SELECT count(*) FROM todos");
 
 // A service-role transaction (the role is fixed for the whole plan):
-await Database.asService().transaction((tx) => {
+await Database.$asService().transaction((tx) => {
   tx.tables.todos.updateWhere({ id }, { done: true });
   return null;
 });
@@ -310,8 +515,8 @@ Guidelines:
   grep for in review.
 - **No double-bypass / no nesting.** The sibling does not re-expose
   `asService()`, and `tx` never exposes it — a plan's role is fixed for the whole
-  transaction. Use `Database.transaction(...)` for an authenticated one and
-  `Database.asService().transaction(...)` for a service-role one; you cannot mix
+  transaction. Use `Database.$transaction(...)` for an authenticated one and
+  `Database.$asService().transaction(...)` for a service-role one; you cannot mix
   enforced and bypassed operations inside a single plan.
 - **It is a second transaction, on a second connection.** It has to be: the
   Postgres role is bound once, when the transaction opens, so a sibling sharing

package/docs/endpoints.md

@@ -40,10 +40,9 @@ export default class RoomsController {
 
 1. **The controller does not touch the database.** It delegates to a service, as
    above. A method here that reaches for `Database` has moved the logic into the
-   layer that is hardest to test. (An export is not required at all: `@Controller`
-   records the class as it decorates it, and importing the file IS the
-   registration — the shipped scaffold's own controllers are not exported.
-   `export default` here is style.)
+   layer that is hardest to test. (Export the class by NAME so its module can
+   list it in `controllers`; a class no module lists is refused at build with
+   `unowned class`. Nothing here is default-exported.)
 2. **A method that awaits a service is `async` + `Promise<T>`.** `Database`
    returns promises, so a body that `await`s it cannot have a sync return type
    (`: RoomSchema` on an `async` body is a `tsc` error). Both methods above are

package/docs/events.md

@@ -17,7 +17,7 @@ import { auth, Database, Log } from "@palbase/backend";
 
 export const onUserCreated = auth.onUserCreated(async (event, meta) => {
   Log.info(`new user: ${event.user.email}`);
-  await Database.insert("profiles", {
+  await Database.$insert("profiles", {
     user_id: event.user.id,
     email: event.user.email,
   });
@@ -50,13 +50,13 @@ import { Database, Log, On, Webhook, type WebhookMeta } from "@palbase/backend";
 export default class StripeWebhook {
   @On("checkout.session.completed")
   async checkoutCompleted(event: unknown, meta: WebhookMeta) {
-    await Database.insert("orders", { status: "paid", data: event });
+    await Database.$insert("orders", { status: "paid", data: event });
   }
 
   @On("payment_intent.payment_failed")
   async paymentFailed(event: unknown, meta: WebhookMeta) {
     Log.error("payment failed");
-    await Database.insert("payment_failures", { data: event });
+    await Database.$insert("payment_failures", { data: event });
   }
 }
 ```

package/docs/getting-started.md

@@ -48,7 +48,7 @@ start. The loop is: edit, validate, push to a dev Environment.
   type or an SDK major skew fails here rather than shipping a deploy that
   serves zero endpoints. It is wired into a `pre-push` git hook for you. It also
   regenerates `palbase-env.d.ts` from your `db/*.ts` files, which is what types
-  `Database.tables.*` (no import, no generic), so run it after editing the
+  `Database.public.*` (no import, no generic), so run it after editing the
   schema — there is no separate command for that. See
   [migrations.md](./migrations.md) for the schema side.
 - `palbase push` deploys the current backend to the selected Environment. For a