nanodb-orm 0.0.3 → 0.0.5

package/README.md

@@ -1,503 +1,676 @@
 # nanodb-orm
 
-A production-ready, generic database package built on top of Drizzle ORM with automatic migrations, schema introspection, atomic transactions, and support for both local SQLite and remote Turso databases.
+A lightweight ORM wrapper for Drizzle ORM with automatic migrations, schema introspection, CLI tools, and support for SQLite/Turso databases.
 
 ## Features
 
-- 🚀 **Auto-Migrations**: Automatically creates and updates database schemas from Drizzle table definitions
-- 🔍 **Schema Introspection**: Comprehensive schema analysis and validation
-- 🌐 **Multi-Database Support**: Works with local SQLite and remote Turso databases
-- ⚡ **Atomic Transactions**: Full transaction support with rollback protection
-- 🛡️ **Type Safe**: Full TypeScript support with proper type inference
-- 🔒 **Security**: SQL injection protection and input validation
-- 🧵 **Thread Safe**: Race condition fixes and concurrent access protection
-- 📦 **NPM Package Ready**: Designed to be used as a standalone npm package
-- ⚙️ **Configurable**: Flexible migration and seeding options
-- 🧪 **Test Ready**: Built-in testing utilities and isolation
-- 🔧 **Production Ready**: Enhanced error handling and reliability features
+- **TypeScript First** — Full type inference from schema to queries
+- **Auto-Migrations** — Automatically creates and updates database schemas from Drizzle tables
+- **Schema Introspection** — Comprehensive schema analysis and validation
+- **Multi-Database** — Works with local SQLite and remote Turso databases
+- **Transactions** — Full transaction support with automatic rollback
+- **CLI Tools** — Built-in commands including Drizzle Studio integration
+- **Plugin System** — Extensible with hooks for audit, validation, transformations
+- **Minimal** — ~1K lines of code, zero bloat
 
 ## Installation
 
 ```bash
 npm install nanodb-orm
+
+# For Drizzle Studio support (optional)
+npm install drizzle-kit --save-dev
 ```
 
-## Quick Start
+## CLI
 
-### 1. Define Your Models with Drizzle
+nanodb-orm includes a CLI for common database operations:
 
-Create your Drizzle table definitions (e.g., `models/users.ts`):
+```bash
+# Launch Drizzle Studio (visual database browser)
+npx nanodb studio
 
-```typescript
-// models/users.ts
-import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+# With custom port
+npx nanodb studio --port 3000
 
-export const usersTable = sqliteTable('users', {
-  id: integer('id').primaryKey({ autoIncrement: true }),
-  name: text('name').notNull(),
-  age: integer('age').notNull(),
-  email: text('email').unique().notNull(),
-});
+# With specific database file
+npx nanodb studio --db ./data/myapp.db
 
-export type InsertUser = typeof usersTable.$inferInsert;
-export type SelectUser = typeof usersTable.$inferSelect;
+# Other commands
+npx nanodb setup      # Initialize schema and seed data
+npx nanodb reset      # Drop all tables and recreate
+npx nanodb status     # Show database health and stats
+npx nanodb validate   # Validate schema against database
+npx nanodb help       # Show all commands
 ```
 
-```typescript
-// models/posts.ts
-import { sql } from 'drizzle-orm';
-import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
-import { usersTable } from './users';
+### Drizzle Studio
 
-export const postsTable = sqliteTable('posts', {
-  id: integer('id').primaryKey({ autoIncrement: true }),
-  title: text('title').notNull(),
-  content: text('content').notNull(),
-  userId: integer('user_id')
-    .notNull()
-    .references(() => usersTable.id, { onDelete: 'cascade' }),
-  createdAt: text('created_at')
-    .default(sql`(datetime('now'))`)
-    .notNull(),
-  updatedAt: text('updated_at').$onUpdate(() => new Date().toISOString()),
-});
+Launch a visual database browser at `https://local.drizzle.studio`:
 
-export type InsertPost = typeof postsTable.$inferInsert;
-export type SelectPost = typeof postsTable.$inferSelect;
+```bash
+npx nanodb studio
 ```
 
-```typescript
-// models/categories.ts
-import { sql } from 'drizzle-orm';
-import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+![Drizzle Studio](https://orm.drizzle.team/images/drizzle-studio.png)
 
-export const categoriesTable = sqliteTable('categories', {
-  id: integer('id').primaryKey({ autoIncrement: true }),
-  name: text('name').notNull(),
-  description: text('description'),
-  color: text('color').notNull().default('#000000'),
-  isActive: integer('is_active').notNull().default(1),
-  createdAt: text('created_at')
-    .default(sql`(datetime('now'))`)
-    .notNull(),
-});
+## Import Styles
+
+```typescript
+// Default import (recommended)
+import nanodb from 'nanodb-orm';
 
