@vertz/db 0.2.0 → 0.2.1

package/README.md

@@ -1,606 +1,424 @@
 # @vertz/db
 
-Type-safe database layer for Vertz with schema-driven migrations, powerful query building, and full type inference from schema to query results.
-
-## Features
-
-- **Type-safe schema builder** — Define tables, columns, relations with full TypeScript inference
-- **Automatic migrations** — Generate SQL migrations from schema changes
-- **Query builder with relations** — Type-safe CRUD with `include` for nested data loading
-- **Multi-tenant support** — Built-in tenant isolation with `d.tenant()` columns
-- **Connection pooling** — PostgreSQL connection pool with configurable limits
-- **Comprehensive error handling** — Parse and transform Postgres errors with helpful diagnostics
-- **Plugin system** — Extend behavior with lifecycle hooks
-- **Zero runtime overhead** — Types are erased at build time
+Type-safe database layer with schema-driven migrations, phantom types, and Result-based error handling.
 
 ## Installation
 
 ```bash
-npm install @vertz/db
+bun add @vertz/db
 ```
 
 **Prerequisites:**
-- PostgreSQL database
-- Node.js >= 22
+- PostgreSQL or SQLite database
+- Node.js >= 22 or Bun
 
 ## Quick Start
 
-### 1. Define Your Schema
-
 ```typescript
-import { d } from '@vertz/db';
+import { d, createDb } from '@vertz/db';
 
-// Define tables
-const users = d.table('users', {
-  id: d.uuid().primaryKey().defaultValue('gen_random_uuid()'),
-  email: d.email().unique().notNull(),
-  name: d.text().notNull(),
-  createdAt: d.timestamp().defaultValue('now()').notNull(),
-});
-
-const posts = d.table('posts', {
-  id: d.uuid().primaryKey().defaultValue('gen_random_uuid()'),
-  title: d.text().notNull(),
-  content: d.text().notNull(),
-  authorId: d.uuid().notNull(),
-  published: d.boolean().defaultValue('false').notNull(),
-  createdAt: d.timestamp().defaultValue('now()').notNull(),
+// 1. Define table
+const todosTable = d.table('todos', {
+  id: d.uuid().primary(),
+  title: d.text(),
+  completed: d.boolean().default(false),
+  createdAt: d.timestamp().default('now').readOnly(),
+  updatedAt: d.timestamp().autoUpdate(),
 });
 
-// Define relations
-const userRelations = {
-  posts: d.ref.many(() => posts, 'authorId'),
-};
-
-const postRelations = {
-  author: d.ref.one(() => users, 'authorId'),
-};
+// 2. Create model (table + relations + derived schemas)
+const todosModel = d.model(todosTable);
 
-// Create registry
+// 3. Create database client
 const db = createDb({
   url: process.env.DATABASE_URL!,
-  tables: {
-    users: d.entry(users, userRelations),
-    posts: d.entry(posts, postRelations),
-  },
+  models: { todos: todosModel },
 });
-```
-
-### 2. Run Migrations
-
-```typescript
-import { migrateDev } from '@vertz/db';
 
-// Development: auto-generate and apply migrations
-await migrateDev({
-  queryFn: db.queryFn,
-  currentSnapshot: db.snapshot,
-  previousSnapshot: loadPreviousSnapshot(), // From file
-  migrationsDir: './migrations',
+// 4. Query with full type inference and Result-based errors
+const result = await db.create('todos', {
+  data: { title: 'Buy milk' },
 });
 
-// Production: apply migrations from files
-import { migrateDeploy } from '@vertz/db';
-
-await migrateDeploy({
-  queryFn: db.queryFn,
-  migrationsDir: './migrations',
-});
+if (result.ok) {
+  console.log(result.data);
+  // { id: string; title: string; completed: boolean; createdAt: Date; updatedAt: Date }
+}
 ```
 
-### 3. Query Your Data
+## Schema Builder (`d`)
+
+### Column Types
 
 ```typescript
-// Create a user
-const user = await db.users.create({
-  data: {
-    email: 'alice@example.com',
-    name: 'Alice',
-  },
-});
+import { d } from '@vertz/db';
 
-// Find users with posts included
-const usersWithPosts = await db.users.findMany({
-  where: { published: true },
-  include: { posts: true },
-  orderBy: { createdAt: 'desc' },
-  limit: 10,
-});
+// Text
+d.text()                    // TEXT → string
+d.varchar(255)              // VARCHAR(255) → string
+d.email()                   // TEXT with email format → string
 
-// Type-safe: usersWithPosts[0].posts is Post[]
+// Identifiers
+d.uuid()                    // UUID → string
 
-// Update a post
-await db.posts.update({
-  where: { id: postId },
-  data: { published: true },
-});
+// Numeric
+d.integer()                 // INTEGER → number
+d.bigint()                  // BIGINT → bigint
+d.serial()                  // SERIAL (auto-increment) → number
+d.decimal(10, 2)            // NUMERIC(10,2) → string
+d.real()                    // REAL → number
+d.doublePrecision()         // DOUBLE PRECISION → number
 
-// Delete old posts
-await db.posts.deleteMany({
-  where: {
-    createdAt: { lt: new Date('2024-01-01') },
-  },
-});
-```
+// Date/Time
+d.timestamp()               // TIMESTAMP WITH TIME ZONE → Date
+d.date()                    // DATE → string
+d.time()                    // TIME → string
 
