@everystack/mcp 0.3.2 → 0.4.0

package/src/resources/schema-patterns.md

@@ -1,167 +1,153 @@
 # Schema Design Patterns
 
-> Drizzle schema design, migrations, and RLS setup for everystack apps.
+> Declaring TABLES with `defineModel` in `db/models/` — fields, authz, relations, indexes.
 
 ## When to Use
-Read this when designing your database schema or adding tables to an existing app.
+Read this when designing your database schema or adding tables to an existing app. This
+resource covers **tables** (`defineModel`). For the derived layer —
+views, materialized views, functions, triggers, standalone sequences — read
+`everystack://derived-objects` (they deploy via `db:reconcile`, not migrations). For the
+operational verbs that move a database (`db:sync`, `db:generate`, `db:plan`/`db:apply`,
+`db:check`), read `everystack://database-operations`.
 
 ## Schema Location
 
-Schemas live in `db/schema.ts` (or `db/schema/` directory for larger apps). This file is the single source of truth for both the handler and SSR.
+The whole declared database lives in `db/models/` — one `defineModel` per table, composed
+onto a `defineModule`. This is the single source of truth for the handler, SSR, RLS, and
+grants. You do **not** hand-write `db/schema.ts`, and you do **not** run
+`drizzle-kit generate`/`drizzle-kit migrate` — the Model is authored, and everystack
+generates the migration (`db:generate`) and the typed artifact (`db/schema.generated.ts`,
+never edited). Never hand-write a SQL migration.
 
 ## Basic Table
 
 ```typescript
-import { pgTable, serial, text, integer, timestamp, uuid } from 'drizzle-orm/pg-core';
-
-export const posts = pgTable('posts', {
-  id: uuid('id').defaultRandom().primaryKey(),
-  body: text('body').notNull(),
-  authorId: uuid('author_id').notNull().references(() => users.id),
-  status: text('status').default('draft').notNull(),
-  createdAt: timestamp('created_at').defaultNow().notNull(),
-  updatedAt: timestamp('updated_at').defaultNow().notNull(),
-  deletedAt: timestamp('deleted_at'),
+import { defineModel, field, can } from '@everystack/model';
+
+export const Post = defineModel('posts', {
+  fields: {
+    id: field.uuid().primaryKey().defaultRandom(),
+    body: field.text().notNull(),
+    authorId: field.uuid().notNull().references('users', 'id'),
+    status: field.text().notNull().default('draft'),
+    createdAt: field.timestamptz().notNull().defaultNow(),
+    updatedAt: field.timestamptz().notNull().defaultNow(),
+    deletedAt: field.timestamptz(),
+  },
+  abilities: [can('read'), can('create'), can('update'), can('delete')],
 });
 ```
 
+Column names are `snake_case` in the database; the field key is the app-side name — the
+generator maps `authorId` → `author_id` for you.
+
 ## Common Patterns
 
 ### UUID vs Serial Primary Keys
 Prefer UUID for user-facing IDs (prevents enumeration attacks). Use serial for internal-only tables.
 
 ```typescript
-id: uuid('id').defaultRandom().primaryKey(),  // Preferred for API-exposed tables
-id: serial('id').primaryKey(),                 // OK for internal tables
+id: field.uuid().primaryKey().defaultRandom(),  // Preferred for API-exposed tables
+id: field.serial().primaryKey(),                 // OK for internal tables
 ```
 
 ### Timestamps
 Always include `createdAt` and `updatedAt`:
 ```typescript
-createdAt: timestamp('created_at').defaultNow().notNull(),
-updatedAt: timestamp('updated_at').defaultNow().notNull(),
+createdAt: field.timestamptz().notNull().defaultNow(),
+updatedAt: field.timestamptz().notNull().defaultNow(),
 ```
 
 ### Soft Delete
 Add `deletedAt` for soft-deletable tables:
 ```typescript
-deletedAt: timestamp('deleted_at'),
+deletedAt: field.timestamptz(),
 ```
 Configure in handler: `softDelete: { column: 'deletedAt', tables: ['posts'] }`.
 
 ### Foreign Keys
 ```typescript
-authorId: uuid('author_id').notNull().references(() => users.id),
+authorId: field.uuid().notNull().references('users', 'id'),
 ```
 
 ### Enums
 ```typescript
-import { pgEnum } from 'drizzle-orm/pg-core';
-
-export const roleEnum = pgEnum('role', ['user', 'admin']);
-
-export const users = pgTable('users', {
-  role: roleEnum('role').default('user').notNull(),
-});
+role: field.enum('role', ['user', 'admin']).notNull().default('user'),
 ```
 
-## Relations (Drizzle)
+## Relations
 
-```typescript
-import { relations } from 'drizzle-orm';
+Declare relations on the Model — the generator emits both the Drizzle relations (used by
+the relational query API, `db.query.posts.findMany({ with: { author: true } })`) and the
+handler's embedding config, so they can't drift apart.
 
-export const postsRelations = relations(posts, ({ one, many }) => ({
-  author: one(users, { fields: [posts.authorId], references: [users.id] }),
-  comments: many(comments),
-}));
+```typescript
+export const Post = defineModel('posts', {
+  fields: { /* … */ },
+  relations: {
+    author: { model: 'users', from: 'authorId', to: 'id' },
+    comments: { model: 'comments', from: 'id', to: 'postId', many: true },
+  },
+  abilities: [can('read')],
+});
 ```
 
-Drizzle relations are used by the relational query API (`db.query.posts.findMany({ with: { author: true } })`). The handler also needs its own `relations` config for embedding.
-
 ## Indexes
 
 ```typescript
