driftsql 1.0.31 → 2.0.0-beta.1

package/README.md

@@ -1,148 +1,328 @@
 # DriftSQL
 
-[![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

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/cli/index.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import"../postgres-9C7eE0wB.js";import{a as e,o as t,r as n,s as r}from"../src-B1L6LdRV.js";import"../type-generator-CpqI7vBb.js";import i from"consola";import a from"node:fs/promises";import o from"node:path";import{Command as s}from"commander";const c=new s;c.name(`driftsql`).description(`DriftSQL CLI - Database migrations and schema management`).version(`0.0.1`),c.command(`migrate:up`).description(`Run all pending migrations`).option(`-d, --dir <directory>`,`Migrations directory`,`./migrations`).option(`-c, --config <path>`,`Config file path`,`./driftsql.config.ts`).action(async e=>{try{let{client:t,migrations:n}=await u(e.dir,e.config);await new r(t).upAll(n),await t.close(),i.success(`All migrations applied successfully`)}catch(e){i.error(`Migration failed:`,e),process.exit(1)}}),c.command(`migrate:down`).description(`Rollback the last migration`).option(`-d, --dir <directory>`,`Migrations directory`,`./migrations`).option(`-c, --config <path>`,`Config file path`,`./driftsql.config.ts`).action(async e=>{try{let{client:t,migrations:n}=await u(e.dir,e.config),a=new r(t),o=await a.getAppliedMigrations(),s=n.find(e=>e.version===o[o.length-1]);s?await a.down(s):i.info(`No migrations to rollback`),await t.close()}catch(e){i.error(`Rollback failed:`,e),process.exit(1)}}),c.command(`migrate:reset`).description(`Reset all migrations (down then up)`).option(`-d, --dir <directory>`,`Migrations directory`,`./migrations`).option(`-c, --config <path>`,`Config file path`,`./driftsql.config.ts`).action(async e=>{try{let{client:t,migrations:n}=await u(e.dir,e.config);await new r(t).reset(n),await t.close(),i.success(`All migrations reset successfully`)}catch(e){i.error(`Reset failed:`,e),process.exit(1)}}),c.command(`migrate:status`).description(`Show migration status`).option(`-d, --dir <directory>`,`Migrations directory`,`./migrations`).option(`-c, --config <path>`,`Config file path`,`./driftsql.config.ts`).action(async e=>{try{let{client:t,migrations:n}=await u(e.dir,e.config),a=await new r(t).getAppliedMigrations();i.info(`Migration Status:
+`);for(let e of n){let t=a.includes(e.version)?`✓ Applied`:`✗ Pending`;i.log(`${t} - ${e.version} (${e.name})`)}await t.close()}catch(e){i.error(`Failed to get status:`,e),process.exit(1)}}),c.command(`migrate:create <name>`).description(`Create a new migration file`).option(`-d, --dir <directory>`,`Migrations directory`,`./migrations`).action(async(e,t)=>{try{let n=new Date().toISOString().replace(/[-:T.]/g,``).slice(0,14),r=`${n}_${e}.ts`,s=o.join(t.dir,r);await a.mkdir(t.dir,{recursive:!0});let c=`import { createMigration } from 'driftsql'
+
+export const migration = createMigration('postgres')
+  .raw('-- Add your migration SQL here')
+  .build('${n}', '${e}')
+`;await a.writeFile(s,c,`utf8`),i.success(`Created migration: ${r}`)}catch(e){i.error(`Failed to create migration:`,e),process.exit(1)}}),c.command(`migrate:generate [name]`).description(`Automatically generate migration from schema changes`).option(`-s, --schema <path>`,`Schema file path`,`./schema.ts`).option(`-d, --dir <directory>`,`Migrations directory`,`./migrations`).action(async(r,s)=>{try{let c=new n,l=o.resolve(process.cwd(),s.schema);i.start(`Loading schema...`);let u=await import(l),d=u.default||u.schema;(!d||!Array.isArray(d))&&(i.error(`Schema file must export default or named "schema" as an array of table definitions`),i.info(`Example: export default [usersTable.getDefinition(), postsTable.getDefinition()]`),process.exit(1));let f=d,p=await c.load();if(!p){i.info(`No previous schema snapshot found, creating initial migration...`);let e=new Date().toISOString().replace(/[-:T.]/g,``).slice(0,14),t=r||`initial`,n=`${e}_${t}.ts`,l=o.join(s.dir,n);await a.mkdir(s.dir,{recursive:!0});let{PostgresGenerator:u}=await import(`../postgres-DfhzvfQU.js`),d=new u,p=f.map(e=>d.generateCreateTable(e)).map(e=>`  .raw(\`${e.replace(/`/g,"\\`")}\`)`).join(`
+`),m=`import { createMigration } from 'driftsql'
+
+// Initial migration - automatically generated
+// Generated at: ${new Date().toISOString()}
+
+export const migration = createMigration('postgres')
+${p}
+  .build('${e}', '${t}')
+`;await a.writeFile(l,m,`utf8`),await c.save(f);let{generateTypesFromSchema:h}=await import(`../type-generator-DdCKALf8.js`);await h(f,o.join(process.cwd(),`db-types.ts`)),i.success(`\nCreated initial migration: ${n}`),i.success(`Generated TypeScript types: db-types.ts`),i.info(`Snapshot saved. Run "driftsql migrate:up" to apply changes.`);return}i.info(`Detecting changes...`);let m=e(p.tables,f,`postgres`);if(m.length===0){i.success(`No schema changes detected!`);return}i.info(`Found ${m.length} change(s):`),m.forEach((e,t)=>{i.log(`  ${t+1}. ${e.type} - ${e.table}`)});let h=new Date().toISOString().replace(/[-:T.]/g,``).slice(0,14),g=r||`auto_migration`,_=`${h}_${g}.ts`,v=o.join(s.dir,_);await a.mkdir(s.dir,{recursive:!0});let y=t(m,h,g).build(h,g).up.map(e=>`  .raw(\`${e.replace(/`/g,"\\`")}\``).join(`
+`),b=`import { createMigration } from 'driftsql'
+
+// This migration was automatically generated
+// Generated at: ${new Date().toISOString()}
+// Changes: ${m.length}
+
+export const migration = createMigration('postgres')
+${y}
+  .build('${h}', '${g}')
+`;await a.writeFile(v,b,`utf8`),await c.save(f);let{generateTypesFromSchema:x}=await import(`../type-generator-DdCKALf8.js`);await x(f,o.join(process.cwd(),`db-types.ts`)),i.success(`\nGenerated migration: ${_}`),i.success(`Updated TypeScript types: db-types.ts`),i.info(`Snapshot updated. Run "driftsql migrate:up" to apply changes.`)}catch(e){i.error(`Failed to generate migration:`,e),process.exit(1)}}),c.command(`db:inspect`).description(`Inspect database and generate TypeScript types`).option(`-c, --config <path>`,`Config file path`,`./driftsql.config.ts`).option(`-o, --output <path>`,`Output file path`,`./db-types.ts`).action(async e=>{try{let t=await l(e.config);await t.inspectDB({driver:t.getDriver(),outputFile:e.output}),await t.close()}catch(e){i.error(`Inspection failed:`,e),process.exit(1)}}),c.command(`generate:types`).description(`Generate TypeScript types from schema file`).option(`-s, --schema <path>`,`Schema file path`,`./schema.ts`).option(`-o, --output <path>`,`Output file path`,`./db-types.ts`).action(async e=>{try{let t=o.resolve(process.cwd(),e.schema),n=o.resolve(process.cwd(),e.output);i.start(`Loading schema...`);let r=await import(t),a=r.default||r.schema;(!a||!Array.isArray(a))&&(i.error(`Schema file must export default or named "schema" as an array of table definitions`),process.exit(1));let{generateTypesFromSchema:s}=await import(`../type-generator-DdCKALf8.js`);await s(a,n),i.success(`TypeScript types generated: ${e.output}`)}catch(e){i.error(`Type generation failed:`,e),process.exit(1)}}),c.command(`init`).description(`Initialize DriftSQL with a basic notes schema`).option(`-d, --dir <directory>`,`Migrations directory`,`./migrations`).action(async e=>{try{await a.mkdir(e.dir,{recursive:!0});let t=`.driftsql/
+.env
+`,n=o.join(process.cwd(),`driftsql.config.ts`),r=o.join(process.cwd(),`schema.ts`),s=o.join(process.cwd(),`.env.example`),c=o.join(process.cwd(),`.gitignore`),l=[{path:n,content:`import { SQLClient, PostgresDriver } from 'driftsql'
+
+export default new SQLClient({
+  driver: new PostgresDriver({
+    connectionString: process.env.DATABASE_URL!,
+  }),
+})
+`,name:`driftsql.config.ts`},{path:r,content:`import { createTable, serial, varchar, text, timestamp, boolean } from 'driftsql'
+
+const notesTable = createTable('notes', (table) => {
+  table
+    .column(serial('id').primaryKey())
+    .column(varchar('title', 255).notNull())
+    .column(text('content'))
+    .column(boolean('is_archived').default(false).notNull())
+    .column(timestamp('created_at').default('CURRENT_TIMESTAMP').notNull())
+    .column(timestamp('updated_at').default('CURRENT_TIMESTAMP').notNull())
+    .index('idx_notes_archived', ['is_archived'])
+    .index('idx_notes_created_at', ['created_at'])
+})
+
+// Export array of table definitions
+export default [notesTable.getDefinition()]
+`,name:`schema.ts`},{path:s,content:`DATABASE_URL=postgresql://user:password@localhost:5432/mydb
+`,name:`.env.example`}];for(let e of l)try{await a.access(e.path),i.warn(`${e.name} already exists, skipping...`)}catch{await a.writeFile(e.path,e.content,`utf8`),i.success(`Created ${e.name}`)}try{(await a.readFile(c,`utf8`)).includes(`.driftsql/`)||(await a.appendFile(c,`
+`+t),i.success(`Updated .gitignore`))}catch{await a.writeFile(c,t,`utf8`),i.success(`Created .gitignore`)}i.success(`
+✨ DriftSQL initialized successfully!
+`),i.info(`Next steps:`),i.info(`1. Copy .env.example to .env and update DATABASE_URL`),i.info(`2. Run: driftsql migrate:generate initial  (generates migration + types)`),i.info(`3. Run: driftsql migrate:up`),i.info(`4. Import Database type from db-types.ts for type safety`),i.info(`5. Edit schema.ts and run migrate:generate to auto-detect changes!
+`)}catch(e){i.error(`Initialization failed:`,e),process.exit(1)}});async function l(e){try{let t=await import(o.resolve(process.cwd(),e));return t.default||t.client}catch(t){throw i.error(`Failed to load config from ${e}`),t}}async function u(e,t){let n=await l(t),r=[];try{let t=o.resolve(process.cwd(),e),i=(await a.readdir(t)).filter(e=>e.endsWith(`.ts`)||e.endsWith(`.js`)).sort();for(let e of i){let n=await import(o.join(t,e)),i=n.migration||n.default;i&&r.push(i)}return{client:n,migrations:r}}catch(t){throw i.error(`Failed to load migrations from ${e}`),t}}c.parse();export{};