-export type InsertCategory = typeof categoriesTable.$inferInsert;
-export type SelectCategory = typeof categoriesTable.$inferSelect;
+const users = nanodb.schema.table('users', { ... });
+const db = await nanodb.createDatabase({ tables: { users } });
+await db.select().from(users).where(nanodb.query.eq(users.id, 1));
 ```
 
 ```typescript
-// models/index.ts
-export * from './users';
-export * from './posts';
-export * from './categories';
-
-// Import tables for aggregation
-import { usersTable } from './users';
-import { postsTable } from './posts';
-import { categoriesTable } from './categories';
+// Named imports
+import { createDatabase, schema, query } from 'nanodb-orm';
+```
 
-// Export aggregated tables for nanodb-orm
-export const tables = {
-  users: usersTable,
-  posts: postsTable,
-  categories: categoriesTable,
-} as const;
+```typescript
+// Individual imports (tree-shakeable)
+import { createDatabase, table, integer, text, eq } from 'nanodb-orm';
 ```
 
-### 2. Initialize and Setup Database
+## Quick Start
+
+### 1. Define Your Schema
 
 ```typescript
-import { initializeDatabase, DatabaseSync } from 'nanodb-orm';
-import { tables } from './models';
+import nanodb from 'nanodb-orm';
 