-## API Reference
+// Other
+d.boolean()                 // BOOLEAN → boolean
+d.jsonb<MyType>()           // JSONB → MyType
+d.jsonb<MyType>(schema)     // JSONB with runtime validation
+d.textArray()               // TEXT[] → string[]
+d.integerArray()            // INTEGER[] → number[]
+d.enum('status', ['active', 'inactive'])  // ENUM → 'active' | 'inactive'
 
-### Schema Builder (`d`)
+// Multi-tenancy
+d.tenant(orgsTable)         // UUID FK to tenant root → string
+```
 
-The `d` object provides all schema building functions.
+### Column Modifiers
 
-#### Column Types
+Columns are **required by default**. Use modifiers to change behavior:
 
 ```typescript
-// Text types
-d.text()           // TEXT
-d.varchar(255)     // VARCHAR(255)
-d.email()          // TEXT with email format constraint
-d.uuid()           // UUID
-
-// Numeric types
-d.integer()        // INTEGER
-d.bigint()         // BIGINT
-d.serial()         // SERIAL (auto-incrementing integer)
-d.decimal(10, 2)   // DECIMAL(10, 2)
-d.real()           // REAL
-d.doublePrecision() // DOUBLE PRECISION
-
-// Date/time types
-d.timestamp()      // TIMESTAMP WITH TIME ZONE
-d.date()           // DATE
-d.time()           // TIME
-
-// Boolean
-d.boolean()        // BOOLEAN
-
-// JSON
-d.jsonb()          // JSONB
-d.jsonb<MyType>({  // JSONB with validation
-  validator: (v) => MyTypeSchema.parse(v)
-})
-
-// Arrays
-d.textArray()      // TEXT[]
-d.integerArray()   // INTEGER[]
-
-// Enums
-d.enum('status', ['draft', 'published', 'archived'])
-
-// Multi-tenant column
-d.tenant(organizationTable) // UUID with tenant FK
+d.text()
+  .primary()                // PRIMARY KEY (auto-excludes from inputs)
+  .primary({ generate: 'cuid' })  // PRIMARY KEY with ID generation
+  .unique()                 // UNIQUE constraint
+  .nullable()               // Allows NULL (T | null)
+  .default('hello')         // DEFAULT value (makes field optional in inserts)
+  .default('now')           // DEFAULT NOW() for timestamps
+  .hidden()                 // Excluded from default SELECT queries
+  .readOnly()               // Excluded from INSERT/UPDATE inputs
+  .sensitive()              // Excluded when select: { not: 'sensitive' }
+  .autoUpdate()             // Read-only + auto-updated on every write
+  .check('length(name) > 0')  // SQL CHECK constraint
+  .references('users')      // FK to users.id
+  .references('users', 'email')  // FK to users.email
 ```
 
-#### Column Modifiers
+### ID Generation
 
 ```typescript
-d.text()
-  .primaryKey()               // Add to PRIMARY KEY
-  .unique()                   // Add UNIQUE constraint
-  .notNull()                  // Add NOT NULL constraint
-  .defaultValue('default')    // Set default value
-  .index()                    // Add index on this column
+d.uuid().primary()                      // No auto-generation
+d.uuid().primary({ generate: 'cuid' }) // CUID2
+d.uuid().primary({ generate: 'uuid' }) // UUID v7
+d.uuid().primary({ generate: 'nanoid' }) // Nano ID
+d.serial().primary()                    // Auto-increment
 ```
 
-#### Defining Tables
+### Tables
 
 ```typescript
 const users = d.table('users', {
-  id: d.uuid().primaryKey(),
-  email: d.email().unique().notNull(),
-  name: d.text().notNull(),
-}, {
-  indexes: [
-    d.index(['email', 'name']), // Composite index
-  ],
+  id: d.uuid().primary({ generate: 'cuid' }),
+  email: d.email().unique(),
+  name: d.text(),
+  bio: d.text().nullable(),
+  isActive: d.boolean().default(true),
+  createdAt: d.timestamp().default('now').readOnly(),
+  updatedAt: d.timestamp().autoUpdate(),
 });
 ```
 
-#### Defining Relations
+### Annotations
 
-```typescript
-// One-to-many
-const userRelations = {
-  posts: d.ref.many(() => posts, 'authorId'),
-};
+Column annotations control visibility and mutability across the stack:
 
-// Many-to-one
-const postRelations = {
-  author: d.ref.one(() => users, 'authorId'),
-};
+| Annotation | Effect on queries | Effect on inputs | Use case |
+|---|---|---|---|
+| `.hidden()` | Excluded from default SELECT | N/A | Internal fields (password hashes) |
+| `.readOnly()` | Included in responses | Excluded from create/update | Server-managed fields |
+| `.autoUpdate()` | Included in responses | Excluded from create/update | `updatedAt` timestamps |
+| `.sensitive()` | Excluded with `select: { not: 'sensitive' }` | N/A | Fields to exclude in bulk queries |
 
-// Many-to-many (through join table)
-const postTags = d.table('post_tags', {
-  postId: d.uuid().notNull(),
-  tagId: d.uuid().notNull(),
-});
+### Phantom Types
 
