@palbase/backend 4.0.0 → 5.1.0

package/docs/migrations.md

@@ -1,98 +1,100 @@
 # Migrations
 
-`db/schema.ts` is the single source of truth for your Postgres schema. On every
-deploy, Palbase diffs your declared schema against the live branch database and
-reconciles it — but *how* it reconciles depends on whether the change is safe to
-apply automatically.
-
-## Two kinds of change
-
-### 1. Additive — auto-applied, no migration file
-
-A new table, or a new **nullable** or **defaulted** column, is additive: the
-deploy applies it automatically (`CREATE TABLE` / `ADD COLUMN`) with no manual
-step and no backfill risk. Just edit `db/schema.ts` and deploy.
-
-```ts
-// before
-todos: {
-  id: uuid().primaryKey().defaultRandom(),
-  title: text().notNull(),
-}
-
-// after — additive: `notes` (nullable) + `priority` (defaulted) auto-apply on deploy
-todos: {
-  id: uuid().primaryKey().defaultRandom(),
-  title: text().notNull(),
-  notes: text().nullable(),
-  priority: text().nullable().default("normal"),
-}
-```
+`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.
 
-> A new **NOT NULL column without a default** is NOT additive-safe on a table
-> that already has rows (there is nothing to put in the existing rows). Make it
-> `.nullable()`, give it a `.default(...)`, or apply it as an explicit migration
-> (add nullable → backfill → set NOT NULL).
+## The workflow
 
-### 2. Destructive / type-changing — needs an explicit migration
+```bash
+# 1. Edit db/schema.ts (add a column, a table, a policy, …)
 
-Renaming or dropping a column, changing a column's type, or adding a NOT NULL
-constraint can lose or corrupt existing data — so the deploy's **drift-gate
-blocks them** and the deploy fails until you provide an explicit migration.
-Write the SQL yourself in `db/migrations/`:
+# 2. Generate the migration from the diff (declared schema vs the live branch)
+palbase db diff -f add_priority
+#   → writes db/migrations/<timestamp>_add_priority.sql
 
+# 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
 ```
-db/migrations/
-  001_user_id_to_text.up.sql
-  001_user_id_to_text.down.sql
+
+`palbase db diff` introspects your **live branch database** (there is no local
+database — every branch 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.
+
+## 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
+
+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
--- 001_user_id_to_text.up.sql
-ALTER TABLE todos ALTER COLUMN user_id TYPE text USING user_id::text;
+-- DESTRUCTIVE: dropping todos.notes loses its data
+ALTER TABLE todos DROP COLUMN notes;
 ```
 
+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:
+
 ```sql
--- 001_user_id_to_text.down.sql
-ALTER TABLE todos ALTER COLUMN user_id TYPE uuid USING user_id::uuid;
+-- TYPE CHANGE: todos.priority text -> integer (review; auto-migrate does not ALTER types)
+-- ALTER TABLE todos ALTER COLUMN priority TYPE integer;
 ```
 
-Migrations are golang-migrate style: numbered `NNN_name.up.sql` / `.down.sql`
-pairs, applied in order and tracked so each runs exactly once (idempotent).
-`db/schema.ts` always describes the **end state**; the migration describes **how
-existing data gets there**. Keep the two in sync — after the migration lands,
-`schema.ts` should already reflect the new column type.
+## The drift gate
+
+You can't push a schema change without its migration:
 
-## The drift-gate
+- **`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
+  version live — a broken schema never goes out silently.
 
-On deploy, Palbase compares `db/schema.ts` to the live database:
+## `palbase serve` uses the deployed database
 
-- **Additive** diffs → auto-applied.
-- **Type-changing / destructive** diffs **with** a matching migration → the
-  migration runs.
-- **Type-changing / destructive** diffs **without** a migration → the deploy
-  **aborts** and your currently-running version keeps serving.
+`palbase serve` runs your controllers locally but proxies `Database` and `ctx.*`
+to the **deployed** branch — it does not spin up a local Postgres. So a schema
+change in `db/schema.ts` doesn't exist in the database until you generate the
+migration and push. Run `palbase gen-types` (or just `palbase serve`, which
+regenerates on change) after editing the schema to refresh `palbase-env.d.ts` so
+`Database.tables.<name>` is fully typed in your services.
 
-This is deliberate: it stops an accidental column-type change from silently
-dropping production data. A blocked deploy is a prompt to write the migration,
-not a failure to work around.
+## Hand-written migrations
 
-## Local dev: `palbase serve` uses the deployed database
+`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
+trigger). Keep `db/schema.ts` as the declared end-state so the drift gate passes.
 
-`palbase serve` runs your controllers locally but proxies `Database` and
-`ctx.*` to the **deployed** branch — it does **not** spin up a local Postgres or
-apply migrations locally. So when your local `db/schema.ts` or `db/migrations/`
-is ahead of what's deployed, serve prints a note: new tables/columns won't exist
-until you push. Deploy to apply them.
+## Adding a NOT NULL column to a table with rows
 