-// Initialize the database package with your Drizzle tables
-initializeDatabase({
-  tables,
-  seedData: {
-    users: [
-      { name: 'John Doe', age: 30, email: 'john@example.com' },
-      { name: 'Jane Smith', age: 25, email: 'jane@example.com' }
-    ],
-    posts: [
-      { title: 'Welcome Post', content: 'This is my first post!', userId: 1 },
-      { title: 'Getting Started', content: 'Here are some tips...', userId: 2 }
-    ],
-    categories: [
-      { name: 'Technology', description: 'Tech-related posts', color: '#3B82F6' },
-      { name: 'Lifestyle', description: 'Life and personal posts', color: '#10B981' }
-    ]
-  }
+const users = nanodb.schema.table('users', {
+  id: nanodb.schema.integer('id').primaryKey({ autoIncrement: true }),
+  name: nanodb.schema.text('name').notNull(),
+  email: nanodb.schema.text('email').unique().notNull(),
+  age: nanodb.schema.integer('age'),
 });
 
-// Setup database (creates tables, runs migrations, seeds data)
-await DatabaseSync.setup();
+const posts = nanodb.schema.table('posts', {
+  id: nanodb.schema.integer('id').primaryKey({ autoIncrement: true }),
+  title: nanodb.schema.text('title').notNull(),
+  userId: nanodb.schema.integer('userId').notNull(),
+});
 ```
 
-### 3. Working with Drizzle Tables
+### 2. Create Database
 
-nanodb-orm works seamlessly with Drizzle ORM table definitions. Here are the key Drizzle column types and methods:
+```typescript
+const db = await nanodb.createDatabase({
+  tables: { users, posts },
+  seedData: {
+    users: [{ name: 'Alice', email: 'alice@example.com', age: 28 }],
+  },
+});
 
-#### Drizzle Column Types
-- `integer()` - Integer numbers
-- `text()` - Text strings  
-- `real()` - Floating point numbers
-- `blob()` - Binary data
+export { db };
+```
 
-#### Drizzle Column Methods
-- `.primaryKey({ autoIncrement: true })` - Primary key with auto-increment
-- `.notNull()` - NOT NULL constraint
-- `.unique()` - UNIQUE constraint
-- `.default(value)` - Default value
-- `.references(table.column)` - Foreign key reference
+### 3. Query Your Data
 
-#### Example Drizzle Column Definitions
 ```typescript
-// Primary key with auto-increment
-id: integer('id').primaryKey({ autoIncrement: true })
+// SELECT
+const allUsers = await db.select().from(users);
+const adults = await db.select().from(users).where(nanodb.query.gte(users.age, 18));
 
-// Required text field
-name: text('name').notNull()
+// INSERT
+await db.insert(users).values({ name: 'Bob', email: 'bob@example.com' });
 
-// Optional text field with default
-color: text('color').notNull().default('#000000')
+// UPDATE
+await db.update(users).set({ name: 'Robert' }).where(nanodb.query.eq(users.email, 'bob@example.com'));
 
-// Unique email field
-email: text('email').unique().notNull()
+// DELETE
+await db.delete(users).where(nanodb.query.eq(users.email, 'bob@example.com'));
+```
 
-// Boolean field (stored as integer)
-isActive: integer('is_active').notNull().default(1)
+## Type Inference
 
-// Timestamp field with SQL function
-createdAt: text('created_at')
-  .default(sql`(datetime('now'))`)
-  .notNull()
+nanodb-orm provides full type inference from your schema:
 
-// Foreign key reference
-userId: integer('user_id')
-  .notNull()
-  .references(() => usersTable.id, { onDelete: 'cascade' })
-```
+```typescript
+import { 
+  createDatabase, 
+  table, 
+  integer, 
+  text,
+  type SelectModel,
+  type InsertModel,
+} from 'nanodb-orm';
+
+const users = table('users', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  name: text('name').notNull(),
+  email: text('email').notNull(),
+  age: integer('age'),
+});
 
-## API Reference
+// Infer types directly from your table definitions
+type User = SelectModel<typeof users>;
+// { id: number; name: string; email: string; age: number | null }
 
-### `initializeDatabase(schemaData: SchemaData)`
+type NewUser = InsertModel<typeof users>;
+// { id?: number; name: string; email: string; age?: number | null }
 
-Initializes the database package with your schema data.
+// The database is fully typed
+const db = await createDatabase({ tables: { users } });
 
-```typescript
-interface SchemaData {
-  tables: Record<string, any>;           // Your Drizzle table definitions
-  seedData?: Record<string, any[]>;      // Optional seed data
-  migrationConfig?: MigrationConfig;     // Optional migration configuration
-}
+// All operations are type-safe
+const allUsers: User[] = await db.select().from(users);
 
-interface MigrationConfig {
-  preserveData?: boolean;    // Preserve existing data (default: true)
-  autoMigrate?: boolean;     // Enable auto-migrations (default: true)
-  dropTables?: boolean;      // Allow dropping tables (default: false)
-}
+// Seed data is type-checked at compile time
+const db2 = await createDatabase({
+  tables: { users },
+  seedData: {
+    users: [
+      { name: 'Alice', email: 'alice@example.com' }, // ✓ Valid
+      // { name: 123 }, // ✗ TypeScript error!
+    ],
+  },
+});
 ```
 
-### `DatabaseSync`
+### Available Type Utilities
 
-Main database synchronization class.
+| Type | Description |
+|------|-------------|
+| `SelectModel<T>` | Infer the row type (SELECT result) from a table |
+| `InsertModel<T>` | Infer the insert type from a table (optional auto-generated columns) |
+| `SchemaModels<S>` | Extract all row types from a schema object |
+| `SchemaInsertModels<S>` | Extract all insert types from a schema |
+| `NanoDatabase<S>` | The typed database instance |
+| `Schema` | Type for schema objects |
+| `AnyTable` | Type constraint for Drizzle tables |
 
-```typescript
-// Setup database (create tables, migrate, seed)
-await DatabaseSync.setup();
+## API Reference
 
-// Reset database (drop all tables and recreate)
-await DatabaseSync.reset();
+### `createDatabase(config)`
 
-// Check if database is ready
-const isReady = await DatabaseSync.isReady();
-```
+Create and initialize database. Returns `db` with all utilities attached.
 
-### `SchemaIntrospection`
+```typescript
+const db = await createDatabase({
+  tables: { users, posts },
+  seedData: { users: [...] },  // Type-checked against schema
+  migrationConfig: {
+    preserveData: true,   // default: true
+    autoMigrate: true,    // default: true
+    dropTables: false,    // default: false
+  },
+  plugins: [auditPlugin, validationPlugin], // optional
+});
+```
 
-Comprehensive schema analysis utilities.
+### Database Operations (from `db`)
 
 ```typescript
-// Get all table names
-const tableNames = SchemaIntrospection.getAllTableNames();
+// Health & Status
+await db.healthCheck();    // { healthy, tables, totalRecords, ... }
+await db.isReady();        // true/false
+await db.sync();           // Sync with Turso (if remote)
+
+// Reset & Seed
+await db.reset();          // Drop all, recreate, reseed
+await db.seed();           // Re-seed data
+await db.clearData();      // Delete all data (keep tables)
+```
 
-// Get table information
-const tableInfo = SchemaIntrospection.getTableInfo('users');
+### Schema Introspection (from `db.schema`)
 
-// Get schema statistics
-const stats = SchemaIntrospection.getSchemaStats();
+```typescript
+db.schema.tables();              // ['users', 'posts'] - typed as (keyof Schema)[]
+db.schema.getTable('users');     // { columns, primaryKey, indexes }
+db.schema.getColumns('users');   // ['id', 'name', 'email']
+await db.schema.validate();      // { isValid, missingTables, ... }
+db.schema.stats();               // Full schema statistics
+db.schema.relationships();       // Foreign key relationships
+```
 
-// Validate schema
-const validation = await SchemaIntrospection.validateSchema();
+### Migrations (from `db.migrations`)
+
+```typescript
+await db.migrations.run();         // Run pending migrations
+await db.migrations.validate();    // Validate schema vs DB
+await db.migrations.checkTables(); // { users: true, posts: true }
 ```
 
-### `DatabaseMigrations`
+### `transaction(fn)` / `batch(statements)`
 
-Migration management utilities.
+Execute operations atomically. Uses Drizzle's native transaction when available (better for Turso).
 
 ```typescript
-// Initialize schema
-await DatabaseMigrations.initializeSchema();
+import nanodb from 'nanodb-orm';
 
-// Check table existence
-const existence = await DatabaseMigrations.checkTableExistence();
+// Transaction with custom logic
+const result = await nanodb.transaction(async (tx) => {
+  await tx.run(nanodb.query.sql`INSERT INTO users (name) VALUES ('Alice')`);
+  await tx.run(nanodb.query.sql`INSERT INTO posts (title, userId) VALUES ('Hello', 1)`);
+  return { created: true };
+});
+
+if (result.success) {
+  console.log(result.result); // { created: true }
+} else {
+  console.log('Rolled back:', result.error?.message);
+}
 
-// Validate schema
-const validation = await DatabaseMigrations.validateSchema();
+// Batch multiple statements (simpler for bulk operations)
+const batchResult = await nanodb.batch([
+  nanodb.query.sql`INSERT INTO users (name) VALUES ('Bob')`,
+  nanodb.query.sql`INSERT INTO users (name) VALUES ('Carol')`,
+]);
 ```
 
-### `DatabaseSeeds`
+### `parseDbError(error, context)`
 
-Database seeding utilities.
+Parse SQLite errors into user-friendly messages.
 
 ```typescript
-// Seed database
-await DatabaseSeeds.seedDatabase();
+import { parseDbError } from 'nanodb-orm';
 
-// Check if database has data
-const hasData = await DatabaseSeeds.hasData();
-
-// Clear all data
-await DatabaseSeeds.clearAllData();
+try {
+  await db.insert(users).values({ email: 'duplicate@example.com' });
+} catch (error) {
+  const parsed = parseDbError(error, { table: 'users', operation: 'insert' });
+  console.log(parsed.message); // "Duplicate value for unique column 'email'"
+}
 ```
 
-## Configuration
+## Plugins
 
-### Environment Variables
+Extend nanodb-orm with custom hooks that run automatically on database operations.
 
-```bash
-# Turso Database (optional)
-TURSO_CONNECTION_URL=libsql://your-database.turso.io
-TURSO_AUTH_TOKEN=your-auth-token
+### Plugin Interface
 
-# Force local database (for testing)
-FORCE_LOCAL_DB=true
-NODE_ENV=test
+```typescript
+import { NanoPlugin } from 'nanodb-orm';
+
+const myPlugin: NanoPlugin = {
+  name: 'my-plugin',
+  
+  // Lifecycle
+  install: (db) => db,           // Modify db instance
+  onReady: (db) => {},           // Called after createDatabase
+  onError: (err, op, table) => {},  // Called on hook errors
+  
+  // Auto hooks (run automatically)
+  beforeInsert: (table, data) => data,   // Transform data before insert
+  afterInsert: (table, data, result) => {},
+  beforeUpdate: (table, data) => data,   // Transform data before update
+  afterUpdate: (table, data, result) => {},
+  beforeDelete: (table, condition) => condition,
+  afterDelete: (table, condition, result) => {},
+  
+  // Query hooks (also auto-triggered)
+  beforeQuery: (table, fields) => fields,
+  afterQuery: (table, fields, result) => {},
+};
 ```
 
-### Migration Configuration
+### Example Plugins
+
+These are **example plugins you can create** - nanodb-orm provides the plugin system, you build the plugins:
 
 ```typescript
-const migrationConfig = {
-  preserveData: true,    // Always try to preserve existing data
-  autoMigrate: true,     // Automatically handle schema changes
-  dropTables: false      // Don't drop tables by default
+// Example: Audit logging with timing
+const timers = new Map<string, number>();
+const auditPlugin: NanoPlugin = {
+  name: 'audit',
+  beforeInsert: (table) => { timers.set('op', performance.now()); console.log(`INSERT ${table}`); },
+  afterInsert: () => { console.log(`  ↳ ${(performance.now() - timers.get('op')!).toFixed(1)}ms`); },
+  beforeQuery: (table) => { timers.set('op', performance.now()); console.log(`SELECT ${table}`); },
+  afterQuery: (t, _, rows) => { console.log(`  ↳ ${rows.length} rows in ${(performance.now() - timers.get('op')!).toFixed(1)}ms`); },
+};
+
+// Auto-generate slugs
+const slugPlugin: NanoPlugin = {
+  name: 'slug',
+  beforeInsert: (table, data) => {
+    if (table === 'posts' && data.title && !data.slug) {
+      return { ...data, slug: data.title.toLowerCase().replace(/\s+/g, '-') };
+    }
+    return data;
+  },
 };
 
-initializeDatabase({
+// Validation
+const validationPlugin: NanoPlugin = {
+  name: 'validation',
+  beforeInsert: (table, data) => {
+    if (table === 'users' && !data.email?.includes('@')) {
+      throw new Error('Invalid email format');
+    }
+    return data;
+  },
+};
+
+// Use plugins
+const db = await createDatabase({
   tables,
-  migrationConfig
+  plugins: [auditPlugin, slugPlugin, validationPlugin],
 });
+
+// Hooks run automatically
+await db.insert(posts).values({ title: 'My Post' }); // slug auto-generated
+await db.insert(users).values({ email: 'invalid' }); // throws error
+
+// Check loaded plugins
+db.plugins.list(); // ['audit', 'slug', 'validation']
 ```
 
-## Usage Examples
+## Best Practices
 
-### Basic Setup
+### Recommended Project Structure
+
+```
+db/
+├── schema.ts      # Table definitions
+├── index.ts       # Database instance export
+├── types.ts       # Type aliases (SelectModel, InsertModel)
+├── plugins.ts     # Custom plugins
+└── seeds.ts       # Seed data
+```
+
+### 1. Schema Order Matters
+
+Define parent tables before children for correct seeding order:
 
 ```typescript
-import { initializeDatabase, DatabaseSync } from 'nanodb-orm';
-import { usersTable, postsTable } from './models';
+// db/schema.ts
+import nanodb from 'nanodb-orm';
+
+// Parent tables first (no foreign keys)
+export const users = nanodb.schema.table('users', {
+  id: nanodb.schema.integer('id').primaryKey({ autoIncrement: true }),
+  name: nanodb.schema.text('name').notNull(),
+  email: nanodb.schema.text('email').notNull().unique(),
+});
 
-const tables = {
-  users: usersTable,
-  posts: postsTable
-};
+export const categories = nanodb.schema.table('categories', {
+  id: nanodb.schema.integer('id').primaryKey({ autoIncrement: true }),
+  name: nanodb.schema.text('name').notNull(),
+});
 
-initializeDatabase({ tables });
-await DatabaseSync.setup();
+// Child tables after (have foreign keys)
+export const posts = nanodb.schema.table('posts', {
+  id: nanodb.schema.integer('id').primaryKey({ autoIncrement: true }),
+  title: nanodb.schema.text('title').notNull(),
+  userId: nanodb.schema.integer('userId').notNull(),      // FK to users
+  categoryId: nanodb.schema.integer('categoryId'),        // FK to categories
+});
+
+// Order: parents → children
+export const schema = { users, categories, posts };
 ```
 
-### With Seed Data
+### 2. Single Database Instance
 
 ```typescript
-const seedData = {
-  users: [
-    { name: 'Alice', age: 25, email: 'alice@example.com' },
-    { name: 'Bob', age: 30, email: 'bob@example.com' }
-  ],
-  posts: [
-    { title: 'Hello World', content: 'My first post', userId: 1 },
-    { title: 'Second Post', content: 'Another post', userId: 2 }
-  ]
-};
+// db/index.ts
+import nanodb from 'nanodb-orm';
+import { schema } from './schema';
+import { seedData } from './seeds';
 
-initializeDatabase({ tables, seedData });
-await DatabaseSync.setup();
+export const db = await nanodb.createDatabase({ tables: schema, seedData });
 ```
 
-### Custom Migration Config
+```typescript
+// anywhere.ts
+import { db } from './db';
+import { users } from './db/schema';
+
+const allUsers = await db.select().from(users);
+```
+
+### 3. Use Type Inference
 
 ```typescript
-const migrationConfig = {
-  preserveData: false,   // Allow data loss for development
-  autoMigrate: true,     // Enable auto-migrations
-  dropTables: true       // Allow dropping tables
-};
+// db/types.ts
+import { type SelectModel, type InsertModel } from 'nanodb-orm';
+import { users, posts } from './schema';
 
-initializeDatabase({ 
-  tables, 
-  migrationConfig 
-});
+export type User = SelectModel<typeof users>;
+export type NewUser = InsertModel<typeof users>;
+export type Post = SelectModel<typeof posts>;
+
+// Usage
+async function createUser(data: NewUser): Promise<void> {
+  await db.insert(users).values(data);  // TypeScript enforces shape
+}
 ```
 
-### Transaction Support (NEW in v0.0.3)
+### 4. Prefer Grouped Imports
 
 ```typescript
-import { TransactionManager } from 'nanodb-orm';
+// ✅ Clean - default import
+import nanodb from 'nanodb-orm';
 
-// Atomic operations
-await TransactionManager.execute(async (db) => {
-  await db.run('INSERT INTO users (name, email) VALUES (?, ?)', ['John', 'john@example.com']);
-  await db.run('INSERT INTO posts (title, content, userId) VALUES (?, ?, ?)', ['Hello', 'World', 1]);
-  // All operations succeed or all fail
-});
+const users = nanodb.schema.table('users', { ... });
+await db.select().from(users).where(nanodb.query.eq(users.id, 1));
 
-// Batch operations
-await TransactionManager.executeBatch([
-  async (db) => await db.run('INSERT INTO users ...'),
-  async (db) => await db.run('INSERT INTO posts ...'),
-  async (db) => await db.run('UPDATE stats ...')
-]);
+// ✅ Also good - grouped imports
+import { schema, query, errors } from 'nanodb-orm';
 
-// Table recreation with transactions
-await TransactionManager.recreateTable('users', async (db) => {
-  await db.run('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)');
-});
+// ❌ Avoid - many individual imports
+import { table, integer, text, eq, gte, and, sql, count, ... } from 'nanodb-orm';
 ```
 
-### Enhanced Error Handling (NEW in v0.0.3)
+### 5. Handle Errors Gracefully
 
 ```typescript
-import { ErrorHandler, DatabaseError } from 'nanodb-orm';
+import { parseDbError, DatabaseError } from 'nanodb-orm';
 
 try {
-  await DatabaseSync.setup();
+  await db.insert(users).values({ email: 'duplicate@test.com' });
 } catch (error) {
   if (error instanceof DatabaseError) {
-    console.log('Operation:', error.operation);
-    console.log('Context:', error.message);
-    console.log('Original Error:', error.originalError);
+    // Already formatted with context
+    console.log(error.message);  // "UNIQUE constraint failed: users.email"
+    console.log(error.table);    // "users"
+  } else {
+    const parsed = parseDbError(error, { table: 'users' });
+    console.log(parsed.format());
   }
 }
-
-// Non-throwing error handling
-const result = ErrorHandler.handleNonThrowingError(
-  someError, 
-  'optional-operation', 
-  'This operation is optional'
-);
 ```
 
-### Thread-Safe Connections (NEW in v0.0.3)
+### 6. Use Transactions for Atomic Operations
 
 ```typescript
-import { DatabaseConnection } from 'nanodb-orm';
+import nanodb from 'nanodb-orm';
 
-// NEW: Async connection (recommended)
-const db = await DatabaseConnection.getInstance();
-
-// OLD: Synchronous connection (deprecated but still works)
-const db = DatabaseConnection.getInstanceSync();
+const result = await nanodb.transaction(async (tx) => {
+  await tx.run(nanodb.query.sql`INSERT INTO users (name) VALUES ('Alice')`);
+  await tx.run(nanodb.query.sql`INSERT INTO posts (title, userId) VALUES ('Hello', 1)`);
+  return { inserted: 2 };
+});
 
-// Check connection status
-if (DatabaseConnection.isConnected()) {
-  console.log('Database is connected');
+if (!result.success) {
+  console.log('Rolled back:', result.error?.message);
 }
 ```
 
-### Schema Introspection
+### 7. Validate on Startup (Production)
 
 ```typescript
-import { SchemaIntrospection } from 'nanodb-orm';
+import nanodb from 'nanodb-orm';
 
-// Get comprehensive schema information
-const schemaInfo = SchemaIntrospection.getSchemaStats();
-console.log('Total tables:', schemaInfo.totalTables);
-console.log('Table details:', schemaInfo.tableDetails);
+const db = await nanodb.createDatabase({ tables: schema });
 
-// Validate schema integrity
-const validation = await SchemaIntrospection.validateSchema();
-if (!validation.isValid) {
-  console.log('Schema issues:', validation.errors);
+if (process.env.NODE_ENV === 'production') {
+  const validation = await db.schema.validate();
+  if (!validation.isValid) {
+    throw new Error(`Schema mismatch: ${validation.missingTables.join(', ')}`);
+  }
+
+  const health = await db.healthCheck();
+  if (!health.healthy) {
+    console.warn('Database issues:', health.errors);
+  }
 }
 ```
 
-## Testing
-
-The package includes built-in testing utilities:
+### 8. Keep Plugins Simple
 
 ```typescript
-import { DatabaseSync } from 'nanodb-orm';
+// Good: focused, single responsibility
+const timestampPlugin: NanoPlugin = {
+  name: 'timestamps',
+  beforeInsert: (_table, data) => ({
+    ...data,
+    createdAt: new Date().toISOString(),
+  }),
+  beforeUpdate: (_table, data) => ({
+    ...data,
+    updatedAt: new Date().toISOString(),
+  }),
+};
 
-describe('My Tests', () => {
-  beforeEach(async () => {
-    // Reset database for each test
-    await DatabaseSync.reset();
-  });
+// Avoid: complex business logic in hooks
+```
 
-  test('should work with clean database', async () => {
-    // Your test code here
-  });
-});
+### 9. Environment Configuration
+
+```bash
+# .env
+TURSO_CONNECTION_URL=libsql://your-db.turso.io
+TURSO_AUTH_TOKEN=your-token
+FORCE_LOCAL_DB=true           # Use local SQLite
+DATABASE_PATH=./data/app.db   # Custom DB path
 ```
 
