relq 1.0.49 → 1.0.51

package/README.md

@@ -2,41 +2,72 @@
 
 **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, and a git-like CLI - 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 git-like CLI for schema management—all with zero runtime dependencies.
 
-## Why Relq?
+[![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)
+[![Node.js](https://img.shields.io/badge/Node.js-22+-green.svg)](https://nodejs.org/)
+[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-12+-blue.svg)](https://www.postgresql.org/)
 
-- **Complete Type Safety** - End-to-end TypeScript inference from schema to query results
-- **Zero Runtime Dependencies** - Everything bundled, no external packages at runtime
-- **Full PostgreSQL Support** - Every PostgreSQL feature you need, properly typed
-- **Tree-Shakeable** - Import only what you use
-- **Schema-First** - Define once, get types everywhere
-- **Git-like CLI** - Familiar commands for schema management
+---
 
-## Installation
+## Table of Contents
 
-```bash
-npm install relq
-```
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Entry Points](#entry-points)
+- [Schema Definition](#schema-definition)
+- [Query API](#query-api)
+- [SQL Functions](#sql-functions)
+- [Condition Builders](#condition-builders)
+- [Advanced Schema Features](#advanced-schema-features)
+- [CLI Commands](#cli-commands)
+- [Configuration](#configuration)
+- [Error Handling](#error-handling)
+- [Requirements](#requirements)
 
-## Entry Points
+---
 
-```typescript
-// Runtime - Client, queries, functions
-import { Relq, F, Case, PG } from 'relq';
+## Features
 
-// Configuration
-import { defineConfig, loadConfig } from 'relq/config';
+### Core Capabilities
 
-// Schema Builder - Types, tables, DDL
-import {
-  defineTable,
-  integer, text, uuid, jsonb, timestamp,
-  pgEnum, pgDomain, pgComposite,
-  one, many
-} from 'relq/schema-builder';
+- **Complete Type Safety** — End-to-end TypeScript inference from schema definition to query results
+- **Zero Runtime Dependencies** — Everything bundled, no external packages needed at runtime
+- **Full PostgreSQL Support** — 100+ column types, all properly typed
+- **Tree-Shakeable** — Import only what you use for optimal bundle size
+- **Schema-First Design** — Define once, get types everywhere
+
+### Schema Management
+
+- **Git-like CLI** — Familiar commands (`pull`, `push`, `diff`, `status`, `branch`, `merge`)
+- **Automatic Migrations** — Generate migrations from schema changes
+- **Database Introspection** — Generate TypeScript schema from existing databases
+- **Tracking IDs** — Detect renames and moves, not just additions/deletions
+
+### Advanced Features
+
+- **Table Partitioning** — Range, list, and hash partitioning with typed definitions
+- **Generated Columns** — Computed columns with expression builders
+- **Domains & Composites** — Custom types with validation
+- **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
+
+---
+
+## Installation
+
+```bash
+npm install relq
+# or
+bun add relq
 ```
 
+---
+
 ## Quick Start
 
 ### 1. Define Your Schema
@@ -46,7 +77,7 @@ import {
 import {
   defineTable,
   uuid, text, timestamp, boolean, integer, jsonb,
-  pgEnum
+  pgEnum, pgRelations
 } from 'relq/schema-builder';
 
 // Enums with full type inference
@@ -72,35 +103,36 @@ 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' } }
+});
+
 export const schema = { users, posts };
 ```
 
-### 2. Connect
+### 2. Connect and Query
 
 ```typescript
 import { Relq } from 'relq';
-import { schema } from './schema';
+import { schema, relations } from './db/schema';
 
 const db = new Relq(schema, {
   host: 'localhost',
+  port: 5432,
   database: 'myapp',
   user: 'postgres',
-  password: 'secret'
-});
-
-// Or with connection URL
-const db = new Relq(schema, {
-  url: process.env.DATABASE_URL
+  password: 'secret',
+  relations
 });
-```
 
-### 3. Query with Full Type Safety
-
-```typescript
-// Types flow from schema to results
-const users = await db.table.users
+// Types flow automatically from schema to results
+const activeUsers = await db.table.users
   .select(['id', 'email', 'status'])
   .where(q => q.equal('status', 'active'))
+  .orderBy('createdAt', 'DESC')
+  .limit(10)
   .all();
 // Type: { id: string; email: string; status: 'active' | 'inactive' | 'suspended' }[]
 
@@ -109,11 +141,37 @@ const user = await db.table.users.findById('uuid-here');
 const user = await db.table.users.findOne({ email: 'test@example.com' });
 ```
 
-## Column Types
+---
+
+## Entry Points
+
+Relq provides three entry points for different use cases:
+
+```typescript
+// Runtime - Client, queries, functions
+import { Relq, F, Case, PG } from 'relq';
+
+// 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 Definition
+
+### Column Types
 
 Relq supports 100+ PostgreSQL types with proper TypeScript mapping:
 
-### Numeric Types
+#### Numeric Types
 ```typescript
 integer(), int(), int4()           // number
 smallint(), int2()                 // number
@@ -126,23 +184,23 @@ doublePrecision(), float8()        // number
 money()                            // string
 ```
 
-### String Types
+#### String Types
 ```typescript
 text()                             // string
 varchar(), char()                  // string
-citext()                           // string (case-insensitive, requires extension)
+citext()                           // string (case-insensitive)
 ```
 
-### Date/Time Types
+#### Date/Time Types
 ```typescript
 timestamp()                        // Date
-timestamptz(), timestampWithTimeZone()  // Date
+timestamptz()                      // Date (with timezone)
 date()                             // Date | string
 time(), timetz()                   // string
 interval()                         // string
 ```
 
-### JSON Types
+#### JSON Types
 ```typescript
 json<T>()                          // T (typed JSON)
 jsonb<T>()                         // T (typed JSONB)
@@ -151,13 +209,13 @@ jsonb<T>()                         // T (typed JSONB)
 metadata: jsonb<{ theme: string; settings: Record<string, boolean> }>()
 ```
 
-### Boolean & UUID
+#### Boolean & UUID
 ```typescript
 boolean(), bool()                  // boolean
 uuid()                             // string
 ```
 
-### Array Types
+#### Array Types
 ```typescript
 // Any column type can be an array
 tags: text().array()               // string[]
@@ -165,7 +223,7 @@ matrix: integer().array(2)         // number[][] (2D array)
 scores: numeric().array()          // string[]
 ```
 
-### Geometric Types
+#### Geometric Types
 ```typescript
 point()                            // { x: number; y: number }
 line()                             // { a: number; b: number; c: number }
@@ -176,15 +234,14 @@ polygon()                          // Array<{ x: number; y: number }>
 circle()                           // { x: number; y: number; r: number }
 ```
 
-### Network Types
+#### Network Types
 ```typescript
 inet()                             // string (IP address)
 cidr()                             // string (IP network)
-macaddr()                          // string
-macaddr8()                         // string
+macaddr(), macaddr8()              // string
 ```
 
-### Range Types
+#### Range Types
 ```typescript
 int4range(), int8range()           // string
 numrange(), daterange()            // string
@@ -192,13 +249,13 @@ tsrange(), tstzrange()             // string
 // Multi-range variants also available
 ```
 
-### Full-Text Search
+#### Full-Text Search
 ```typescript
 tsvector()                         // string
 tsquery()                          // string
 ```
 
-### PostGIS (requires extension)
+#### PostGIS (requires extension)
 ```typescript
 geometry('location', 4326, 'POINT')     // GeoJSON
 geography('area', 4326, 'POLYGON')      // GeoJSON
@@ -206,7 +263,7 @@ geoPoint('coords')                       // { x, y, srid }
 box2d(), box3d()                        // string
 ```
 
-### Extension Types
+#### Extension Types
 ```typescript
 ltree()                            // string (hierarchical labels)
 hstore()                           // Record<string, string | null>
@@ -214,17 +271,18 @@ cube()                             // number[]
 semver()                           // string
 ```
 
+---
+
 ## Query API
 
-### Select
+### SELECT
+
 ```typescript
 // All columns
 const users = await db.table.users.select().all();
 
 // Specific columns
-const emails = await db.table.users
-  .select(['id', 'email'])
-  .all();
+const emails = await db.table.users.select(['id', 'email']).all();
 
 // With conditions
 const active = await db.table.users
@@ -238,17 +296,14 @@ const active = await db.table.users
 const user = await db.table.users
   .select()
   .where(q => q.equal('id', userId))
-  .one();
+  .get();
 
 // With joins
 const postsWithAuthors = await db.table.posts
-  .select(['posts.id', 'posts.title', 'users.name'])
-  .leftJoin('users', 'users.id = posts.author_id')
+  .select(['id', 'title'])
+  .join('users', (on, posts, users) => on.equal(posts.authorId, users.id))
   .all();
 
-// Distinct
-await db.table.users.select(['status']).distinct().all();
-
 // Distinct on (PostgreSQL-specific)
 await db.table.logs
   .select()
@@ -257,22 +312,23 @@ await db.table.logs
   .orderBy('createdAt', 'DESC')
   .all();
 
-// Locking
+// Row locking
 await db.table.jobs
   .select()
   .where(q => q.equal('status', 'pending'))
   .forUpdateSkipLocked()
   .limit(1)
-  .one();
+  .get();
 ```
 
-### Insert
+### INSERT
+
 ```typescript
 // Single insert with returning
 const user = await db.table.users
   .insert({ email: 'new@example.com', name: 'New User' })
   .returning(['id', 'createdAt'])
-  .one();
+  .run();
 
 // Bulk insert
 await db.table.users
@@ -297,7 +353,8 @@ await db.table.users
   .run();
 ```
 
-### Update
+### UPDATE
+
 ```typescript
 // Basic update
 await db.table.users
@@ -310,7 +367,7 @@ const updated = await db.table.posts
   .update({ viewCount: F.increment('viewCount', 1) })
   .where(q => q.equal('id', postId))
   .returning(['id', 'viewCount'])
-  .one();
+  .run();
 
 // Bulk update
 await db.table.posts
@@ -319,7 +376,8 @@ await db.table.posts
   .run();
 ```
 
-### Delete
+### DELETE
+
 ```typescript
 // Delete with condition
 await db.table.users
@@ -332,22 +390,26 @@ const deleted = await db.table.posts
   .delete()
   .where(q => q.equal('authorId', userId))
   .returning(['id', 'title'])
-  .all();
+  .run();
 ```
 
 ### Aggregations
+
 ```typescript
 // Count
 const count = await db.table.users
   .count()
   .where(q => q.equal('status', 'active'))
-  .run();
+  .get();
 
-// Count with group by
-const byStatus = await db.table.users
-  .count()
-  .groupBy('status')
-  .run();
+// Count with 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))
+  .group('favorites', q => q.equal('favorite', true).equal('isDeleted', false))
+  .where(q => q.equal('userId', userId))
+  .get();
+// Returns: { all: number, new: number, favorites: number }
 
 // Multiple aggregations
 const stats = await db.table.orders
@@ -357,12 +419,13 @@ const stats = await db.table.orders
   .avg('amount', 'avgOrderValue')
   .min('amount', 'minOrder')
   .max('amount', 'maxOrder')
-  .one();
+  .get();
 ```
 
 ### Pagination
+
 ```typescript
-// Cursor-based (recommended)
+// Cursor-based (recommended for large datasets)
 const page = await db.table.posts
   .select(['id', 'title', 'createdAt'])
   .paginate({ orderBy: ['createdAt', 'DESC'] })
@@ -383,6 +446,66 @@ const page = await db.table.posts
 // page.pagination.total
 ```
 
+---
+
+## SQL Functions
+
+```typescript
+import { F, Case, PG } from 'relq';
+
+// String Functions
+F.lower('email'), F.upper('name')
+F.concat('first', ' ', 'last')
+F.substring('text', 1, 10)
+F.trim('value'), F.ltrim('value'), F.rtrim('value')
+F.length('text'), F.replace('text', 'old', 'new')
+
+// Date/Time Functions
+F.now(), F.currentDate(), F.currentTimestamp()
+F.extract('year', 'created_at')
+F.dateTrunc('month', 'created_at')
+F.age('birth_date')
+
+// Math Functions
+F.abs('value'), F.ceil('value'), F.floor('value')
+F.round('price', 2), F.trunc('value', 2)
+F.power('base', 2), F.sqrt('value')
+F.greatest('a', 'b', 'c'), F.least('a', 'b', 'c')
+
+// Aggregate Functions
+F.count('id'), F.sum('amount'), F.avg('rating')
+F.min('price'), F.max('price')
+F.arrayAgg('tag'), F.stringAgg('name', ', ')
+
+// JSONB Functions
+F.jsonbSet('data', ['key'], 'value')
+F.jsonbExtract('data', 'key')
+F.jsonbArrayLength('items')
+
+// Array Functions
+F.arrayAppend('tags', 'new')
+F.arrayRemove('tags', 'old')
+F.arrayLength('items', 1)
+F.unnest('tags')
+
+// Conditional (CASE)
+Case()
+  .when(F.gt('price', 100), 'expensive')
+  .when(F.gt('price', 50), 'moderate')
+  .else('cheap')
+  .end()
+
+// PostgreSQL Values
+PG.now()          // NOW()
+PG.currentDate()  // CURRENT_DATE
+PG.currentUser()  // CURRENT_USER
+PG.null()         // NULL
+PG.true()         // TRUE
+PG.false()        // FALSE
+```
+
+---
+
 ## Condition Builders
 
 ### Basic Comparisons
@@ -390,9 +513,7 @@ const page = await db.table.posts
 .where(q => q.equal('status', 'active'))
 .where(q => q.notEqual('role', 'guest'))
 .where(q => q.greaterThan('age', 18))
-.where(q => q.greaterThanEqual('score', 100))
 .where(q => q.lessThan('price', 50))
-.where(q => q.lessThanEqual('quantity', 10))
 .where(q => q.between('createdAt', startDate, endDate))
 ```
 
@@ -455,7 +576,6 @@ const page = await db.table.posts
 // Typed array conditions
 .where(q => q.array.string.startsWith('emails', 'admin@'))
 .where(q => q.array.numeric.greaterThan('scores', 90))
-.where(q => q.array.date.after('dates', '2024-01-01'))
 ```
 
 ### Full-Text Search
@@ -465,45 +585,31 @@ const page = await db.table.posts
 .where(q => q.fulltext.rank('body', 'search terms', 0.1))
 ```
 
-### Range Conditions
+### Range & Geometric Conditions
 ```typescript
 .where(q => q.range.contains('dateRange', '2024-06-15'))
-.where(q => q.range.containedBy('priceRange', '[0, 1000]'))
 .where(q => q.range.overlaps('availability', '[2024-01-01, 2024-12-31]'))
-```
-
-### Geometric Conditions
-```typescript
-.where(q => q.geometric.contains('area', '(0,0),(10,10)'))
-.where(q => q.geometric.overlaps('region', box))
 .where(q => q.geometric.distanceLessThan('location', '(5,5)', 10))
 ```
 
-### Network Conditions
-```typescript
-.where(q => q.network.containsOrEqual('subnet', '192.168.1.0/24'))
-.where(q => q.network.isIPv4('address'))
-.where(q => q.network.isIPv6('address'))
-```
+---
 
 ## Advanced Schema Features
 
 ### Domains with Validation
+
 ```typescript
 import { pgDomain, text, numeric } from 'relq/schema-builder';
 
-// Email domain with pattern validation
 export const emailDomain = pgDomain('email', text(), (value) => [
   value.matches('^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$')
 ]);
 
-// Percentage domain with range validation
 export const percentageDomain = pgDomain('percentage',
   numeric().precision(5).scale(2),
   (value) => [value.gte(0), value.lte(100)]
 );
 
-// Use in tables
 const employees = defineTable('employees', {
   email: emailDomain().notNull(),
   bonus: percentageDomain().default(0)
@@ -511,6 +617,7 @@ const employees = defineTable('employees', {
 ```
 
 ### Composite Types
+
 ```typescript
 import { pgComposite, text, varchar, boolean } from 'relq/schema-builder';
 
@@ -530,6 +637,7 @@ const customers = defineTable('customers', {
 ```
 
 ### Generated Columns
+
 ```typescript
 const orderItems = defineTable('order_items', {
   quantity: integer().notNull(),
@@ -543,19 +651,15 @@ const orderItems = defineTable('order_items', {
       .multiply(F.subtract(1, F.divide(table.discount, 100)))
   ),
 
-  // Using SQL functions
+  // Full-text search vector
   searchVector: tsvector().generatedAlwaysAs(
     (table, F) => F.toTsvector('english', table.description)
-  ),
-
-  // String concatenation
-  fullName: text().generatedAlwaysAs(
-    (table, F) => F.concat(table.firstName, ' ', table.lastName)
   )
 });
 ```
 
 ### Table Partitioning
+
 ```typescript
 // Range partitioning
 const events = defineTable('events', {
@@ -601,24 +705,35 @@ const sessions = defineTable('sessions', {
 });
 ```
 
-### Check Constraints
+### Triggers and Functions
+
 ```typescript
-const products = defineTable('products', {
-  price: numeric().precision(10).scale(2).notNull(),
-  salePrice: numeric().precision(10).scale(2),
-  stockQuantity: integer().default(0)
-}, {
-  checkConstraints: (table, check) => [
-    check.constraint('price_positive', table.price.gt(0)),
-    check.constraint('sale_price_valid',
-      table.salePrice.isNull().or(table.salePrice.lte(table.price))
-    ),
-    check.constraint('stock_non_negative', table.stockQuantity.gte(0))
-  ]
-});
+import { pgTrigger, pgFunction } from 'relq/schema-builder';
+
+// Define a function
+export const updateUpdatedAt = pgFunction('update_updated_at_column', {
+  returns: 'trigger',
+  language: 'plpgsql',
+  body: `
+    BEGIN
+      NEW.updated_at = NOW();
+      RETURN NEW;
+    END;
+  `,
+  volatility: 'VOLATILE',
+}).$id('func123');
+
+// Define a trigger using the function
+export const usersUpdatedAt = pgTrigger('users_updated_at', {
+  on: schema.users,
+  before: 'UPDATE',
+  forEach: 'ROW',
+  execute: updateUpdatedAt,
+}).$id('trig456');
 ```
 
 ### Indexes
+
 ```typescript
 const posts = defineTable('posts', {
   id: uuid().primaryKey(),
@@ -653,150 +768,81 @@ const posts = defineTable('posts', {
 
     // Expression index
     index('posts_title_lower_idx')
-      .on(F => F.lower(table.title)),
-
-    // With storage options
-    index('posts_search_idx')
-      .on(table.searchVector)
-      .using('gin')
-      .with({ fastupdate: false })
+      .on(F => F.lower(table.title))
   ]
 });
 ```
 
-### Relations
-```typescript
-import { one, many, manyToMany } from 'relq/schema-builder';
+---
 
-export const users = defineTable('users', {
-  id: uuid().primaryKey(),
-  email: text().notNull().unique()
-}, {
-  relations: {
-    posts: many('posts', { foreignKey: 'authorId' }),
-    profile: one('profiles', { foreignKey: 'userId' })
-  }
-});
-
-export const posts = defineTable('posts', {
-  id: uuid().primaryKey(),
-  authorId: uuid('author_id').references('users', 'id')
-}, {
-  relations: {
-    author: one('users', { foreignKey: 'authorId' }),
-    tags: manyToMany('tags', {
-      through: 'post_tags',
-      foreignKey: 'postId',
-      otherKey: 'tagId'
-    })
-  }
-});
-```
-
-## SQL Functions
-
-```typescript
-import { F, Case, PG } from 'relq';
-
-// String
-F.lower('email'), F.upper('name')
-F.concat('first', ' ', 'last')
-F.substring('text', 1, 10)
-F.trim('value'), F.ltrim('value'), F.rtrim('value')
-F.length('text'), F.replace('text', 'old', 'new')
+## CLI Commands
 
-// Date/Time
-F.now(), F.currentDate(), F.currentTimestamp()
-F.extract('year', 'created_at')
-F.dateTrunc('month', 'created_at')
-F.age('birth_date')
+Relq provides a comprehensive git-like CLI for schema management:
 
-// Math
-F.abs('value'), F.ceil('value'), F.floor('value')
-F.round('price', 2), F.trunc('value', 2)
-F.power('base', 2), F.sqrt('value')
-F.greatest('a', 'b', 'c'), F.least('a', 'b', 'c')
+### Initialization & Status
 
-// Aggregates
-F.count('id'), F.sum('amount'), F.avg('rating')
-F.min('price'), F.max('price')
-F.arrayAgg('tag'), F.stringAgg('name', ', ')
+```bash
+relq init                    # Initialize a new Relq project
+relq status                  # Show current schema status and pending changes
+```
 
-// JSONB
-F.jsonbSet('data', ['key'], 'value')
-F.jsonbExtract('data', 'key')
-F.jsonbArrayLength('items')
+### Schema Operations
 
-// Arrays
-F.arrayAppend('tags', 'new')
-F.arrayRemove('tags', 'old')
-F.arrayLength('items', 1)
-F.unnest('tags')
+```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
+```
 
-// Conditional
-Case()
-  .when(F.gt('price', 100), 'expensive')
-  .when(F.gt('price', 50), 'moderate')
-  .else('cheap')
-  .end()
+### Change Management
 
-// PostgreSQL values
-PG.now()          // NOW()
-PG.currentDate()  // CURRENT_DATE
-PG.currentUser()  // CURRENT_USER
-PG.null()         // NULL
-PG.true()         // TRUE
-PG.false()        // FALSE
+```bash
+relq add [files...]          # Stage schema changes
+relq commit -m "message"     # Commit staged changes
+relq reset [--hard]          # Unstage or reset changes
 ```
 
-## Transactions
+### Migration Commands
 
-```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'])
-    .one();
-
-  await tx.table.posts
-    .insert({ title: 'First Post', authorId: user.id })
-    .run();
+```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
+```
 
-  return user;
-});
+### Branching & Merging
 
-// With savepoints
-await db.transaction(async (tx) => {
-  await tx.table.users.insert({ ... }).run();
+```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
+```
 
-  try {
-    await tx.savepoint('optional', async (sp) => {
-      await sp.table.posts.insert({ ... }).run();
-    });
-  } catch (e) {
-    // Savepoint rolled back, transaction continues
-  }
+### Remote Operations
 
-  await tx.table.logs.insert({ ... }).run();
-});
+```bash
+relq remote [add|remove]     # Manage remote databases
+relq fetch                   # Fetch remote schema without applying
+relq tag <name>              # Tag current schema version
 ```
 
-## CLI Commands
+### Utilities
 
 ```bash
-relq init                    # Initialize project
-relq status                  # Show pending changes
-relq diff [--sql]            # Show differences
-relq pull [--force]          # Pull from database
-relq generate -m "message"   # Create migration
-relq push [--dry-run]        # Apply migrations
-relq log / relq history     # View history
-relq rollback [n]            # Rollback migrations
-relq sync                    # Full sync
-relq introspect              # Generate schema from DB
+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
 ```
 
+---
+
 ## Configuration
 
 ```typescript
@@ -809,13 +855,15 @@ export default defineConfig({
     port: 5432,
     database: 'myapp',
     user: 'postgres',
-    password: process.env.DB_PASSWORD
+    password: process.env.DB_PASSWORD,
+    // Or use connection string
+    // url: process.env.DATABASE_URL
   },
   schema: './db/schema.ts',
   migrations: {
     directory: './db/migrations',
     tableName: '_relq_migrations',
-    format: 'timestamp'
+    format: 'timestamp'  // or 'sequential'
   },
   generate: {
     outDir: './db/generated',
@@ -828,35 +876,124 @@ export default defineConfig({
 });
 ```
 
+### Environment-Specific Configuration
+
+```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
+  }
+
+  await tx.table.logs.insert({ ... }).run();
+});
+
+// With isolation level
+await db.transaction({ isolation: 'SERIALIZABLE' }, async (tx) => {
+  // ...
+});
+```
+
+---
+
 ## Error Handling
 
 ```typescript
-import { RelqError, RelqConnectionError, RelqQueryError, isRelqError } from 'relq';
+import {
+  RelqError,
+  RelqConnectionError,
+  RelqQueryError,
+  isRelqError
+} from 'relq';
 
 try {
   await db.table.users.insert({ ... }).run();
 } catch (error) {
   if (isRelqError(error)) {
     if (error instanceof RelqConnectionError) {
-      // Connection issues
+      console.error('Connection failed:', error.message);
     } else if (error instanceof RelqQueryError) {
+      console.error('Query failed:', error.message);
       console.error('SQL:', error.sql);
+      console.error('Parameters:', error.parameters);
     }
   }
 }
 ```
 
+---
+
 ## Requirements
 
-- Node.js 18+ or Bun 1.0+
-- PostgreSQL 12+
-- TypeScript 5.0+
+- **Node.js** 22+ or **Bun** 1.0+
+- **PostgreSQL** 12+
+- **TypeScript** 5.0+
+
+---
 
 ## License
 
 MIT
 
+---
+
 ## Links
 
 - [GitHub](https://github.com/yuniqsolutions/relq)
 - [npm](https://www.npmjs.com/package/relq)
+
+---
+
+<p align="center">
+  <strong>Built with TypeScript for TypeScript developers</strong>
+</p>