-## Workflow
+There's nothing to put in existing rows, so do it in two migrations: first add it
+nullable (or with a default) and backfill, then a follow-up `ALTER ... SET NOT
+NULL`. `db/schema.ts` describes the end state; the migrations describe how
+existing data gets there.
 
-1. Edit `db/schema.ts`.
-2. **Additive** change? → `git push`. It auto-migrates on deploy.
-3. **Type change / rename / drop?** → add `db/migrations/NNN_*.up.sql` (+
-   `.down.sql`), then `git push`. The runner applies it; without it the
-   drift-gate blocks the deploy.
-4. `palbase serve` warns locally until the change is deployed.
+## Row-Level Security
 
-See [schema.md](./schema.md) for the column builders and typed
+Add `rls: true` + `policies: [policy(...)]` to a table in `db/schema.ts`; the
+generated migration emits the `ENABLE ROW LEVEL SECURITY` + `CREATE POLICY` DDL.
+See [schema.md](./schema.md) for the column builders, the policy DSL, and typed
 `Database.tables.*` access.

package/docs/routing.md

@@ -19,22 +19,20 @@ method declares its verb + subpath; the real work lives in a `services/` class
 
 ```ts
 // controllers/places.controller.ts
-import { Controller, Get, Post, Returns, Body, User, z } from "@palbase/backend";
+import { Controller, Get, Post, Body, User } from "@palbase/backend";
 import type { UserT } from "@palbase/backend";
 import { placeService } from "../services/place.service.js";
 import { ImportNearbyBody } from "../models/places/import.js";
-import { PlaceSchema } from "../models/places/shared.js";
+import type { PlaceSchema } from "../models/places/shared.js";  // the return TYPE names the 200 schema
 
 @Controller("/places")
 export default class PlacesController {
   @Post("/import")
-  @Returns(PlaceSchema)
   importNearby(@Body(ImportNearbyBody) body: ImportNearbyBody, @User() user: UserT): PlaceSchema {
     return placeService.importNearby(body.lat, body.lng, user.id);
   }
 
   @Get("/favorites", { auth: false })
-  @Returns(z.array(PlaceSchema))
   listFavorites(): PlaceSchema[] {
     return placeService.listFavorites();
   }
@@ -52,8 +50,10 @@ Rules:
 - A `{segment}` in a path becomes a path param, injected via `@Param("segment")`.
 - Input is declared with the parameter decorators — `@Body(schema)`,
   `@Query(schema)`, `@Param("id")`, `@Headers(schema?)`. The success response is
-  the method's RETURN TYPE; pair it with `@Returns(schema)` so the zod value
-  drives the OpenAPI 200 response (or annotate `: void` for no body).
+  the method's RETURN TYPE (`: PlaceSchema` or `: z.infer<typeof PlaceSchema>`):
+  codegen + the runtime read that named type to drive the OpenAPI 200 response.
+  A body route with no named return type is a build error — annotate `: void`
+  (or `: Promise<void>`) for no body.
 - The operationId is derived FLAT from method + full path (`postPlacesImport`),
   not from the method name. Change `@Post` → `@Put` — no file rename.
 

package/docs/schema.md

@@ -72,7 +72,7 @@ You do **not** wire anything per endpoint. Saving `db/schema.ts` regenerates
 of the schema, no generic, no cast:
 
 ```ts
-import { Controller, Post, Returns, Body, Database, z } from "@palbase/backend";
+import { Controller, Post, Body, Database, z } from "@palbase/backend";
 
 const CreateRoomBody = z.object({ name: z.string() });
 const RoomOut = z.object({ id: z.string(), name: z.string() });
@@ -80,7 +80,8 @@ const RoomOut = z.object({ id: z.string(), name: z.string() });
 @Controller("/rooms")
 export default class RoomsController {
   @Post("")
-  @Returns(RoomOut)
+  // 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 ✓

package/docs/services.md

@@ -90,7 +90,7 @@ await Notifications.sms.send({ /* PalbaseSmsSendParams */ });
 ## Flags
 
 ```ts
-import { Controller, Get, Returns, User, Flags, z } from "@palbase/backend";
+import { Controller, Get, User, Flags, z } from "@palbase/backend";
 import type { UserT } from "@palbase/backend";
 
 const FlagsOut = z.object({ enabled: z.boolean() });
@@ -98,8 +98,7 @@ const FlagsOut = z.object({ enabled: z.boolean() });
 @Controller("/checkout")
 export default class CheckoutController {
   @Get("/flags")                       // auth omitted → required → user is non-null
-  @Returns(FlagsOut)
-  async flags(@User() user: UserT): Promise<z.infer<typeof FlagsOut>> {
+  async flags(@User() user: UserT): Promise<z.infer<typeof FlagsOut>> {  // return type names the 200 schema
     const { data: enabled } = await Flags.isEnabled("new-checkout", { userId: user.id });
     const { data: variant } = await Flags.getVariant("button-color", { userId: user.id });
     return { enabled: enabled ?? false };

package/package.json

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