-## Database Support
+nanodb-orm auto-detects the right database:
+- **Turso**: when `TURSO_*` vars are set
+- **Local**: when `FORCE_LOCAL_DB=true` or no Turso config  
+- **Test**: isolated `test.db` when `NODE_ENV=test`
 
-### Local SQLite
-- Automatically used when Turso credentials are not available
-- Perfect for development and testing
-- File-based storage
+## Configuration
+
+### Environment Variables
+
+```bash
+# Remote Turso database
+TURSO_CONNECTION_URL=libsql://your-db.turso.io
+TURSO_AUTH_TOKEN=your-token
+
+# Force local SQLite
+FORCE_LOCAL_DB=true
+
+# Custom database path (works with FORCE_LOCAL_DB or as fallback)
+DATABASE_PATH=./data/myapp.db
+```
 
-### Remote Turso
-- Cloud-hosted SQLite database
-- Requires `TURSO_CONNECTION_URL` and `TURSO_AUTH_TOKEN`
-- Production-ready with global replication
+### Database Selection
+
+- **Turso** — Used when `TURSO_CONNECTION_URL` and `TURSO_AUTH_TOKEN` are set
+- **Local SQLite** — Used when `FORCE_LOCAL_DB=true` or Turso credentials missing
+- **Custom Path** — Set `DATABASE_PATH=./path/to/db.sqlite` for custom location
+- **Test Mode** — Isolated `test.db` when `NODE_ENV=test`
 
 ## Error Handling
 
