driftsql 1.0.32 → 2.0.0-beta.2

package/README.md

@@ -1,148 +1,328 @@
-# DriftSQL
+# DriftSQL (beta)
 
-[![npm version](https://img.shields.io/npm/v/driftsql?color=yellow)](https://npmjs.com/package/driftsql)
-[![npm downloads](https://img.shields.io/npm/dm/driftsql?color=yellow)](https://npm.chart.dev/driftsql)
+A modern, type-safe SQL client with built-in schema builder and migration system for TypeScript.
 
-A lightweight, type-safe SQL client for TypeScript with support for PostgreSQL, MySQL, LibSQL/SQLite, and Neon.
+## Features
+
+- 🚀 **High-Performance SQL Client** with connection pooling and query caching
+- 🎯 **Type-Safe Schema Builder** similar to Drizzle/Prisma
+- 🔄 **Migration System** with automatic change detection
+- 🛠️ **CLI Tools** for database management
+- 📦 **Multiple Databases** - PostgreSQL, MySQL, SQLite support
+- ⚡ **Helper Functions** for common CRUD operations
+- 🔍 **Database Inspection** to generate TypeScript types
+
+## Quick Start
+
+```bash
+# Install
+bun add driftsql
 
-## Installation
+# Initialize with a basic notes schema
+driftsql init
 
-```sh
-npm install driftsql
+# Update .env with your DATABASE_URL
+cp .env.example .env
+
+# Generate migration from schema
+driftsql migrate:generate initial
+
+# Run migrations
+driftsql migrate:up
+
+# Edit schema.ts, then generate new migrations automatically
+driftsql migrate:generate add_posts
 ```
 
-## Features
+## Automatic Workflow
 
-- 🔐 **Type-safe** - Full TypeScript support
-- 🚀 **Modular** - Import only what you need
-- 🛡️ **SQL injection protection** - Parameterized queries
-- 🔄 **Unified API** - Same interface across all drivers
-- ⚡ **Transactions** - When supported by the driver
+DriftSQL automatically detects schema changes and generates migrations for you!
 
-## Quick Start
+1. Define your schema in `schema.ts`:
 
 ```typescript
-import { PostgresDriver, SQLClient } from 'driftsql'
+import { createTable, serial, varchar, text } from 'driftsql'
 
-// Choose your database
-const driver = new PostgresDriver({
-  connectionString: 'postgresql://user:password@localhost:5432/mydb',
+const usersTable = createTable('users', (table) => {
+  table.column(serial('id').primaryKey()).column(varchar('email', 255).unique().notNull()).column(varchar('name', 255).notNull())
 })
-const client = new SQLClient({ driver })
 
-// Raw queries
-const result = await client.query('SELECT * FROM users WHERE id = $1', [1])
+const postsTable = createTable('posts', (table) => {
+  table.column(serial('id').primaryKey()).column(integer('user_id').references('users', 'id')).column(varchar('title', 255).notNull()).column(text('content'))
+})
 
-// Helper methods
-const user = await client.findFirst('users', { email: 'user@example.com' })
-const newUser = await client.insert('users', { name: 'John', email: 'john@example.com' })
+export default [usersTable.getDefinition(), postsTable.getDefinition()]
 ```
 
-## Supported Databases
+2. Generate migration:
 
-```typescript
-import { PostgresDriver, LibSQLDriver, MySQLDriver, NeonDriver, SQLClient } from 'driftsql'
+```bash
+driftsql migrate:generate
+```
 
-// PostgreSQL
-const pg = new PostgresDriver({ connectionString: 'postgresql://...' })
+3. DriftSQL automatically:
 
-// Neon
-const neon = new NeonDriver({ connectionString: 'postgresql://...' })
+   - ✅ Compares with the last snapshot
+   - ✅ Detects all changes
+   - ✅ Generates migration file
+   - ✅ Generates TypeScript types (`db-types.ts`)
 
-// LibSQL/Turso/SQLite
-const libsql = new LibSQLDriver({ url: 'libsql://...', authToken: '...' })
-// or for local SQLite: new LibSQLDriver({ url: 'file:./database.db' })
+4. Apply migrations:
 
-// MySQL
-const mysql = new MySQLDriver({ connectionString: 'mysql://...' })
+```bash
+driftsql migrate:up
+```
+
+5. Use type-safe queries:
 
-// Create client with any driver
-const client = new SQLClient({ driver: pg })
+```typescript
+import { Database } from './db-types'
+const client = new SQLClient<Database>({
+  /* ... */
+})
 ```
 
-## Custom Drivers
+## Usage
 
-You can easily create your own database drivers by implementing the `DatabaseDriver` interface:
+### SQL Client with Type Safety
 
-```typescript
-import type { DatabaseDriver, QueryResult } from 'driftsql'
-
-class MyCustomDriver implements DatabaseDriver {
-  async query<T = any>(sql: string, params?: any[]): Promise<QueryResult<T>> {
-    // Your implementation here
-    return {
-      rows: [], // T[]
-      rowCount: 0,
-      command: 'SELECT',
-    }
-  }
-
-  async close(): Promise<void> {
-    // Cleanup logic
-  }
-}
+TypeScript types are **automatically generated** when you run `migrate:generate`:
 
-// Use your custom driver
-const client = new SQLClient({ driver: new MyCustomDriver() })
+```bash
+driftsql migrate:generate  # Creates migration AND db-types.ts automatically
 ```
 
-## Database Inspection
+Or generate them manually:
+
+```bash
+driftsql generate:types --schema ./schema.ts --output ./db-types.ts
+```
 
-Generate TypeScript interfaces from your database schema:
+Then use them for full type safety:
 
 ```typescript
-import { inspectDB, PostgresDriver } from 'driftsql'
+import { SQLClient, PostgresDriver } from 'driftsql'
+import type { Database } from './db-types'
 
-const driver = new PostgresDriver({
-  connectionString: 'postgresql://user:password@localhost:5432/mydb',
+// Generic parameter makes client type-safe
+const client = new SQLClient<Database>({
+  driver: new PostgresDriver({
+    connectionString: process.env.DATABASE_URL!,
+    max: 10, // Connection pool size
+    idle_timeout: 30, // Seconds
+    connect_timeout: 10, // Seconds
+  }),
+  cacheTTL: 5000, // Cache TTL in ms (default: 5000)
 })
 
-// Generate types for all tables
-await inspectDB({
-  driver,
-  outputFile: 'db-types.ts', // optional, defaults to 'db-types.ts'
+// Raw SQL queries (no type safety, but flexible)
+const result = await client.query('SELECT * FROM users WHERE id = $1', [1])
+
+// ✅ Type-safe helper methods (TypeScript validates everything!)
+const user = await client.findFirst('users', { email: 'test@example.com' })
+//                                    ^^^^^ TypeScript ensures 'users' exists
+//                                           ^^^^^ TypeScript ensures 'email' is a valid column
+
+const activeUsers = await client.findMany('users', {
+  where: { active: true }, // ✅ TypeScript validates field names and types
+  limit: 10,
+  offset: 0,
 })
-```
 
-This will create a file with TypeScript interfaces for each table:
+// ✅ Insert with type checking
+const newUser = await client.insert('users', {
+  email: 'new@example.com', // ✅ Must be a string
+  name: 'New User', // ✅ Must be a string
+  active: true, // ✅ Must be a boolean
+  // invalid: 'field'       // ❌ TypeScript error!
+})
 
-```typescript
-// Generated db-types.ts
-export interface Users {
-  id: number
-  name: string
-  email: string
-  created_at: Date
-  active: boolean | null
-}
+// ✅ Update with type checking
+const updated = await client.update(
+  'users',
+  { name: 'Updated Name' }, // ✅ Only valid columns
+  { id: 1 } // ✅ Only valid columns in where clause
+)
+
+// ✅ Delete with type checking
+const deletedCount = await client.delete('users', { id: 1 })
+
+// Transactions - all operations succeed or all fail
+await client.transaction(async (tx) => {
+  const user = await tx.insert('users', { email: 'user@example.com', name: 'User' })
+  await tx.insert('posts', { user_id: user.id, title: 'First Post' })
+  await tx.query('UPDATE users SET post_count = post_count + 1 WHERE id = $1', [user.id])
+})
+
+// Cache management
+const stats = client.getCacheStats() // { size: 5, ttl: 5000 }
+client.clearCache() // Clear all cached queries
 
-export interface Posts {
-  id: number
-  title: string
-  content: string
-  user_id: number
-  published: boolean
+// Check driver capabilities
+if (client.supportsTransactions()) {
+  await client.transaction(async (tx) => {
+    /* ... */
+  })
 }
 
-export interface Database {
-  users: Users
-  posts: Posts
+if (client.supportsPreparedStatements()) {
+  const stmt = await client.prepare('SELECT * FROM users WHERE id = $1')
+  const result = await stmt.execute([1])
+  await stmt.finalize()
 }
+
+await client.close()
 ```
 
-Then use the generated types with your client:
+### Schema Builder
 
 ```typescript
-import type { Database } from './db-types'
-import { PostgresDriver, SQLClient } from 'driftsql'
+import { createTable, createMigration, serial, varchar, text, timestamp } from 'driftsql'
+
+// Define table
+const usersTable = createTable('users', (table) => {
+  table
+    .column(serial('id').primaryKey())
+    .column(varchar('email', 255).unique().notNull())
+    .column(varchar('name', 255).notNull())
+    .column(text('bio'))
+    .column(timestamp('created_at').default('CURRENT_TIMESTAMP').notNull())
+    .index('idx_users_email', ['email'])
+})
+
+// Create migration
+const migration = createMigration('postgres').createTable(usersTable).build('001', 'create_users_table')
+
+// View generated SQL
+console.log(migration.up) // CREATE TABLE statements
+console.log(migration.down) // DROP TABLE statements
+```
 
-const client = new SQLClient<Database>({ driver })
+### Change Detection
 
-// Now you get full type safety
-const user = await client.findFirst('users', { email: 'test@example.com' }) // Returns Users | null
-const posts = await client.findMany('posts', { where: { published: true } }) // Returns Posts[]
+```typescript
+import { detectChanges, generateMigrationFromChanges } from 'driftsql'
+
+const oldSchema = [
+  /* previous table definitions */
+]
+const newSchema = [
+  /* updated table definitions */
+]
+
+// Detect what changed
+const changes = detectChanges(oldSchema, newSchema, 'postgres')
+
+// Generate migration from changes
+const migration = generateMigrationFromChanges(changes, '002', 'auto_migration')
+```
+
+### CLI Commands
+
+```bash
+# Initialize project
+driftsql init
+
+# Create new migration
+driftsql migrate:create add_users_table
+
+# Run migrations
+driftsql migrate:up
+
+# Check migration status
+driftsql migrate:status
+
+# Rollback last migration
+driftsql migrate:down
+
+# Reset all migrations
+driftsql migrate:reset
+
+# Generate TypeScript types from database
+driftsql db:inspect --output ./src/db-types.ts
+```
+
+## Performance Features
+
+- **Connection Pooling**: Configurable pool size and timeouts
+- **Query Caching**: Built-in LRU cache with TTL (default 5 seconds)
+- **Smart Fallbacks**: Fast-path primary driver with automatic fallback support
+- **Optimized Error Handling**: Reduced overhead in CRUD operations
+
+```typescript
+const client = new SQLClient({
+  driver: new PostgresDriver({
+    connectionString: process.env.DATABASE_URL!,
+    max: 10, // Pool size
+    idle_timeout: 30, // Seconds
+    connect_timeout: 10, // Seconds
+  }),
+  cacheTTL: 5000, // Cache TTL in ms
+})
+
+// Cache management
+client.clearCache()
+const stats = client.getCacheStats()
 ```
 
+## Supported Databases
+
+- ✅ **PostgreSQL** - Full feature support
+- ✅ **MySQL** - Full feature support
+- ✅ **SQLite** - Full feature support
+- 🔄 More coming soon...
+
+## Column Types
+
+**Numeric**: `serial`, `bigserial`, `integer`, `bigint`, `smallint`, `decimal`, `numeric`, `real`, `doublePrecision`
+
+**String**: `text`, `varchar`, `char`
+
+**Date/Time**: `timestamp`, `timestamptz`, `date`, `time`
+
+**Other**: `boolean`, `json`, `jsonb`, `uuid`, `bytea`
+
+## Column Modifiers
+
+```typescript
+column.primaryKey().notNull().unique().default(value).length(255).precision(10, 2).references('users', 'id').onDelete('CASCADE').check('age >= 18')
+```
+
+## Documentation
+
+- [Schema Builder Guide](./SCHEMA.md) - Complete schema builder documentation
+- [CLI Reference](./CLI.md) - All CLI commands and usage
+
+## Examples
+
+Check the `examples/` directory for:
+
+- Basic schema creation
+- Migration generation
+- Change detection
+- Multiple database dialects
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines.
+
 ## License
 
-Published under the [MIT](https://github.com/lassejlv/driftsql/blob/main/LICENSE) license.
+MIT
+
+## Roadmap
+
+- [x] PostgreSQL driver with helpers
+- [x] Query caching
+- [x] Schema builder
+- [x] Migration system
+- [x] Change detection
+- [x] CLI tools
+- [x] MySQL helpers
+- [x] SQLite helpers
+- [ ] MySQL driver implementation
+- [ ] SQLite driver implementation
+- [ ] More database drivers (SQL Server, Oracle, etc.)
+- [ ] Schema diffing from live database
+- [ ] Migration squashing
+- [ ] Seeding system