@palbase/backend 23.1.0 → 24.0.1

package/docs/migrations.md

@@ -1,88 +1,109 @@
 # Migrations
 
 `db/schema.ts` is the single source of truth for your Postgres schema. You change
-the schema by editing that file, then generating a **migration** from the diff
-with `palbase db diff`. Every schema change — additive or destructive — flows
-through a reviewable migration file committed to git. The deploy applies the
-migrations in `db/migrations/`; nothing is auto-applied behind your back.
+the schema by editing that file — and **nothing generates a migration from it**.
+There is no diff-to-file step: the change is computed against the database *as it
+is right now*, by the stack that owns it, which is what lets it cover type
+changes, policies and constraints that a text diff cannot see.
+
+Two paths lead out of an edit, for two different moments:
+
+- **On your machine** — `palbase db plan` and `palbase db apply` act on the local
+  stack (`palbase start`). Try the change, look at it, keep going.
+- **Anywhere real** — `palbase push` carries the code AND the schema to the
+  selected Environment together, because a deploy that lands a handler against a
+  column that does not exist yet fails at the first request, in production.
+
+`db/migrations/*.sql` still exists, and still runs on deploy, for the objects the
+declaration cannot express — see [Hand-written migrations](#hand-written-migrations).
+It is not where an ordinary column change goes any more.
 
 ## The workflow
 
 ```bash
 # 1. Edit db/schema.ts (add a column, a table, a policy, …)
 
-# 2. Generate the migration from the diff (declared schema vs the selected Environment)
-palbase db diff -f add_priority
-#   → writes db/migrations/<timestamp>_add_priority.sql
+# 2. See what it would take. THIS APPLIES NOTHING.
+palbase db plan
+#   ALTER TABLE todos ADD COLUMN priority text
+#   ⚠ drop todos.notes — 41908 value(s) in 41908 row(s)
+#
+#   the ⚠ changes take data away — `palbase db apply --approve` runs them too
 
-# 3. Review the generated SQL (especially destructive changes — see below),
-#    then commit + push. git push deploys; the migration runs on deploy.
-git add db/migrations && git commit -m "add priority column" && git push
+# 3. Do it — one transaction, against the LOCAL database.
+palbase db apply
+
+# 4. Ship it. Code and schema travel together.
+palbase push
 ```
 
-`palbase db diff` introspects the selected Environment's live database (there is
-no local database — each Environment runs on the server), diffs it against
-`db/schema.ts`, and writes one migration SQL file. If the schema is already in
-sync it writes nothing and tells you so.
+`palbase db plan` hands `db/schema.ts` to the local stack, which computes the plan
+against its own database and answers with what it would change. When there is
+nothing to do it says `✓ the database matches db/schema.ts`. It writes nothing,
+ever — neither a file nor a row — so it is safe to run at any moment, including
+from a script (`--detailed-exitcode` exits 2 when the plan would change
+something, 0 when it is in sync).
 
 ## Additive vs destructive
 
-The generated SQL labels what it does. An additive change (new table, new column)
-is plain DDL:
-
-```sql
--- palbase db diff: add_priority
--- generated 20260605T142233
+The plan separates the two, and a **destructive** change (dropping a column or a
+table) is REFUSED unless you say so again:
 
-ALTER TABLE todos ADD COLUMN IF NOT EXISTS priority text;
 ```
-
-A **destructive** change (dropping a column or table — losing data) is generated
-with a clear warning comment, and `palbase db diff` prints a warning. Review it
-before committing:
-
-```sql
--- DESTRUCTIVE: dropping todos.notes loses its data
-ALTER TABLE todos DROP COLUMN notes;
+$ palbase db apply
+refused: this would take data away — run it again with --approve if that is
+what you mean
 ```
 
-A **column type change** is emitted as a commented stub — auto-migration never
-alters types, so you write the real `ALTER ... TYPE` with whatever `USING` cast
-and backfill your data needs:
+Destructive lines carry their **row counts**, and that is the whole design: "this
+drops a column" is a shrug, "this drops a column with 41,908 values in it" is a
+decision. `palbase db apply --approve` runs them; `palbase push --approve` is the
+same consent for an Environment.
+
+A **column type change** is not applied by this rail at all. The plan lists it
+under `not applied by this rail — change these yourself:` and you write the real
+`ALTER ... TYPE` as a hand-written migration, with whatever `USING` cast and
+backfill your data needs:
 
 ```sql
--- TYPE CHANGE: todos.priority text -> integer (review; auto-migrate does not ALTER types)
--- ALTER TABLE todos ALTER COLUMN priority TYPE integer;
+-- todos.priority text -> integer
+ALTER TABLE todos ALTER COLUMN priority TYPE integer USING priority::integer;
 ```
 
 ## The drift gate
 