-const postRelations = {
-  tags: d.ref.many(() => tags).through(() => postTags, 'postId', 'tagId'),
-};
-```
+Every `TableDef` carries phantom type properties for compile-time type inference:
 
-### Database Client
+```typescript
+const users = d.table('users', {
+  id: d.uuid().primary(),
+  name: d.text(),
+  passwordHash: d.text().hidden(),
+  createdAt: d.timestamp().default('now').readOnly(),
+});
 
-#### `createDb(options)`
+type Response = typeof users.$response;
+// { id: string; name: string; createdAt: Date }
+// (passwordHash excluded — hidden)
 
-Create a database client instance.
+type CreateInput = typeof users.$create_input;
+// { name: string }
+// (id excluded — primary, createdAt excluded — readOnly, passwordHash excluded — hidden)
 
-```typescript
-import { createDb, d } from '@vertz/db';
+type UpdateInput = typeof users.$update_input;
+// { name?: string }
+// (same exclusions, all fields optional)
 
-const db = createDb({
-  url: 'postgresql://user:pass@localhost:5432/mydb',
-  tables: {
-    users: d.entry(usersTable, userRelations),
-    posts: d.entry(postsTable, postRelations),
-  },
-  pool: {
-    max: 20,                  // Max connections (default: 10)
-    idleTimeout: 30000,       // Idle timeout ms (default: 30000)
-    connectionTimeout: 5000,  // Connection timeout ms (default: 10000)
-    healthCheckTimeout: 5000,  // Health check timeout ms (default: 5000)
-    replicas: [               // Read replica URLs for query routing
-      'postgresql://user:pass@localhost:5433/mydb',
-      'postgresql://user:pass@localhost:5434/mydb',
-    ],
-  },
-  casing: 'snake_case',       // or 'camelCase' (default: 'snake_case')
-  log: (msg) => console.log(msg), // Optional logger
-});
+type Insert = typeof users.$insert;
+// { name: string; passwordHash: string; createdAt?: Date }
+// (id excluded — has default, createdAt optional — has default)
 ```
 
-**Returns:** `DatabaseInstance<TTables>` with typed table accessors.
-
-#### Query Methods
-
-All query methods are available on `db.<tableName>`:
+| Phantom type | Description |
+|---|---|
+| `$response` | API response shape (excludes hidden) |
+| `$create_input` | API create input (excludes readOnly + primary) |
+| `$update_input` | API update input (same exclusions, all optional) |
+| `$insert` | DB insert shape (columns with defaults are optional) |
+| `$update` | DB update shape (non-PK columns, all optional) |
+| `$infer` | Default SELECT (excludes hidden) |
+| `$infer_all` | All columns including hidden |
+| `$not_sensitive` | Excludes sensitive + hidden |
 
-##### `findOne(options)`
+### Models
 
-Find a single record (returns `null` if not found).
+`d.model()` combines a table with its relations and derived runtime schemas:
 
 ```typescript
-const user = await db.users.findOne({
-  where: { email: 'alice@example.com' },
-  select: { id: true, name: true }, // Optional: select specific columns
-  include: { posts: true },          // Optional: include relations
+// Without relations
+const todosModel = d.model(todosTable);
+
+// With relations
+const usersModel = d.model(usersTable, {
+  posts: d.ref.many(() => postsTable, 'authorId'),
 });
 
-// Type: { id: string; name: string; posts: Post[] } | null
+const postsModel = d.model(postsTable, {
+  author: d.ref.one(() => usersTable, 'authorId'),
+  comments: d.ref.many(() => commentsTable, 'postId'),
+});
 ```
 
-##### `findOneOrThrow(options)`
-
-Find a single record or throw `NotFoundError`.
+Every model exposes:
 
 ```typescript
-const user = await db.users.findOneOrThrow({
-  where: { id: userId },
-});
+postsModel.table       // the table definition
+postsModel.relations   // { author, comments }
+postsModel.schemas.response     // SchemaLike<$response>
+postsModel.schemas.createInput  // SchemaLike<$create_input>
+postsModel.schemas.updateInput  // SchemaLike<$update_input>
 ```
 
-##### `findMany(options)`
-
-Find multiple records.
+Models are used by `@vertz/server`'s `entity()` to derive validation and type-safe CRUD.
 
-```typescript
-const posts = await db.posts.findMany({
-  where: {
-    published: true,
-    authorId: userId,
-  },
-  orderBy: { createdAt: 'desc' },
-  limit: 10,
-  offset: 0,
-  include: { author: true },
-});
-```
+## Relations
 
-**Cursor-based pagination:**
+Define relations as the second argument to `d.model()`:
 
 ```typescript
-const posts = await db.posts.findMany({
-  where: { published: true },
-  orderBy: { createdAt: 'desc' },
-  cursor: { id: lastPostId }, // Start after this record
-  take: 10,
-});
-```
-
-##### `findManyAndCount(options)`
+import { d } from '@vertz/db';
 
-Find records and get total count (useful for pagination).
+const usersTable = d.table('users', {
+  id: d.uuid().primary(),
+  name: d.text(),
+});
 
-```typescript
-const { rows, count } = await db.posts.findManyAndCount({
-  where: { published: true },
-  limit: 10,
-  offset: 0,
+const postsTable = d.table('posts', {
+  id: d.uuid().primary(),
+  title: d.text(),
+  authorId: d.uuid(),
 });
 
-console.log(`Showing ${rows.length} of ${count} posts`);
-```
+const commentsTable = d.table('comments', {
+  id: d.uuid().primary(),
+  body: d.text(),
+  postId: d.uuid(),
+  authorId: d.uuid(),
+});
 