-The package provides comprehensive error handling:
+Errors are automatically parsed into user-friendly messages:
 
 ```typescript
-import { DatabaseError } from 'nanodb-orm';
+import { DatabaseError, SchemaError, SeedError, parseDbError } from 'nanodb-orm';
 
 try {
   await DatabaseSync.setup();
 } catch (error) {
   if (error instanceof DatabaseError) {
-    console.log('Database error:', error.message);
-    console.log('Operation:', error.operation);
+    console.log(error.message);    // User-friendly message
+    console.log(error.operation);  // 'seed', 'migration', etc.
+    console.log(error.table);      // Table name if applicable
+    console.log(error.detail);     // Additional context
   }
 }
 ```
 
-## Contributing
+Error output is clean and actionable:
 
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add some amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+```
+┌─ nanodb-orm error ─────────────────────────────
+│ Column "email" does not exist
+│ Table: users
+│ Operation: seed
+│ Detail: Row data: {"name":"Alice","email":"alice@example.com"}
+└────────────────────────────────────────────────
+```
+
+## Exports
+
+```typescript
+// Default export (recommended)
+import nanodb from 'nanodb-orm';
+
+nanodb.createDatabase  // Main entry point
+nanodb.transaction     // Atomic operations
+nanodb.schema          // .table, .integer, .text, .real, .blob
+nanodb.query           // .eq, .gte, .and, .or, .sql, .count, ...
+nanodb.errors          // .DatabaseError, .parse
+nanodb.cli             // .studio, .setup, .reset, .status, .validate
+
+// Types (named imports)
+import { type SelectModel, type InsertModel, type NanoPlugin } from 'nanodb-orm';
+```
+
+## nanodb-orm vs Drizzle + Turso (Direct)
+
+| Feature | nanodb-orm | Drizzle + Turso |
+|---------|------------|-----------------|
+| **Setup** | One-liner: `createDatabase({ tables })` | Manual: create client, drizzle, manage connection |
+| **Migrations** | Automatic on startup | Manual: `drizzle-kit push/migrate` |
+| **Seeding** | Built-in with `seedData` | Write seed scripts |
+| **Type Safety** | ✅ Full (same as Drizzle) | ✅ Full |
+| **Query API** | ✅ Same as Drizzle | ✅ Native Drizzle |
+| **Plugins/Hooks** | ✅ beforeInsert, afterQuery, etc. | ❌ None |
+| **Schema Introspection** | ✅ `db.schema.tables()` | ❌ Manual |
+| **Health Checks** | ✅ `db.healthCheck()` | ❌ Manual |
+| **CLI** | `npx nanodb studio/status/validate` | `npx drizzle-kit studio` only |
+| **Error Parsing** | User-friendly messages | Raw SQLite errors |
+| **Connection** | Auto-detects Turso vs local | Manual configuration |
+
+### When to Use What
+
+| Use Case | Recommendation |
+|----------|----------------|
+| Quick prototyping | **nanodb-orm** |
+| Need plugins/hooks | **nanodb-orm** |
+| Want auto-migrations | **nanodb-orm** |
+| New SQLite/Turso project | **nanodb-orm** |
+| Maximum control | Drizzle directly |
+| Complex migration strategies | Drizzle + drizzle-kit |
+| Existing Drizzle project | Keep Drizzle |
+
+### Comparison
+
+```typescript
+// nanodb-orm: 5 lines
+import nanodb from 'nanodb-orm';
+
+const users = nanodb.schema.table('users', { id: nanodb.schema.integer('id').primaryKey() });
+const db = await nanodb.createDatabase({ tables: { users }, seedData: { users: [{ id: 1 }] } });
+// Ready - tables created, seeded
+```
+
+```typescript
+// Drizzle + Turso: More setup
+import { drizzle } from 'drizzle-orm/libsql';
+import { createClient } from '@libsql/client';
+import { sqliteTable, integer } from 'drizzle-orm/sqlite-core';
+import { migrate } from 'drizzle-orm/libsql/migrator';
+
+const users = sqliteTable('users', { id: integer('id').primaryKey() });
+const client = createClient({ url: process.env.TURSO_CONNECTION_URL!, authToken: process.env.TURSO_AUTH_TOKEN! });
+const db = drizzle(client);
+await migrate(db, { migrationsFolder: './drizzle' });
+await db.insert(users).values([{ id: 1 }]);
+```
+
+**nanodb-orm is a convenience layer** — it uses Drizzle under the hood and passes through all queries unchanged. You get Drizzle's full type safety plus automatic setup, plugins, and utilities.
 
 ## License
 
 MIT © Damilola Alao
-
-## Changelog
-
-### 0.0.2
-- **Enhanced Documentation**: Added comprehensive Drizzle ORM integration examples
-- **Real Model Examples**: Updated documentation with actual Drizzle table definitions
-- **Schema Validation Fix**: Fixed table existence validation logic for proper health checks
-- **LLM Documentation**: Added detailed `llm.txt` file for AI/LLM integration
-- **Column Types Guide**: Added complete Drizzle column types and methods documentation
-- **Foreign Key Support**: Documented foreign key relationships and cascade deletes
-- **Type Safety**: Enhanced TypeScript integration examples with Drizzle's type inference
-
-### 0.0.1
-- Initial release
-- Auto-migration system
-- Schema introspection
-- Multi-database support
-- TypeScript support
-- Testing utilities