-import { index, uniqueIndex } from 'drizzle-orm/pg-core';
-
-export const posts = pgTable('posts', {
-  // columns...
-}, (table) => [
-  index('posts_author_id_idx').on(table.authorId),
-  uniqueIndex('posts_slug_idx').on(table.slug),
-]);
+import { defineModel, field, can, index } from '@everystack/model';
+
+export const Post = defineModel('posts', {
+  fields: { /* … */ },
+  indexes: [
+    index(['authorId']),
+    index(['slug']).unique(),
+  ],
+  abilities: [can('read')],
+});
 ```
 
-## Migration Workflow
-
-```bash
-# Generate migration from schema changes
-npx drizzle-kit generate
-
-# Apply migrations locally
-npx drizzle-kit migrate
+## Authorization is declared, not migrated
 
-# Apply migrations on deployed Lambda
-everystack db:migrate
-```
+You never hand-write `CREATE ROLE`, `GRANT`, or `CREATE POLICY`. Abilities on the Model
+compile to grants + RLS, and `db:sync`/`db:apply` deploy them. `can('read')` grants `anon`
++ `authenticated`; `can('read', { role: 'admin' })` narrows to a role. RLS is required —
+the CI gate (`db:check`) refuses a table without it. See `everystack://security` for the
+policy patterns the abilities compile to.
 
-Migration files go in `drizzle/` directory. Each migration is a SQL file.
-
-### RLS Migration Template
-
-After creating tables, add a migration for roles and policies:
-
-```sql
--- Create roles (idempotent)
-DO $$ BEGIN
-  IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'authenticator') THEN
-    CREATE ROLE authenticator LOGIN NOINHERIT;
-  END IF;
-  IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'anon') THEN
-    CREATE ROLE anon NOLOGIN;
-  END IF;
-  IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'authenticated') THEN
-    CREATE ROLE authenticated NOLOGIN;
-  END IF;
-  IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'admin') THEN
-    CREATE ROLE admin NOLOGIN;
-  END IF;
-END $$;
-
-GRANT anon TO authenticator;
-GRANT authenticated TO authenticator;
-GRANT admin TO authenticator;
-
--- Table grants
-GRANT USAGE ON SCHEMA public TO anon, authenticated, admin;
-GRANT SELECT ON posts TO anon;
-GRANT SELECT, INSERT, UPDATE, DELETE ON posts TO authenticated;
-GRANT SELECT, INSERT, UPDATE, DELETE ON posts TO admin;
-
--- Enable RLS
-ALTER TABLE posts ENABLE ROW LEVEL SECURITY;
-ALTER TABLE posts FORCE ROW LEVEL SECURITY;
-
--- Policies (see everystack://security for templates)
+```typescript
+export const Post = defineModel('posts', {
+  fields: { /* … */ },
+  abilities: [
+    can('read'),                              // anon + authenticated
+    can('create', { role: 'authenticated' }),
+    can('update', { role: 'authenticated', own: 'authorId' }),  // row ownership
+    can('delete', { role: 'admin' }),
+  ],
+});
 ```
 
 ## Handler Config for Schema
 
+The handler config is **derived** from the Models (`deriveHandlerConfig(models)`), so
+`exposedTables`, `hiddenColumns`, `protectedFields`, and `relations` come from the
+declarations rather than a hand-kept parallel list:
+
 ```typescript
-createHandler(db, schema, {
-  exposedTables: ['posts', 'profiles'],  // Only these are API-accessible
-  hiddenColumns: { users: ['passwordHash', 'resetToken'] },
-  protectedFields: { profiles: ['role', 'deletedAt'] },
-  relations: {
-    posts: { author: { table: 'users', from: 'authorId', to: 'id' } },
-  },
-});
+import { deriveHandlerConfig } from '@everystack/model';
+import { models } from '../db/models';
+
+createHandler(db, schema, deriveHandlerConfig(models));
 ```
 
 ## Gotchas
 
-- Drizzle column names (camelCase) and SQL column names (snake_case) are both specified: `authorId: uuid('author_id')`
-- The handler's `relations` config uses Drizzle property names, not SQL column names
-- `exposedTables` uses Drizzle table variable names, not SQL table names
-- Always run `drizzle-kit generate` after schema changes
-- RLS migration must be run AFTER table creation migration
-- Connect as `authenticator` in production (never RDS master/superuser)
+- Field keys are app-side names (camelCase); the database column is `snake_case` — the
+  generator maps `authorId` → `author_id`.
+- Edit the Model, then move the database with `db:sync` (dev) or `db:generate` +
+  `db:plan`/`db:apply` (protected stages). Never run `drizzle-kit generate`.
+- RLS and grants are declared with `can()`, never hand-written; `db:check` fails a table
+  without RLS.
+- `db/schema.generated.ts` is a generated artifact — never edit it; `db:check` refuses
+  drift.
+- Connect as `authenticator` in production (never RDS master/superuser).