-##### `create(options)`
+// Models with relations
+const usersModel = d.model(usersTable, {
+  posts: d.ref.many(() => postsTable, 'authorId'),
+});
 
-Insert a single record.
+const postsModel = d.model(postsTable, {
+  author: d.ref.one(() => usersTable, 'authorId'),
+  comments: d.ref.many(() => commentsTable, 'postId'),
+});
 
-```typescript
-const user = await db.users.create({
-  data: {
-    email: 'bob@example.com',
-    name: 'Bob',
-  },
-  select: { id: true, email: true }, // Optional: customize returned fields
+const commentsModel = d.model(commentsTable, {
+  post: d.ref.one(() => postsTable, 'postId'),
+  author: d.ref.one(() => usersTable, 'authorId'),
 });
 ```
 
-##### `createMany(options)`
-
-Insert multiple records (no return value).
+### Relation Types
 
 ```typescript
-await db.posts.createMany({
-  data: [
-    { title: 'Post 1', content: 'Content 1', authorId: userId },
-    { title: 'Post 2', content: 'Content 2', authorId: userId },
-  ],
-});
-```
-
-##### `createManyAndReturn(options)`
+// belongsTo — FK lives on source table
+d.ref.one(() => usersTable, 'authorId')
 
-Insert multiple records and return them.
+// hasMany — FK lives on target table
+d.ref.many(() => postsTable, 'authorId')
 
-```typescript
-const posts = await db.posts.createManyAndReturn({
-  data: [
-    { title: 'Post 1', content: 'Content 1', authorId: userId },
-    { title: 'Post 2', content: 'Content 2', authorId: userId },
-  ],
-  select: { id: true, title: true },
-});
+// Many-to-many — via join table
+d.ref.many(() => coursesTable).through(() => enrollmentsTable, 'studentId', 'courseId')
 ```
 
-##### `update(options)`
+## Database Client
 
-Update a single record.
+### Configuration
 
 ```typescript
-const updatedPost = await db.posts.update({
-  where: { id: postId },
-  data: { published: true, updatedAt: new Date() },
-  select: { id: true, published: true },
+const db = createDb({
+  url: 'postgresql://user:pass@localhost:5432/mydb',
+  models: { users: usersModel, posts: postsModel },
+  dialect: 'postgres',           // 'postgres' (default) or 'sqlite'
+  pool: {
+    max: 20,
+    idleTimeout: 30000,
+    connectionTimeout: 5000,
+    replicas: ['postgresql://...'],
+  },
+  casing: 'snake_case',          // column name transformation
+  log: (msg) => console.log(msg),
 });
 ```
 
-##### `updateMany(options)`
+### Query Methods
 
-Update multiple records (returns count).
+All methods return `Promise<Result<T, Error>>` — never throw.
 
 ```typescript
-const { count } = await db.posts.updateMany({
-  where: { authorId: userId },
-  data: { published: false },
+// Read
+const user = await db.get('users', { where: { id: userId } });
+const users = await db.list('users', {
+  where: { isActive: true },
+  orderBy: { createdAt: 'desc' },
+  limit: 10,
+  include: { posts: true },
 });
+const { data, total } = await db.listAndCount('users', { where: { isActive: true } });
 
-console.log(`Updated ${count} posts`);
-```
-
-##### `upsert(options)`
-
-Insert or update (based on unique constraint).
+// Write
+const created = await db.create('users', {
+  data: { name: 'Alice', email: 'alice@example.com' },
+});
+const updated = await db.update('users', {
+  where: { id: userId },
+  data: { name: 'Bob' },
+});
+const deleted = await db.delete('users', { where: { id: userId } });
 
-```typescript
-const user = await db.users.upsert({
+// Upsert
+const upserted = await db.upsert('users', {
   where: { email: 'alice@example.com' },
-  create: {
-    email: 'alice@example.com',
-    name: 'Alice',
-  },
-  update: {
-    name: 'Alice Updated',
-  },
+  create: { email: 'alice@example.com', name: 'Alice' },
+  update: { name: 'Alice Updated' },
 });
+
+// Bulk
+await db.createMany('users', { data: [{ name: 'A' }, { name: 'B' }] });
+await db.updateMany('users', { where: { isActive: false }, data: { isActive: true } });
+await db.deleteMany('users', { where: { isActive: false } });
 ```
 
-##### `delete(options)`
+### Result-Based Error Handling
 
-Delete a single record.
+Query methods return `Result<T, ReadError | WriteError>` instead of throwing:
 
 ```typescript
-const deleted = await db.users.delete({
-  where: { id: userId },
-  select: { id: true, email: true },
-});
-```
+import { match, matchErr } from '@vertz/schema';
 
-##### `deleteMany(options)`
+const result = await db.create('users', {
+  data: { email: 'exists@example.com', name: 'Alice' },
+});
 
-Delete multiple records (returns count).
+if (result.ok) {
+  console.log('Created:', result.data);
+} else {
+  console.log('Failed:', result.error);
+}
 