-You can't push a schema change without its migration:
-
-- **`palbase db check`** exits non-zero when `db/schema.ts` declares something the
-  database lacks (i.e. you edited the schema but didn't run `palbase db diff`).
-- The scaffold installs a **git pre-push hook** that runs `palbase db check`, so a
-  plain `git push` is **blocked** until you generate + commit the migration.
-  (Bypass with `git push --no-verify` — but the deploy-time gate still rejects it.)
-- On deploy, after migrations run, Palbase asserts `db/schema.ts` matches the live
-  database. Any unresolved drift **fails the deploy** and keeps the previous
+Code and schema move at different speeds, so three things keep them together:
+
+- **`palbase db plan --detailed-exitcode`** exits 2 when the declaration and the
+  database disagree and 0 when they match — the form to put in CI, because it
+  answers with a status code and still writes nothing.
+- The CLI installs a **git pre-push hook** that runs `palbase build`, the same
+  validation the deploy runs, so a push that would produce a failed deploy is
+  caught on your machine first. (Bypass with `git push --no-verify` — the server
+  still gates it.)
+- On deploy, the migrations run and Palbase then asserts `db/schema.ts` matches
+  the live database. Unresolved drift **fails the deploy** and keeps the previous
   version live — a broken schema never goes out silently.
 
-## Your schema change is not live until you deploy it
+## Your schema change is not live anywhere you have not applied it
+
+The local stack and every Environment hold their own database, and editing
+`db/schema.ts` changes none of them: `palbase db apply` is what moves the local
+one, `palbase push` is what moves an Environment's. Until then the declaration is
+ahead of the tables.
 
-There is no local database. `Database` always talks to the selected deployed
-Environment, so a change in `db/schema.ts` does not exist in that database until
-you generate the migration and deploy it — the types can be ahead of the tables.
-Run `palbase db types` after editing the schema to refresh `palbase-env.d.ts` so
-`Database.tables.<name>` is fully typed in your services, and deploy to a dev
-Environment to exercise it against real data.
+The TYPES move separately again. `palbase build` regenerates `palbase-env.d.ts`
+from `db/schema.ts`, which is what types `Database.tables.<name>` in your
+services — so after a schema edit, run it. (There is no second command for this:
+`build` regenerates everything derived, because one verb to remember is one verb
+to forget.) Typed and applied are independent, and knowing which one you are
+missing is usually the whole debugging step.
 
 ## Hand-written migrations
 
 `db/migrations/*.sql` is plain SQL applied in filename order and tracked in
-`schema_migrations` (idempotent — a migration runs once). `palbase db diff`
-generates them for you, but you can also hand-write one for anything the diff
-can't express: a data backfill, a complex type change with a `USING` cast, a
+`schema_migrations` (idempotent — a migration runs once). Nothing generates
+these; you write one for anything the declaration cannot express: a data backfill, a complex type change with a `USING` cast, a
 trigger, a `CHECK` constraint, an `EXCLUDE` constraint, a composite/multi-column
 `UNIQUE`, an index (`CREATE INDEX`), or `CREATE EXTENSION` for an extension that
 isn't in the DSL allowlist (e.g. `btree_gist`). The DSL column builders cover
@@ -126,12 +147,12 @@ Two patterns follow from this:
 - **Extra constraint/index on a DSL-expressible table** — declare the table in
   `db/schema.ts` and add **only** the constraint/index via the migration. The
   base table stays modeled, the gate ignores the constraint, and `palbase db
-  check` stays clean.
+  plan` stays clean.
 - **A whole object the DSL can't model** (like `instructor_sessions` above — its
   `tstzrange` column has no DSL builder) — the table lives entirely in raw SQL,
-  not in `db/schema.ts`. The deploy still succeeds, but `palbase db check` (the
-  read-only client warning) will print a `- table <name>` would-be-drop line for
-  it; that's expected and the deploy-time gate does not block on it.
+  not in `db/schema.ts`. The deploy still succeeds, but `palbase db plan` will
+  list it as a ⚠ would-be-drop for the local database; that is expected, and the
+  deploy-time gate does not block on it. Never approve that one.
 
 ## Adding a NOT NULL column to a table with rows
 
@@ -158,8 +179,9 @@ RLS on and no applicable policy, Postgres denies everything: empty reads, refuse
 writes, no error anywhere that says why.
 
 **Guard the CREATE.** Postgres has no `CREATE POLICY IF NOT EXISTS`, so a
-migration that replays — a fresh Environment, a branch, `palbase db reset` —
-fails on the second run. Drop first:
+migration that replays — a fresh Environment, or `palbase start --reset`, which
+throws the local database away and brings it back empty — fails on the second
+run. Drop first:
 
 ```sql
 DROP POLICY IF EXISTS owner_all ON notes;

package/docs/schema.md

@@ -8,8 +8,9 @@ everywhere — by default, with no import and no generic.
 ## Defining a schema
 
 The table NAME comes from the object key under `tables`. Each table value is an
-object `{ columns, rls?, policies? }` — `columns` is required; `rls` and
-`policies` enable [Row-Level Security](#row-level-security-rls).
+object whose 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 {
@@ -65,6 +66,85 @@ Chainable modifiers: `.primaryKey()`, `.notNull()` (default), `.nullable()`,
 `.defaultNow()` (timestamp → `now()`), `.references(table, column)`,
 `.onDelete("cascade" | "set null" | "restrict" | "no action")`.
 
+## 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"] },
+      ],
+    },
+  },
+});
+```
+
+On deploy each entry becomes a statement of its own — `CREATE INDEX IF NOT
+EXISTS <name> ON <table> (<columns>)` — not a clause of the `CREATE TABLE`. The
+name and every column are identifier-validated before any SQL is built.
+
+**The diff key is the NAME, and the diff is additive.** Three consequences, worth
+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
+  names.
+- Removing an entry from `indexes` therefore does **not** drop the index. Drop it
+  in an explicit [migration](./migrations.md).
+- Changing `columns` under a name that is already live does **nothing** — the
+  deploy matches the name, sees it, and skips. Give the new column list a NEW
+  name (and drop the old index in a migration if you want it gone).
+
+### Scope: plain btree over columns, nothing else
+
+`indexes` models exactly one kind of index. It cannot express:
+
+| what you want | declare it with |
+|---------------|-----------------|
+| a UNIQUE index | `unique: [{ name, columns }]` on the table |
+| a partial index (`WHERE …`) | `raw()` |
+| an expression index (`lower(email)`, …) | `raw()` |
+| any other method (`gin`, `gist`, `hnsw`, …) | `raw()` |
+
+The limit is deliberate, not an oversight. Comparing a partial predicate or an
+expression against the live database needs the same round-trip through Postgres'
+own deparse that `checks` uses; without it an edited predicate would silently do
+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";
+
+// …
+orders: {
+  columns: {
+    id:         uuid().primaryKey().defaultRandom(),
+    status:     text().notNull(),
+    created_at: timestamp().defaultNow(),
+  },
+  raw: [
+    raw(
+      "orders_pending_idx",
+      "CREATE INDEX IF NOT EXISTS orders_pending_idx ON orders (created_at) WHERE status = 'pending'",
+      { down: "DROP INDEX IF EXISTS orders_pending_idx" },
+    ),
+  ],
+},
+```
+
+`raw()`'s `up` is emitted verbatim on the privileged DDL connection and, like
+`indexes`, is tracked by NAME only — a changed body needs a new name. Pass
+`down` yourself for an index: the default drop statement drops a *constraint*,
+and an index is not one.
+
 ## Typed DB access — by default
 
 You do **not** wire anything per endpoint. Saving `db/schema.ts` regenerates

