relq 1.0.96 → 1.0.98

package/README.md

@@ -2,7 +2,7 @@
 
 **The Fully-Typed PostgreSQL ORM for TypeScript**
 
-Relq is a complete, type-safe ORM for PostgreSQL that brings the full power of the database to TypeScript. With support for 100+ PostgreSQL types, advanced features like partitions, domains, composite types, generated columns, enums, triggers, functions, and a git-like CLI for schema management—all with zero runtime dependencies.
+Relq is a complete, type-safe ORM for PostgreSQL that brings the full power of the database to TypeScript. With support for 100+ PostgreSQL types, advanced features like partitions, domains, composite types, generated columns, enums, triggers, functions, and a CLI for schema management — all with zero runtime dependencies.
 
 [![npm version](https://img.shields.io/npm/v/relq.svg)](https://www.npmjs.com/package/relq)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
@@ -17,11 +17,20 @@ Relq is a complete, type-safe ORM for PostgreSQL that brings the full power of t
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Entry Points](#entry-points)
+- [Multi-Dialect Support](#multi-dialect-support)
 - [Schema Definition](#schema-definition)
 - [Query API](#query-api)
+- [Joins](#joins)
+- [Relation Loading](#relation-loading)
+- [Computed Columns](#computed-columns)
+- [Convenience Methods](#convenience-methods)
+- [Raw SQL](#raw-sql)
 - [SQL Functions](#sql-functions)
 - [Condition Builders](#condition-builders)
+- [Pagination](#pagination)
+- [Transactions](#transactions)
 - [Advanced Schema Features](#advanced-schema-features)
+- [DDL Builders](#ddl-builders)
 - [CLI Commands](#cli-commands)
 - [Configuration](#configuration)
 - [Error Handling](#error-handling)
@@ -39,10 +48,28 @@ Relq is a complete, type-safe ORM for PostgreSQL that brings the full power of t
 - **Tree-Shakeable** — Import only what you use for optimal bundle size
 - **Schema-First Design** — Define once, get types everywhere
 
+### Multi-Dialect Support
+
+- **PostgreSQL** — Full native support
+- **CockroachDB** — Dedicated client with CockroachDB-compatible feature set
+- **Nile** — Multi-tenant PostgreSQL with `setTenant()` / `withTenant()`
+- **AWS DSQL** — Amazon Aurora DSQL with AWS credential support
+
+### Query Features
+
+- **Relation Loading** — `.with()` and `.withMany()` for auto-FK joins without writing join conditions
+- **Computed Columns** — `.include()` for inline aggregates and expressions
+- **One-to-Many Joins** — LATERAL subqueries via `.joinMany()` / `.leftJoinMany()`
+- **Many-to-Many** — Junction table support via `{ through: 'table' }`
+- **Tagged Template SQL** — `` sql`SELECT * FROM users WHERE id = ${id}` `` with auto-escaping
+- **Nested Creates** — `.createWith()` inserts parent + children in a single transaction
+- **INSERT FROM SELECT** — `.insertFrom()` with type-safe callback
+- **Cursor Iteration** — `.each()` for memory-efficient row-by-row processing
+- **Conflict Handling** — `.doUpdate()` / `.doNothing()` with EXCLUDED column access
+
 ### Schema Management
 
-- **Git-like CLI** — Familiar commands (`pull`, `push`, `diff`, `status`, `branch`, `merge`)
-- **Automatic Migrations** — Generate migrations from schema changes
+- **CLI** — Commands for `pull`, `push`, `diff`, `generate`, `migrate`, `rollback`, `sync`
 - **Database Introspection** — Generate TypeScript schema from existing databases
 - **Tracking IDs** — Detect renames and moves, not just additions/deletions
 
@@ -54,7 +81,12 @@ Relq is a complete, type-safe ORM for PostgreSQL that brings the full power of t
 - **Triggers & Functions** — Define and track database-side logic
 - **Full-Text Search** — `tsvector`, `tsquery` with ranking functions
 - **PostGIS Support** — Geometry and geography types for spatial data
-- **AWS DSQL Support** — First-class support for Amazon Aurora DSQL
+- **CTE** — Common Table Expressions for recursive and complex queries
+- **Window Functions** — `OVER`, `PARTITION BY`, `ROW_NUMBER()`, etc.
+- **LISTEN/NOTIFY** — Real-time pub/sub
+- **COPY** — Bulk import/export with `COPY TO` / `COPY FROM`
+- **Query Cache** — Built-in caching with TTL and invalidation strategies
+- **EXPLAIN** — Query analysis and optimization
 
 ---
 
@@ -78,12 +110,10 @@ import {
   defineTable,
   uuid, text, timestamp, boolean, integer, jsonb,
   pgEnum, pgRelations
-} from 'relq/schema-builder';
+} from 'relq/pg-builder';
 
-// Enums with full type inference
 export const userStatus = pgEnum('user_status', ['active', 'inactive', 'suspended']);
 
-// Tables with complete column typing
 export const users = defineTable('users', {
   id: uuid().primaryKey().default('gen_random_uuid()'),
   email: text().notNull().unique(),
@@ -103,7 +133,6 @@ export const posts = defineTable('posts', {
   createdAt: timestamp('created_at').default('now()'),
 });
 
-// Define relationships
 export const relations = pgRelations({
   users: { posts: { type: 'many', table: 'posts', foreignKey: 'authorId' } },
   posts: { author: { type: 'one', table: 'users', foreignKey: 'authorId' } }
@@ -118,7 +147,7 @@ export const schema = { users, posts };
 import { Relq } from 'relq';
 import { schema, relations } from './db/schema';
 
-const db = new Relq(schema, {
+const db = new Relq(schema, 'postgres', {
   host: 'localhost',
   port: 5432,
   database: 'myapp',
@@ -129,7 +158,7 @@ const db = new Relq(schema, {
 
 // Types flow automatically from schema to results
 const activeUsers = await db.table.users
-  .select(['id', 'email', 'status'])
+  .select('id', 'email', 'status')
   .where(q => q.equal('status', 'active'))
   .orderBy('createdAt', 'DESC')
   .limit(10)
@@ -138,31 +167,73 @@ const activeUsers = await db.table.users
 
 // Convenience methods
 const user = await db.table.users.findById('uuid-here');
-const user = await db.table.users.findOne({ email: 'test@example.com' });
+const found = await db.table.users.findOne({ email: 'test@example.com' });
 ```
 
 ---
 
 ## Entry Points
 
-Relq provides three entry points for different use cases:
-
 ```typescript
-// Runtime - Client, queries, functions
-import { Relq, F, Case, PG } from 'relq';
+// Runtime — Client, queries, functions
+import { Relq, F, Case, PG, sql, SqlFragment } from 'relq';
+
+// Dialect clients (direct usage)
+import { RelqPostgres, RelqNile, RelqDsql, RelqCockroachDB } from 'relq';
 
-// Configuration - CLI and project setup
+// Configuration — CLI and project setup
 import { defineConfig, loadConfig } from 'relq/config';
 
-// Schema Builder - Types, tables, DDL definitions
-import {
-  defineTable,
-  integer, text, uuid, jsonb, timestamp,
-  pgEnum, pgDomain, pgComposite, pgTrigger, pgFunction,
-  pgRelations, one, many
-} from 'relq/schema-builder';
+// Schema Builder — PostgreSQL (full)
+import { defineTable, uuid, text, pgEnum, pgRelations } from 'relq/pg-builder';
+
+// Schema Builder — Dialect-specific (compile-time safety)
+import { defineTable } from 'relq/cockroachdb-builder';
+import { defineTable } from 'relq/nile-builder';
+import { defineTable } from 'relq/dsql-builder';
+```
+
+---
+
+## Multi-Dialect Support
+
+Relq supports 4 PostgreSQL-family dialects. Each dialect client only exposes methods it supports, enforced at both compile time and runtime.
+
+```typescript
+// PostgreSQL — full feature set including subscribe()
+const db = new Relq(schema, 'postgres', { host, database, user, password });
+
+// CockroachDB — no geometric types, no ranges, no full-text
+const db = new Relq(schema, 'cockroachdb', { host, database, user, password });
+
+// Nile — multi-tenant PostgreSQL
+const db = new Relq(schema, 'nile', { host, database, user, password });
+await db.setTenant(tenantId);
+
+// AWS DSQL — no subscribe, no triggers, no sequences, no LATERAL
+const db = new Relq(schema, 'awsdsql', { database, aws: { region, hostname } });
+```
+
+Dialect-specific schema builders prevent using unsupported types at compile time:
+
+```typescript
+// Using CockroachDB builder — geometric types won't be available
+import { defineTable, text, uuid, jsonb } from 'relq/cockroachdb-builder';
+// point(), line(), money() — not exported, compile error if used
 ```
 
+### Capability Matrix
+
+| Feature | PostgreSQL | CockroachDB | Nile | AWS DSQL |
+|---------|-----------|-------------|------|----------|
+| RETURNING | Yes | Yes | Yes | Yes |
+| LATERAL JOIN | Yes | Yes | Yes | No |
+| DISTINCT ON | Yes | Yes | Yes | No |
+| FOR UPDATE SKIP LOCKED | Yes | Yes | Yes | No |
+| Cursors | Yes | Yes | Yes | No |
+| LISTEN/NOTIFY | Yes | No | No | No |
+| Multi-tenant | No | No | Yes | No |
+
 ---
 
 ## Schema Definition
@@ -217,7 +288,6 @@ uuid()                             // string
 
 #### Array Types
 ```typescript
-// Any column type can be an array
 tags: text().array()               // string[]
 matrix: integer().array(2)         // number[][] (2D array)
 scores: numeric().array()          // string[]
@@ -246,7 +316,6 @@ macaddr(), macaddr8()              // string
 int4range(), int8range()           // string
 numrange(), daterange()            // string
 tsrange(), tstzrange()             // string
-// Multi-range variants also available
 ```
 
 #### Full-Text Search
@@ -281,44 +350,49 @@ semver()                           // string
 // All columns
 const users = await db.table.users.select().all();
 
-// Specific columns
+// Specific columns — array or variadic
 const emails = await db.table.users.select(['id', 'email']).all();
+const emails = await db.table.users.select('id', 'email').all();
 
-// With conditions
+// With conditions, ordering, limit
 const active = await db.table.users
-  .select(['id', 'email', 'name'])
+  .select('id', 'email', 'name')
   .where(q => q.equal('status', 'active'))
   .orderBy('createdAt', 'DESC')
   .limit(10)
   .all();
 
-// Single record
+// Single record (auto LIMIT 1)
 const user = await db.table.users
   .select()
   .where(q => q.equal('id', userId))
   .get();
 
-// With joins
-const postsWithAuthors = await db.table.posts
-  .select(['id', 'title'])
-  .join('users', (on, posts, users) => on.equal(posts.authorId, users.id))
+// NULLS FIRST / NULLS LAST ordering
+await db.table.users.select()
+  .orderByNulls('deletedAt', 'ASC', 'LAST')
   .all();
 
 // Distinct on (PostgreSQL-specific)
-await db.table.logs
-  .select()
+await db.table.logs.select()
   .distinctOn('userId')
   .orderBy('userId')
   .orderBy('createdAt', 'DESC')
   .all();
 
+// Set operations
+const query1 = db.table.users.select('id', 'email').where(q => q.equal('status', 'active'));
+const query2 = db.table.users.select('id', 'email').where(q => q.equal('role', 'admin'));
+await query1.union(query2).all();
+// Also: unionAll, intersect, except
+
 // Row locking
-await db.table.jobs
-  .select()
+await db.table.jobs.select()
   .where(q => q.equal('status', 'pending'))
   .forUpdateSkipLocked()
   .limit(1)
   .get();
+// Also: forUpdate(), forShare()
 ```
 
 ### INSERT
@@ -327,30 +401,36 @@ await db.table.jobs
 // Single insert with returning
 const user = await db.table.users
   .insert({ email: 'new@example.com', name: 'New User' })
-  .returning(['id', 'createdAt'])
+  .returning('*')
   .run();
 
-// Bulk insert
+// Multi-row insert
 await db.table.users
-  .insert([
-    { email: 'user1@example.com', name: 'User 1' },
-    { email: 'user2@example.com', name: 'User 2' }
-  ])
+  .insert({ email: 'user1@example.com', name: 'User 1' })
+  .addRow({ email: 'user2@example.com', name: 'User 2' })
   .run();
 
-// Upsert - ON CONFLICT DO UPDATE
+// ON CONFLICT DO UPDATE (upsert) — with EXCLUDED column access
 await db.table.users
-  .insert({ email: 'user@example.com', name: 'Updated' })
-  .onConflict('email')
-  .doUpdate({ name: 'Updated', updatedAt: PG.now() })
+  .insert({ email: 'user@example.com', name: 'New' })
+  .doUpdate('email', {
+    name: (excluded, sql) => excluded.name,             // Use EXCLUDED value
+    score: (excluded, sql, row) => sql.greatest(excluded.score, row.score),
+  })
   .run();
 
 // ON CONFLICT DO NOTHING
 await db.table.users
   .insert({ email: 'user@example.com', name: 'New' })
-  .onConflict('email')
-  .doNothing()
+  .doNothing('email')
   .run();
+
+// INSERT FROM SELECT — callback receives schema tables
+const count = await db.table.archivedUsers.insertFrom(
+  ['name', 'email', 'createdAt'],
+  t => t.users.select('name', 'email', 'createdAt')
+    .where(q => q.equal('status', 'inactive'))
+);
 ```
 
 ### UPDATE
@@ -366,13 +446,7 @@ await db.table.users
 const updated = await db.table.posts
   .update({ viewCount: F.increment('viewCount', 1) })
   .where(q => q.equal('id', postId))
-  .returning(['id', 'viewCount'])
-  .run();
-
-// Bulk update
-await db.table.posts
-  .update({ published: true })
-  .where(q => q.in('id', postIds))
+  .returning('*')
   .run();
 ```
 
@@ -402,7 +476,7 @@ const count = await db.table.users
   .where(q => q.equal('status', 'active'))
   .get();
 
-// Count with groups
+// Named count groups
 const counts = await db.table.results.count()
   .group('all', q => q.equal('isDeleted', false))
   .group('new', q => q.equal('isRead', false).equal('isDeleted', false))
@@ -411,9 +485,8 @@ const counts = await db.table.results.count()
   .get();
 // Returns: { all: number, new: number, favorites: number }
 
-// Multiple aggregations
-const stats = await db.table.orders
-  .aggregate()
+// Multiple aggregation functions
+const stats = await db.table.orders.aggregate()
   .count('id', 'totalOrders')
   .sum('amount', 'totalRevenue')
   .avg('amount', 'avgOrderValue')
@@ -422,28 +495,272 @@ const stats = await db.table.orders
   .get();
 ```
 
-### Pagination
+---
+
+## Joins
+
+### Type-Safe Joins
+
+Join callbacks receive `(on, joined, source)` — the joined table is always the second parameter.
 
 ```typescript
-// Cursor-based (recommended for large datasets)
-const page = await db.table.posts
-  .select(['id', 'title', 'createdAt'])
-  .paginate({ orderBy: ['createdAt', 'DESC'] })
-  .paging({ perPage: 20, cursor: lastCursor });
+// INNER JOIN — auto FK detection (requires relations config)
+const postsWithAuthors = await db.table.posts.select()
+  .join('users')
+  .all();
+// Result: { ...post, users: { id, name, ... } }[]
 
-// page.data - results
-// page.pagination.next - cursor for next page
-// page.pagination.hasNext - boolean
+// INNER JOIN — explicit callback
+const postsWithAuthors = await db.table.posts.select('id', 'title')
+  .join('users', (on, users, posts) =>
+    on.equal(users.id, posts.authorId)
+  )
+  .all();
 
-// Offset-based
-const page = await db.table.posts
-  .select(['id', 'title'])
-  .paginate({ orderBy: ['createdAt', 'DESC'] })
-  .offset({ perPage: 20, page: 2 });
+// LEFT JOIN — joined table may be null
+await db.table.orders.select()
+  .leftJoin('users')
+  .all();
+// Result: { ...order, users: { ... } | null }[]
 
-// page.pagination.totalPages
-// page.pagination.currentPage
-// page.pagination.total
+// With alias
+await db.table.orders.select()
+  .join(['users', 'customer'], (on, customer, orders) =>
+    on.equal(customer.id, orders.userId)
+  )
+  .all();
+// Result: { ...order, customer: { ... } }[]
+
+// RIGHT JOIN
+await db.table.orders.select()
+  .rightJoin('users', (on, orders, users) =>
+    on.equal(orders.userId, users.id)
+  )
+  .all();
+```
+
+### One-to-Many Joins (LATERAL)
+
+```typescript
+// Get top 5 orders per user
+await db.table.users.select()
+  .joinMany('orders', (on, orders, users) =>
+    on.equal(orders.userId, users.id)
+      .orderBy('createdAt', 'DESC')
+      .limit(5)
+  )
+  .all();
+// Result: { ...user, orders: Order[] }[]
+
+// LEFT JOIN — empty array if no matches
+await db.table.users.select()
+  .leftJoinMany('orders', (on, orders, users) =>
+    on.equal(orders.userId, users.id)
+  )
+  .all();
+
+// Many-to-many through junction table
+await db.table.posts.select()
+  .leftJoinMany('labels', { through: 'itemLabels' }, on =>
+    on.select('id', 'name', 'color')
+  )
+  .all();
+
+// Subquery join
+await db.table.users.select()
+  .joinSubquery(
+    'stats',
+    'SELECT user_id, COUNT(*) as order_count FROM orders GROUP BY user_id',
+    '"stats"."user_id" = "users"."id"'
+  )
+  .all();
+```
+
+---
+
+## Relation Loading
+
+Sugar methods for common join patterns. No callback needed — FK is auto-detected from `relations` config.
+
+### `.with()` — Many-to-One / One-to-One
+
+```typescript
+// Load the user for each order
+await db.table.orders.select('id', 'total')
+  .with('users')
+  .all();
+// Result: { id, total, users: { id, name, ... } | null }[]
+
+// Chain multiple relations
+await db.table.orders.select('id')
+  .with('users')
+  .with('products')
+  .all();
+```
+
+### `.withMany()` — One-to-Many
+
+```typescript
+// Load all orders for each user
+await db.table.users.select('id', 'name')
+  .withMany('orders')
+  .all();
+// Result: { id, name, orders: { id, total, ... }[] }[]
+
+// Many-to-many through junction table
+await db.table.users.select('id', 'name')
+  .withMany('tags', { through: 'userTags' })
+  .all();
+// Result: { id, name, tags: { id, label, ... }[] }[]
+```
+
+---
+
+## Computed Columns
+
+Add aggregate functions and expressions to query results with `.include()`.
+
+```typescript
+// Count items per folder
+const folders = await db.table.folders.select('id', 'name')
+  .include((a, t) => ({
+    itemCount: a.count(t.items.id),
+  }))
+  .leftJoin('items')
+  .groupBy('id')
+  .all();
+// Result: { id: string, name: string, itemCount: number }[]
+
+// Multiple aggregates with table references
+const users = await db.table.users.select('id', 'name')
+  .include((a, t) => ({
+    orderCount: a.count(t.orders.id),
+    totalSpent: a.sum(t.orders.amount),
+    lastOrder: a.max(t.orders.createdAt),
+  }))
+  .leftJoin('orders')
+  .groupBy('id')
+  .all();
+
+// Raw SQL expressions
+db.table.users.select('id')
+  .include((a) => ({
+    year: a.raw<number>('EXTRACT(YEAR FROM NOW())'),
+  }))
+  .all();
+```
+
+The callback receives `(a, t)` where `a` provides aggregate functions (`count`, `sum`, `avg`, `min`, `max`, `raw`) and `t` provides type-safe table proxies for referencing columns across joined tables.
+
+---
+
+## Convenience Methods
+
+Quick operations without building full queries.
+
+```typescript
+// Find by primary key (auto-detects PK column from schema)
+const user = await db.table.users.findById('uuid-here');
+
+// Find first matching record
+const user = await db.table.users.findOne({ email: 'test@example.com' });
+
+// Find all matching records
+const admins = await db.table.users.findMany({ role: 'admin' });
+
+// Check existence
+const exists = await db.table.users.exists({ email: 'test@example.com' });
+
+// Upsert — insert or update
+const user = await db.table.users.upsert({
+  where: { email: 'user@example.com' },
+  create: { email: 'user@example.com', name: 'New User' },
+  update: { name: 'Updated Name' },
+});
+
+// Bulk insert with RETURNING *
+const created = await db.table.users.insertMany([
+  { email: 'a@example.com', name: 'A' },
+  { email: 'b@example.com', name: 'B' },
+]);
+
+// INSERT FROM SELECT
+const count = await db.table.archivedUsers.insertFrom(
+  ['name', 'email', 'createdAt'],
+  t => t.users.select('name', 'email', 'createdAt')
+    .where(q => q.equal('status', 'inactive'))
+);
+
+// Nested create — parent + children in one transaction
+const user = await db.table.users.createWith({
+  data: { name: 'John', email: 'john@example.com' },
+  with: {
+    posts: [
+      { title: 'Hello', content: 'World' },
+      { title: 'Second', content: 'Post' },
+    ],
+    profile: { bio: 'Developer' },
+  }
+});
+// Inserts: user -> posts with userId set -> profile with userId set
+
+// Soft delete (sets deleted_at to now)
+await db.table.users.softDelete({ id: userId });
+
+// Restore soft-deleted record (clears deleted_at)
+await db.table.users.restore({ id: userId });
+```
+
+---
+
+## Raw SQL
+
+### Tagged Template Literal
+
+The `sql` tagged template auto-escapes interpolated values to prevent SQL injection.
+
+```typescript
+import { sql } from 'relq';
+
+// Values are auto-escaped
+const query = sql`SELECT * FROM users WHERE id = ${userId}`;
+
+// Multiple parameters
+const query = sql`
+  SELECT * FROM orders
+  WHERE user_id = ${userId}
+  AND status = ${status}
+  AND total > ${minTotal}
+`;
+
+// Identifiers (table/column names)
+const query = sql`SELECT * FROM ${sql.id('users')} WHERE ${sql.id('email')} = ${email}`;
+
+// Raw SQL (no escaping — use only with trusted input)
+const query = sql`SELECT * FROM users ${sql.raw('ORDER BY id DESC')}`;
+
+// Composable fragments
+const condition = sql`status = ${status}`;
+const query = sql`SELECT * FROM users WHERE ${condition}`;
+```
+
+**Type handling:**
+- Strings -> single-quoted and escaped
+- Numbers -> literal
+- Booleans -> `true` / `false`
+- `null` / `undefined` -> `NULL`
+- Dates -> ISO string, single-quoted
+- Arrays -> parenthesized list `(val1, val2)`
+- Objects -> JSON string with `::jsonb` cast
+- `SqlFragment` -> inlined as-is (for composition)
+
+### Raw Query Builder
+
+```typescript
+import { RawQueryBuilder } from 'relq';
+
+const builder = new RawQueryBuilder('SELECT * FROM users WHERE status = %L', 'active');
+const sql = builder.toString();
 ```
 
 ---
@@ -540,7 +857,7 @@ PG.false()        // FALSE
 
 ### Logical Operators
 ```typescript
-// AND (default - conditions chain)
+// AND (default — conditions chain)
 .where(q => q
   .equal('status', 'active')
   .greaterThan('age', 18)
@@ -594,12 +911,97 @@ PG.false()        // FALSE
 
 ---
 
+## Pagination
+
+### Paginate Builder
+
+```typescript
+// Cursor-based (recommended for large datasets)
+const page = await db.table.posts
+  .paginate({ orderBy: ['createdAt', 'DESC'] })
+  .paging({ perPage: 20, cursor: lastCursor });
+
+// page.data            — results
+// page.pagination.next — cursor for next page
+// page.pagination.hasNext
+
+// Offset-based
+const page = await db.table.posts
+  .paginate({ orderBy: ['createdAt', 'DESC'] })
+  .offset({ perPage: 20, page: 2 });
+
+// page.pagination.totalPages
+// page.pagination.currentPage
+// page.pagination.total
+```
+
+### Cursor Iteration
+
+Process large result sets row by row using PostgreSQL cursors. Memory-efficient — rows are fetched in batches.
+
+```typescript
+await db.table.users.select('email')
+  .where(q => q.equal('verified', false))
+  .each(async (row) => {
+    await sendVerificationEmail(row.email);
+  });
+
+// Stop early
+await db.table.logs.select()
+  .each(async (row, index) => {
+    if (index >= 1000) return false;
+    processLog(row);
+  }, { batchSize: 50 });
+```
+
+---
+
+## Transactions
+
+```typescript
+// Basic transaction
+const result = await db.transaction(async (tx) => {
+  const user = await tx.table.users
+    .insert({ email: 'new@example.com', name: 'User' })
+    .returning(['id'])
+    .run();
+
+  await tx.table.posts
+    .insert({ title: 'First Post', authorId: user.id })
+    .run();
+
+  return user;
+});
+
+// With savepoints
+await db.transaction(async (tx) => {
+  await tx.table.users.insert({ ... }).run();
+
+  try {
+    await tx.savepoint('optional', async (sp) => {
+      await sp.table.posts.insert({ ... }).run();
+    });
+  } catch (e) {
+    // Savepoint rolled back, transaction continues
+  }
+
+  await tx.table.logs.insert({ ... }).run();
+});
+
+// With isolation level
+await db.transaction({ isolation: 'SERIALIZABLE' }, async (tx) => {
+  // ...
+});
+```
+
+---
+
 ## Advanced Schema Features
 
 ### Domains with Validation
 
 ```typescript
-import { pgDomain, text, numeric } from 'relq/schema-builder';
+import { pgDomain, text, numeric } from 'relq/pg-builder';
 
 export const emailDomain = pgDomain('email', text(), (value) => [
   value.matches('^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$')
@@ -609,17 +1011,12 @@ export const percentageDomain = pgDomain('percentage',
   numeric().precision(5).scale(2),
   (value) => [value.gte(0), value.lte(100)]
 );
-
-const employees = defineTable('employees', {
-  email: emailDomain().notNull(),
-  bonus: percentageDomain().default(0)
-});
 ```
 
 ### Composite Types
 
 ```typescript
-import { pgComposite, text, varchar, boolean } from 'relq/schema-builder';
+import { pgComposite, text, varchar, boolean } from 'relq/pg-builder';
 
 export const addressType = pgComposite('address_type', {
   line1: text().notNull(),
@@ -629,11 +1026,6 @@ export const addressType = pgComposite('address_type', {
   postalCode: varchar().length(20),
   verified: boolean().default(false)
 });
-
-const customers = defineTable('customers', {
-  billingAddress: addressType(),
-  shippingAddress: addressType()
-});
 ```
 
 ### Generated Columns
@@ -643,15 +1035,11 @@ const orderItems = defineTable('order_items', {
   quantity: integer().notNull(),
   unitPrice: numeric().precision(10).scale(2).notNull(),
   discount: numeric().precision(5).scale(2).default(0),
-
-  // Computed from other columns
   lineTotal: numeric().precision(12).scale(2).generatedAlwaysAs(
     (table, F) => F(table.unitPrice)
       .multiply(table.quantity)
       .multiply(F.subtract(1, F.divide(table.discount, 100)))
   ),
-
-  // Full-text search vector
   searchVector: tsvector().generatedAlwaysAs(
     (table, F) => F.toTsvector('english', table.description)
   )
@@ -664,35 +1052,29 @@ const orderItems = defineTable('order_items', {
 // Range partitioning
 const events = defineTable('events', {
   id: uuid().primaryKey(),
-  eventType: text().notNull(),
   createdAt: timestamp('created_at').notNull()
 }, {
   partitionBy: (table, p) => p.range(table.createdAt),
   partitions: (partition) => [
     partition('events_2024_q1').from('2024-01-01').to('2024-04-01'),
     partition('events_2024_q2').from('2024-04-01').to('2024-07-01'),
-    partition('events_2024_q3').from('2024-07-01').to('2024-10-01'),
-    partition('events_2024_q4').from('2024-10-01').to('2025-01-01'),
   ]
 });
 
 // List partitioning
 const logs = defineTable('logs', {
-  id: uuid().primaryKey(),
   level: text().notNull(),
   message: text()
 }, {
   partitionBy: (table, p) => p.list(table.level),
   partitions: (partition) => [
     partition('logs_error').forValues('error', 'fatal'),
-    partition('logs_warn').forValues('warn'),
     partition('logs_info').forValues('info', 'debug')
   ]
 });
 
 // Hash partitioning
 const sessions = defineTable('sessions', {
-  id: uuid().primaryKey(),
   userId: uuid('user_id').notNull()
 }, {
   partitionBy: (table, p) => p.hash(table.userId),
@@ -708,9 +1090,8 @@ const sessions = defineTable('sessions', {
 ### Triggers and Functions
 
 ```typescript
-import { pgTrigger, pgFunction } from 'relq/schema-builder';
+import { pgTrigger, pgFunction } from 'relq/pg-builder';
 
-// Define a function
 export const updateUpdatedAt = pgFunction('update_updated_at_column', {
   returns: 'trigger',
   language: 'plpgsql',
@@ -723,7 +1104,6 @@ export const updateUpdatedAt = pgFunction('update_updated_at_column', {
   volatility: 'VOLATILE',
 }).$id('func123');
 
-// Define a trigger using the function
 export const usersUpdatedAt = pgTrigger('users_updated_at', {
   on: schema.users,
   before: 'UPDATE',
@@ -736,37 +1116,22 @@ export const usersUpdatedAt = pgTrigger('users_updated_at', {
 
 ```typescript
 const posts = defineTable('posts', {
-  id: uuid().primaryKey(),
   title: text().notNull(),
   authorId: uuid('author_id').notNull(),
   tags: text().array(),
   metadata: jsonb(),
   published: boolean().default(false),
-  createdAt: timestamp('created_at').default('now()')
 }, {
   indexes: (table, index) => [
-    // B-tree (default)
     index('posts_author_idx').on(table.authorId),
-
-    // Composite with ordering
     index('posts_author_created_idx')
       .on(table.authorId, table.createdAt.desc()),
-
-    // Partial index
     index('posts_published_idx')
       .on(table.createdAt)
       .where(table.published.eq(true)),
-
-    // GIN for arrays
     index('posts_tags_idx').on(table.tags).using('gin'),
-
-    // GIN for JSONB
     index('posts_metadata_idx').on(table.metadata).using('gin'),
-
-    // Unique
     index('posts_slug_idx').on(table.slug).unique(),
-
-    // Expression index
     index('posts_title_lower_idx')
       .on(F => F.lower(table.title))
   ]
@@ -775,70 +1140,59 @@ const posts = defineTable('posts', {
 
 ---
 
-## CLI Commands
-
-Relq provides a comprehensive git-like CLI for schema management:
-
-### Initialization & Status
-
-```bash
-relq init                    # Initialize a new Relq project
-relq status                  # Show current schema status and pending changes
-```
-
-### Schema Operations
-
-```bash
-relq pull [--force]          # Pull schema from database
-relq push [--dry-run]        # Push schema changes to database
-relq diff [--sql]            # Show differences between local and remote schema
-relq sync                    # Full bidirectional sync
-relq introspect              # Generate TypeScript schema from existing database
-```
-
-### Change Management
-
-```bash
-relq add [files...]          # Stage schema changes
-relq commit -m "message"     # Commit staged changes
-relq reset [--hard]          # Unstage or reset changes
-```
-
-### Migration Commands
-
-```bash
-relq generate -m "message"   # Generate migration from changes
-relq migrate [--up|--down]   # Run migrations
-relq rollback [n]            # Rollback n migrations
-relq log                     # View migration log
-relq history                 # View full migration history
-```
+## DDL Builders
 
-### Branching & Merging
+Relq includes builders for all PostgreSQL DDL operations:
 
-```bash
-relq branch [name]           # List or create branches
-relq checkout <branch>       # Switch to a branch
-relq merge <branch>          # Merge a branch into current
-relq cherry-pick <commit>    # Apply specific commit
-relq stash [pop|list|drop]   # Stash/unstash changes
+```typescript
+import {
+  // Tables
+  CreateTableBuilder, AlterTableBuilder, TruncateBuilder,
+  // Indexes
+  CreateIndexBuilder, DropIndexBuilder, ReindexBuilder,
+  // Views
+  CreateViewBuilder, DropViewBuilder, RefreshMaterializedViewBuilder,
+  // Functions & Triggers
+  CreateFunctionBuilder, DropFunctionBuilder,
+  CreateTriggerBuilder, DropTriggerBuilder,
+  // Schemas & Roles
+  CreateSchemaBuilder, DropSchemaBuilder,
+  GrantBuilder, RevokeBuilder, DefaultPrivilegesBuilder,
+  CreateRoleBuilder, AlterRoleBuilder, DropRoleBuilder,
+  // Sequences
+  CreateSequenceBuilder, AlterSequenceBuilder, DropSequenceBuilder,
+  // Partitions
+  PartitionBuilder, CreatePartitionBuilder,
+  AttachPartitionBuilder, DetachPartitionBuilder,
+  // CTE, Window, COPY
+  CTEBuilder, WindowBuilder,
+  CopyToBuilder, CopyFromBuilder,
+  // EXPLAIN, Maintenance
+  ExplainBuilder, VacuumBuilder, AnalyzeBuilder,
+  // Pub/Sub
+  ListenBuilder, UnlistenBuilder, NotifyBuilder,
+} from 'relq';
 ```
 
-### Remote Operations
-
-```bash
-relq remote [add|remove]     # Manage remote databases
-relq fetch                   # Fetch remote schema without applying
-relq tag <name>              # Tag current schema version
-```
+---
 
-### Utilities
+## CLI Commands
 
 ```bash
-relq validate                # Validate schema definitions
-relq export [--format=sql]   # Export schema as SQL
-relq import <file>           # Import schema from file
-relq resolve                 # Resolve merge conflicts
+relq init              # Initialize a new Relq project
+relq status            # Show current schema state
+relq diff [--sql]      # Show schema differences
+relq pull [--force]    # Pull schema from database
+relq push [--dry-run]  # Push schema changes to database
+relq generate -m "msg" # Generate migration from changes
+relq migrate           # Apply pending migrations
+relq rollback [n]      # Rollback n migrations
+relq sync              # Pull + Push in one command
+relq import <file>     # Import SQL file to schema
+relq export            # Export schema to SQL file
+relq validate          # Check schema for errors
+relq seed              # Seed database from SQL files
+relq introspect        # Parse SQL DDL to defineTable() code
 ```
 
 ---
@@ -863,7 +1217,7 @@ export default defineConfig({
   migrations: {
     directory: './db/migrations',
     tableName: '_relq_migrations',
-    format: 'timestamp'  // or 'sequential'
+    format: 'timestamp'
   },
   generate: {
     outDir: './db/generated',
@@ -876,71 +1230,15 @@ export default defineConfig({
 });
 ```
 
-### Environment-Specific Configuration
+### AWS DSQL
 
 ```typescript
-export default defineConfig({
-  connection: process.env.NODE_ENV === 'production'
-    ? { url: process.env.DATABASE_URL }
-    : {
-        host: 'localhost',
-        database: 'myapp_dev',
-        user: 'postgres',
-        password: 'dev'
-      }
-});
-```
-
-### AWS DSQL Support
-
-```typescript
-import { Relq } from 'relq';
-
-const db = new Relq(schema, {
-  provider: 'aws-dsql',
-  region: 'us-east-1',
-  hostname: 'your-cluster.dsql.us-east-1.on.aws',
-  // Uses AWS credentials from environment
-});
-```
-
----
-
-## Transactions
-
-```typescript
-// Basic transaction
-const result = await db.transaction(async (tx) => {
-  const user = await tx.table.users
-    .insert({ email: 'new@example.com', name: 'User' })
-    .returning(['id'])
-    .run();
-
-  await tx.table.posts
-    .insert({ title: 'First Post', authorId: user.id })
-    .run();
-
-  return user;
-});
-
-// With savepoints
-await db.transaction(async (tx) => {
-  await tx.table.users.insert({ ... }).run();
-
-  try {
-    await tx.savepoint('optional', async (sp) => {
-      await sp.table.posts.insert({ ... }).run();
-    });
-  } catch (e) {
-    // Savepoint rolled back, transaction continues
+const db = new Relq(schema, 'awsdsql', {
+  database: 'postgres',
+  aws: {
+    region: 'us-east-1',
+    hostname: 'your-cluster.dsql.us-east-1.on.aws',
   }
-
-  await tx.table.logs.insert({ ... }).run();
-});
-
-// With isolation level
-await db.transaction({ isolation: 'SERIALIZABLE' }, async (tx) => {
-  // ...
 });
 ```
 
@@ -953,6 +1251,11 @@ import {
   RelqError,
   RelqConnectionError,
   RelqQueryError,
+  RelqTransactionError,
+  RelqConfigError,
+  RelqTimeoutError,
+  RelqPoolError,
+  RelqBuilderError,
   isRelqError
 } from 'relq';
 
@@ -965,7 +1268,6 @@ try {
     } else if (error instanceof RelqQueryError) {
       console.error('Query failed:', error.message);
       console.error('SQL:', error.sql);
-      console.error('Parameters:', error.parameters);
     }
   }
 }