-```typescript
-const { count } = await db.posts.deleteMany({
-  where: {
-    createdAt: { lt: new Date('2024-01-01') },
-  },
+// Pattern matching
+match(result, {
+  ok: (user) => console.log('Created:', user.name),
+  err: (error) => console.log('Error:', error.code),
 });
-
-console.log(`Deleted ${count} old posts`);
 ```
 
-#### Filter Operators
-
-Use operators in `where` clauses:
+### Filter Operators
 
 ```typescript
-await db.posts.findMany({
+await db.list('users', {
   where: {
     // Equality
-    published: true,
-    
+    isActive: true,
+
     // Comparison
-    views: { gt: 100 },           // greater than
-    createdAt: { gte: startDate }, // greater than or equal
-    likes: { lt: 50 },            // less than
-    rating: { lte: 3 },           // less than or equal
-    
+    age: { gte: 18, lte: 65 },
+
     // Pattern matching
-    title: { like: '%tutorial%' },
-    email: { ilike: '%@EXAMPLE.COM%' }, // case-insensitive
-    
+    name: { contains: 'Smith' },
+    email: { startsWith: 'admin' },
+
     // Set operations
-    status: { in: ['draft', 'published'] },
-    category: { notIn: ['spam', 'deleted'] },
-    
+    role: { in: ['admin', 'moderator'] },
+    status: { notIn: ['deleted'] },
+
     // Null checks
     deletedAt: { isNull: true },
-    publishedAt: { isNotNull: true },
-    
-    // Logical operators
-    OR: [
-      { authorId: user1Id },
-      { authorId: user2Id },
-    ],
-    AND: [
-      { published: true },
-      { views: { gt: 100 } },
-    ],
-    NOT: { status: 'archived' },
   },
 });
 ```
 
-#### Aggregation
+### Select & Include
 
 ```typescript
-// Count
-const count = await db.posts.count({
-  where: { published: true },
-});
-
-// Sum
-const totalViews = await db.posts.sum('views', {
-  where: { authorId: userId },
-});
-
-// Average
-const avgRating = await db.posts.avg('rating', {
-  where: { published: true },
+// Select specific fields
+await db.get('users', {
+  where: { id: userId },
+  select: { id: true, name: true, email: true },
 });
 
-// Min/Max
-const oldestPost = await db.posts.min('createdAt');
-const newestPost = await db.posts.max('createdAt');
-```
-
-#### Raw SQL Queries
-
-For complex queries, use the raw query function:
-
-```typescript
-import { sql } from '@vertz/db/sql';
-
-const results = await db.query<{ count: number }>(
-  sql`
-    SELECT COUNT(*) as count
-    FROM posts
-    WHERE published = ${true}
-      AND author_id = ${userId}
-  `
-);
-
-console.log(results.rows[0].count);
-```
-
-**Security note:** Always use `sql` tagged template for user input to prevent SQL injection.
-
-#### Timestamp Coercion
-
-> ⚠️ **Important:** The PostgreSQL driver automatically coerces string values that match ISO 8601 timestamp patterns into JavaScript `Date` objects. This applies to all columns, not just declared timestamp columns.
-
-If you store timestamp-formatted strings in plain `text` columns (e.g., `"2024-01-15T10:30:00Z"`), they will be silently converted to `Date` objects when returned from queries.
-
-This behavior uses a heuristic regex (`/^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}/`) to detect timestamp-like strings. Future versions may add column-type-aware coercion to eliminate false positives.
-
-### Migrations
-
-#### `migrateDev(options)`
-
-Development workflow: generate and apply migrations.
-
-```typescript
-import { migrateDev } from '@vertz/db';
-
-const result = await migrateDev({
-  queryFn: db.queryFn,
-  currentSnapshot: db.snapshot,
-  previousSnapshot: loadPreviousSnapshot(), // Load from file
-  migrationsDir: './migrations',
+// Exclude by visibility
+await db.list('users', {
+  select: { not: 'sensitive' },  // excludes sensitive + hidden fields
 });
 
-console.log(`Applied migration: ${result.migrationName}`);
-console.log(`SQL:\n${result.sql}`);
-
-// Save current snapshot for next time
-fs.writeFileSync(
-  './schema-snapshot.json',
-  JSON.stringify(db.snapshot, null, 2)
-);
-```
-
-#### `migrateDeploy(options)`
-
-Production: apply pending migrations from files.
-
-```typescript
-import { migrateDeploy } from '@vertz/db';
-
-const result = await migrateDeploy({
-  queryFn: db.queryFn,
-  migrationsDir: './migrations',
+// Include relations
+await db.list('posts', {
+  include: { author: true, comments: true },
 });
-
-console.log(`Applied ${result.appliedCount} migrations`);
 ```
 
-#### `migrateStatus(options)`
-
-Check migration status.
+### Aggregation
 
 ```typescript
-import { migrateStatus } from '@vertz/db';
+// Count
+const count = await db.count('users', { where: { isActive: true } });
 
-const status = await migrateStatus({
-  queryFn: db.queryFn,
-  migrationsDir: './migrations',
+// Aggregate functions
+await db.aggregate('orders', {
+  where: { status: 'completed' },
+  _count: true,
+  _sum: { price: true },
+  _avg: { amount: true },
+  _min: { discount: true },
+  _max: { total: true },
 });
 
-for (const migration of status.migrations) {
-  console.log(`${migration.name}: ${migration.applied ? '✓' : '✗'}`);
-}
-```
-
-#### `push(options)`
-
-Push schema changes directly without creating migration files (development only).
-
-```typescript
-import { push } from '@vertz/db';
-
-const result = await push({
-  queryFn: db.queryFn,
-  currentSnapshot: db.snapshot,
-  previousSnapshot: loadPreviousSnapshot(),
+// Group by
+await db.groupBy('orders', {
+  by: ['customerId', 'status'],
+  _count: true,
+  _sum: { total: true },
 });
-
-console.log(`Pushed changes to: ${result.tablesAffected.join(', ')}`);
 ```
 