package/docs/services.md

@@ -1,12 +1,27 @@
-# Services
+# Service singletons — `Database`, `Storage`, `Cache`, …
 
-Import service singletons from `@palbase/backend` in every handler type —
-endpoints, workers, jobs, hooks, and webhooks all use the same imports. Only
-**middleware** uses a `ctx` argument (`ctx.db`, `ctx.log`, etc.).
+**Two different things are called "services" here, and this page is the second
+one.** Read the first paragraph before searching this page for a layout rule.
 
-Available singletons: `Database`, `Documents`, `Storage`, `Cache`, `Queue`,
+- **YOUR service layer** — `services/<name>.service.ts`, the plain classes your
+  own business logic lives in. The scaffold ships one, and the contract is at
+  the bottom of this page: [Your own service layer](#your-own-service-layer).
+- **THE service singletons** — the platform objects you import from
+  `@palbase/backend` (`Database`, `Cache`, `Storage`, …). Everything between
+  here and that last section is about these.
+
+Import them in every handler type — endpoints, workers, jobs, hooks, and
+webhooks all use the same imports. Only **middleware** uses a `ctx` argument
+(`ctx.db`, `ctx.log`, etc.).
+
+Available singletons: `Database`, `Documents`, `Storage`, `Cache`,
 `Log`, `Notifications`, `Flags`, `Realtime`.
 
+There is **no `Queue`**. It was listed here for months and has never been
+exported: background work is a cron `@Job` under `jobs/` (see
+[background.md](./background.md)). Importing it does not fail at a queue that
+turns out to be empty — it fails at the import.
+
 `Realtime` is **broadcast-only** on the backend — a handler can push an event to
 a channel, but cannot subscribe (a stateless request can't hold a socket).
 Subscription lives on the client SDK (`pb.realtime`).
@@ -76,9 +91,10 @@ const { data: doc } = await Documents.doc("rooms/abc").get();
 ## Notifications
 
 **No provider setup is required.** Every project starts with a managed sender, so
-email and SMS deliver on a brand-new project with no provider, no API key, and no
-`config/notifications.ts`. You configure your own provider only to send from your
-own domain — see [Config](./config.md).
+email and SMS deliver on a brand-new project with no provider and no API key. You
+configure your own provider only to send from your own domain, and that is a CLI
+act against the stack, not a file in this repository:
+`palbase notifications providers`.
 
 ```ts
 import { Notifications } from "@palbase/backend";
@@ -91,7 +107,7 @@ await Notifications.email.send({
 });
 await Notifications.email.send({
   to: user.email,
-  templateSlug: "receipt",         // defined in config/notifications.ts
+  templateSlug: "receipt",         // created with `palbase notifications templates`
   locale: "tr",                    // without this the extra locale rows are unreachable
   variables: { total: "₺240" },
 });
@@ -198,3 +214,76 @@ and never blocks the handler waiting on subscribers.
 
 Pair it with the client SDK's `pb.realtime.channel("room:42").on("message", …)`
 to drive live chat, presence, dashboards, and other push features.
+
+## Your own service layer
+
+The singletons above are what a service CALLS. This section is the layer that
+calls them — `services/<name>.service.ts`, which the scaffold ships a working
+example of (`services/note.service.ts` and the controller that uses it).
+
+The contract is three rules, and the scaffold's own test enforces all three:
+
+**1. The logic lives in a service; the controller does not touch the database.**
+A controller's job is HTTP — validate a body through a named schema, name the
+200 shape as the return type, turn a missing row into a status. Which rows,
+whose, in what order is the service's. A controller that reaches for `Database`
+has moved the logic into the layer that is hardest to test.
+
+**2. The dependency arrives through the CONSTRUCTOR, and the module exports one
+wired instance.** There is no DI container and no decorator — the last line of
+the file is the wiring:
+
+```ts
+// services/note.service.ts
+import { Database } from "@palbase/backend";
+
+type NotesTable = typeof Database.tables.notes;
+
+export class NoteService {
+  private readonly notes: NotesTable;
+
+  // Assigned in the BODY. A parameter property (`constructor(private notes: …)`)
+  // is refused by Node's type-stripping test runner, for the whole file.
+  constructor(notes: NotesTable) {
+    this.notes = notes;
+  }
+
+  list(userId: string) {
+    return this.notes.findMany({ user_id: userId });
+  }
+}
+
+export const noteService = new NoteService(Database.tables.notes);
+```
+
+```ts
+// controllers/notes.controller.ts
+import { noteService } from "../services/note.service";
+```
+
+**3. That module-level singleton is the only way to hold a dependency.**
+Controllers, hooks, jobs and webhooks are all constructed by the runtime with
+**no arguments**. A class that declares a constructor parameter is refused at
+build with the class named — there is no injector to fill it, so the field would
+otherwise be `undefined` in production. Import the singleton instead.
+
+Rule 2 is also what makes rule 1 pay off: because the service is handed its
+table rather than reaching for the singleton, a test constructs it with a
+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 { NoteService } from "./note.service.ts";
+
+test("list filters by owner", async () => {
+  const seen: unknown[] = [];
+  const fake = { findMany: async (q: unknown) => (seen.push(q), []) };
+  await new NoteService(fake as never).list("u_1");
+  assert.deepEqual(seen, [{ user_id: "u_1" }]);
+});
+```
+
+Node's ESM resolver wants the extension on a relative import inside a test
+(`./note.service.ts`); the scaffold's `tsconfig.json` allows it.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@palbase/backend",
-  "version": "23.1.0",
-  "description": "Palbase Backend SDK \u2014 class controllers (@Controller/@Get/@Post + @Body/@QueryParams/@Param), error classes, schema DSL",
+  "version": "24.0.1",
+  "description": "Palbase Backend SDK — class controllers (@Controller/@Get/@Post + @Body/@QueryParams/@Param), error classes, schema DSL",
   "license": "MIT",
   "repository": {
     "type": "git",