-### Error Handling
-
-`@vertz/db` provides typed error classes for common database errors:
+## Error Types
 
 ```typescript
 import {
@@ -610,312 +428,212 @@ import {
   NotNullError,
   CheckConstraintError,
   ConnectionError,
-  DbError,
+  dbErrorToHttpError,
 } from '@vertz/db';
-
-try {
-  await db.users.create({
-    data: { email: 'duplicate@example.com', name: 'Test' },
-  });
-} catch (error) {
-  if (error instanceof UniqueConstraintError) {
-    console.error(`Unique constraint violated on: ${error.constraint}`);
-    console.error(`Table: ${error.table}, Column: ${error.column}`);
-  } else if (error instanceof ForeignKeyError) {
-    console.error(`Foreign key violation: ${error.constraint}`);
-  } else if (error instanceof NotNullError) {
-    console.error(`Not null constraint on: ${error.column}`);
-  }
-  throw error;
-}
 ```
 
-#### Diagnostic Utilities
-
-Get helpful error explanations:
+| Error | HTTP Status | When |
+|---|---|---|
+| `NotFoundError` | 404 | Record not found |
+| `UniqueConstraintError` | 409 | Duplicate unique value |
+| `ForeignKeyError` | 409 | Referenced record doesn't exist |
+| `NotNullError` | 422 | Required field missing |
+| `CheckConstraintError` | 422 | CHECK constraint violated |
+| `ConnectionError` | 503 | Database unreachable |
 
 ```typescript
-import { diagnoseError, formatDiagnostic } from '@vertz/db';
-
-try {
-  await db.users.create({ data: { email: null, name: 'Test' } });
-} catch (error) {
-  const diagnostic = diagnoseError(error);
-  if (diagnostic) {
-    console.error(formatDiagnostic(diagnostic));
-    // Output:
-    // ERROR: Not null constraint violated on column "email"
-    // Table: users
-    // Suggestion: Ensure the email field is provided and not null
-  }
-}
+const httpError = dbErrorToHttpError(error);
+// Converts any db error to the appropriate HTTP status
 ```
 
-#### HTTP Error Mapping
-
-Convert database errors to HTTP status codes:
+## Diagnostics
 
 ```typescript
-import { dbErrorToHttpError } from '@vertz/db';
-
-try {
-  await db.users.findOneOrThrow({ where: { id: userId } });
-} catch (error) {
-  const httpError = dbErrorToHttpError(error);
-  return new Response(JSON.stringify(httpError), {
-    status: httpError.status,
-  });
-}
+import { diagnoseError, formatDiagnostic, explainError } from '@vertz/db';
 
-// NotFoundError → 404
-// UniqueConstraintError → 409 Conflict
-// ForeignKeyError → 409 Conflict
-// CheckConstraintError → 422 Unprocessable Entity
-// NotNullError → 422 Unprocessable Entity
-```
+const diagnostic = diagnoseError(error.message);
+// {
+//   code: 'NOT_NULL_VIOLATION',
+//   explanation: 'Not null constraint violated on column "email"',
+//   table: 'users',
+//   suggestion: 'Ensure the email field is provided and not null'
+// }
 
-### Multi-Tenant Support
+console.log(formatDiagnostic(diagnostic));
+console.log(explainError(error.message));
+```
 
-Built-in support for tenant isolation:
+## Multi-Tenancy
 
 ```typescript
-// Define organization table
-const organizations = d.table('organizations', {
-  id: d.uuid().primaryKey(),
-  name: d.text().notNull(),
+import { d, computeTenantGraph } from '@vertz/db';
+
+const orgsTable = d.table('organizations', {
+  id: d.uuid().primary(),
+  name: d.text(),
 });
 
-// Add tenant column to scoped tables
-const posts = d.table('posts', {
-  id: d.uuid().primaryKey(),
-  organizationId: d.tenant(organizations), // Automatic FK to organizations.id
-  title: d.text().notNull(),
-  content: d.text().notNull(),
+const usersTable = d.table('users', {
+  id: d.uuid().primary(),
+  email: d.email(),
+  orgId: d.tenant(orgsTable),  // scopes this table to a tenant
 });
 
-// Compute tenant graph (for automatic scoping)
-import { computeTenantGraph } from '@vertz/db';
+const orgsModel = d.model(orgsTable);
+const usersModel = d.model(usersTable);
 
-const tenantGraph = computeTenantGraph({
-  users: d.entry(users),
-  organizations: d.entry(organizations),
-  posts: d.entry(posts), // Will be marked as tenant-scoped
-});
+const tenantGraph = computeTenantGraph({ organizations: orgsModel, users: usersModel });
 
-console.log(tenantGraph.scopedTables); // ['posts']
+tenantGraph.root;            // 'organizations'
+tenantGraph.directlyScoped;  // ['users']
 ```
 
-### Plugin System
+Tables can be marked as shared (cross-tenant):
+
+```typescript
+const settings = d.table('settings', { /* ... */ }).shared();
+```
 
-Extend `@vertz/db` with custom behavior:
+## Dialects
 
 ```typescript
-import type { DbPlugin } from '@vertz/db/plugin';
-
-const auditLogPlugin: DbPlugin = {
-  name: 'audit-log',
-  
-  hooks: {
-    beforeCreate: async (tableName, data) => {
-      console.log(`Creating ${tableName}:`, data);
-    },
-    
-    afterCreate: async (tableName, result) => {
-      await logToAuditTable(tableName, 'create', result);
-    },
-    
-    beforeUpdate: async (tableName, where, data) => {
-      console.log(`Updating ${tableName}:`, { where, data });
-    },
-    
-    afterDelete: async (tableName, result) => {
-      await logToAuditTable(tableName, 'delete', result);
-    },
-  },
-};
+import { createDb, defaultPostgresDialect, defaultSqliteDialect } from '@vertz/db';
 
-const db = createDb({
-  url: process.env.DATABASE_URL!,
-  tables: { /* ... */ },
-  plugins: [auditLogPlugin],
+// PostgreSQL (default)
+const pgDb = createDb({ url: 'postgresql://...', models });
+
+// SQLite
+const sqliteDb = createDb({
+  models,
+  dialect: 'sqlite',
+  d1: d1Database,  // Cloudflare D1 or compatible
 });
 ```
 
-## Type Safety Features
+## Migrations
 
-### Schema to Query Type Flow
+```bash
+# Generate and apply migrations (development)
+vertz db migrate
 
-Types flow automatically from schema definition to query results:
+# Apply migrations from files (production)
+vertz db migrate --deploy
 
-```typescript
-// 1. Define schema
-const users = d.table('users', {
-  id: d.uuid(),
-  email: d.email(),
-  name: d.text(),
-  age: d.integer().nullable(), // Optional field
-});
+# Check migration status
+vertz db migrate --status
 
-// 2. Query with full inference
-const user = await db.users.findOne({
-  where: { email: 'test@example.com' },
-  select: { id: true, name: true },
-});
+# Push schema directly without migration files (dev only)
+vertz db push
+```
 
-// 3. Type is inferred: { id: string; name: string } | null
+### Programmatic API
 
-// 4. With relations
-const userWithPosts = await db.users.findOne({
-  where: { id: userId },
-  include: { posts: true },
+```typescript
+import { migrateDev, migrateDeploy, migrateStatus, push } from '@vertz/db';
+
+await migrateDev({
+  queryFn: db.queryFn,
+  currentSnapshot: db.snapshot,
+  previousSnapshot: loadFromFile(),
+  migrationsDir: './migrations',
 });
 
-// 5. Type is inferred: { id: string; email: string; name: string; age: number | null; posts: Post[] } | null
+await migrateDeploy({
+  queryFn: db.queryFn,
+  migrationsDir: './migrations',
+});
 ```
 
-### Insert Type Inference
+### Auto-Migrate
 
-Insert types respect `notNull()`, `defaultValue()`, and `nullable()`:
+For development workflows, `autoMigrate` diffs the current schema against a saved snapshot and applies changes automatically — no migration files needed.
 
 ```typescript
-const users = d.table('users', {
-  id: d.uuid().primaryKey().defaultValue('gen_random_uuid()'), // Auto-generated
-  email: d.email().notNull(),  // Required
-  name: d.text().notNull(),    // Required
-  bio: d.text().nullable(),    // Optional
-  createdAt: d.timestamp().defaultValue('now()'), // Auto-generated
-});
-
-// Type inference for insert:
-await db.users.create({
-  data: {
-    // id: NOT required (has default)
-    email: 'test@example.com', // REQUIRED
-    name: 'Test User',         // REQUIRED
-    bio: null,                 // OPTIONAL (can be null or omitted)
-    // createdAt: NOT required (has default)
-  },
+import { autoMigrate } from '@vertz/db';
+
+await autoMigrate({
+  currentSchema, // from d.table() definitions
+  snapshotPath: '.vertz/schema-snapshot.json',
+  dialect: 'sqlite',
+  db: queryFn,
 });
 ```
 
-### Select Type Narrowing
-
-Select only specific columns with full type safety:
+When using `createDbProvider`, auto-migration runs automatically in non-production environments:
 
 ```typescript
-const user = await db.users.findOne({
-  where: { id: userId },
-  select: {
-    id: true,
-    email: true,
-    // name intentionally omitted
+import { createDbProvider } from '@vertz/db/core';
+
+const dbProvider = createDbProvider({
+  url: process.env.DATABASE_URL!,
+  models: { users: { table: users, relations: {} } },
+  migrations: {
+    autoApply: true, // explicit opt-in (defaults to NODE_ENV !== 'production')
+    snapshotPath: '.vertz/schema-snapshot.json',
   },
 });
-
-// Type: { id: string; email: string } | null
-// user.name ← TypeScript error: Property 'name' does not exist
 ```
 
-### Branded Error Types
+### Custom Snapshot Storage
 
-Compile-time errors for invalid queries:
+By default, snapshots are stored on the filesystem via `NodeSnapshotStorage`. For non-Node runtimes (Cloudflare Workers, Deno Deploy) or custom backends, implement the `SnapshotStorage` interface:
 
 ```typescript
-// ❌ TypeScript error: Invalid column
-await db.users.findMany({
-  where: { invalidColumn: 'value' }, // Error: 'invalidColumn' does not exist on User
-});
+import type { SnapshotStorage, SchemaSnapshot } from '@vertz/db';
 
-// ❌ TypeScript error: Invalid relation
-await db.users.findOne({
-  include: { invalidRelation: true }, // Error: 'invalidRelation' is not a valid relation
-});
-
-// ❌ TypeScript error: Invalid filter operator
-await db.posts.findMany({
-  where: { title: { invalidOp: 'value' } }, // Error: 'invalidOp' is not a valid operator
-});
-```
+class KVSnapshotStorage implements SnapshotStorage {
+  constructor(private kv: KVNamespace) {}
 
-## Integration with @vertz/schema
+  async load(key: string): Promise<SchemaSnapshot | null> {
+    const data = await this.kv.get(key);
+    return data ? JSON.parse(data) : null;
+  }
 
-Use `@vertz/schema` for additional validation on JSONB columns:
+  async save(key: string, snapshot: SchemaSnapshot): Promise<void> {
+    await this.kv.put(key, JSON.stringify(snapshot));
+  }
+}
 
-```typescript
-import { d } from '@vertz/db';
-import { s } from '@vertz/schema';
-
-// Define a schema for JSONB data
-const MetadataSchema = s.object({
-  tags: s.array(s.string()),
-  priority: s.enum(['low', 'medium', 'high']),
-  dueDate: s.string().datetime().nullable(),
-});
-
-// Use the schema as a JSONB validator
-const tasks = d.table('tasks', {
-  id: d.uuid().primaryKey(),
-  title: d.text().notNull(),
-  metadata: d.jsonb<typeof MetadataSchema._output>({
-    validator: (value) => MetadataSchema.parse(value),
-  }),
-});
-
-// Insert with validated JSONB
-await db.tasks.create({
-  data: {
-    title: 'Complete documentation',
-    metadata: {
-      tags: ['docs', 'p0'],
-      priority: 'high',
-      dueDate: '2024-12-31T23:59:59Z',
-    },
+// Pass to autoMigrate or createDbProvider
+await autoMigrate({
+  currentSchema,
+  snapshotPath: 'schema-snapshot',
+  dialect: 'sqlite',
+  db: queryFn,
+  storage: new KVSnapshotStorage(env.SNAPSHOTS),
+});
+
+// Or via the provider
+const dbProvider = createDbProvider({
+  url: env.DATABASE_URL,
+  models,
+  migrations: {
+    storage: new KVSnapshotStorage(env.SNAPSHOTS),
   },
 });
-
-// Query returns typed JSONB
-const task = await db.tasks.findOne({ where: { id: taskId } });
-// task.metadata is typed as { tags: string[]; priority: 'low' | 'medium' | 'high'; dueDate: string | null }
 ```
 
-## Best Practices
-
-1. **Use migrations in production** — Never use `push()` in production; always use `migrateDeploy()`
-2. **Store schema snapshots** — Commit `schema-snapshot.json` to version control
-3. **Leverage type inference** — Let TypeScript infer types; avoid manual type annotations
-4. **Use relations wisely** — `include` loads related data, but use `select` to avoid over-fetching
-5. **Prefer `findOneOrThrow`** — More explicit than null checks for required data
-6. **Use connection pooling** — Configure `pool.max` based on your load
-7. **Handle specific errors** — Catch `UniqueConstraintError`, `ForeignKeyError`, etc. for better UX
-8. **Use `sql` template for raw queries** — Prevents SQL injection
-9. **Test migrations locally** — Run `migrateDev` locally before deploying
-
-## Casing Strategy
+| Interface | Method | Description |
+|-----------|--------|-------------|
+| `SnapshotStorage` | `load(key: string)` | Load a snapshot by key. Returns `null` on first run |
+| `SnapshotStorage` | `save(key: string, snapshot)` | Persist a snapshot |
+| `NodeSnapshotStorage` | (class) | Built-in filesystem implementation using `node:fs` |
 
-By default, `@vertz/db` uses `snake_case` for database column names (PostgreSQL convention):
+## Raw SQL
 
 ```typescript
-const users = d.table('users', {
-  firstName: d.text(), // Stored as "first_name" in database
-  lastName: d.text(),  // Stored as "last_name"
-});
-
-// Use camelCase in queries:
-await db.users.create({
-  data: { firstName: 'Alice', lastName: 'Smith' },
-});
+import { sql } from '@vertz/db/sql';
 
-// Automatically converted to snake_case in SQL
-```
+const result = await db.query(
+  sql`SELECT * FROM users WHERE email = ${email}`
+);
 
-To use `camelCase` in the database:
+// Composition
+const where = sql`WHERE active = ${true}`;
+const query = sql`SELECT * FROM users ${where}`;
 
-```typescript
-const db = createDb({
-  url: process.env.DATABASE_URL!,
-  tables: { /* ... */ },
-  casing: 'camelCase',
-});
+// Raw (unparameterized)
+const col = sql.raw('created_at');
 ```
 
 ## License