noormme 1.0.2 → 1.0.3

package/README.md

@@ -32,27 +32,46 @@ We fixed all that nonsense:
 
 ### **Real Benefits (The Stuff That Actually Matters):**
 - 🚀 **Feel like a coding wizard** - AI that understands your project
-- 💰 **Save money** - No expensive database servers to maintain
-- 🔧 **Deploy easily** - One file instead of a server farm
-- ⚡ **Go fast** - Direct file access beats network calls every time
-- 🛡️ **Stay secure** - No network = no network attacks
+- 🗄️ **Multi-database support** - SQLite for simplicity, PostgreSQL for power
+- 💰 **Save money** - SQLite for dev/small apps, PostgreSQL when you need it
+- 🔧 **Deploy easily** - SQLite = one file, PostgreSQL = full production ready
+- ⚡ **Go fast** - Optimized performance for both SQLite and PostgreSQL
+- 🛡️ **Stay secure** - Built-in connection pooling and security best practices
 - 😊 **Have fun** - Finally, coding that doesn't make you cry
 
-**Bottom line:** You get enterprise-grade superpowers with the simplicity of a single file.
+**Bottom line:** You get enterprise-grade superpowers with your choice of database.
 
 ## 🚀 What's the Big Deal? (Spoiler: It's Actually Pretty Big)
 
 **Before NOORMME:** You spend 8 hours setting up a database, 4 hours organizing your project, and 2 hours fighting with AI tools that suggest code from 2019.
 
 **With NOORMME:** Your development environment becomes AI-ready in 5 minutes:
-- ✅ **SQLite that acts like PostgreSQL** - All the power, none of the pain
+- ✅ **SQLite & PostgreSQL support** - Start simple, scale when needed
 - ✅ **Organized architecture** - Patterns that actually make sense
 - ✅ **AI context rules** - Cursor IDE integration that works
 - ✅ **Type safety** - TypeScript that doesn't make you want to throw things
-- ✅ **Production features** - WAL mode, caching, and performance optimization
+- ✅ **Production features** - WAL mode, connection pooling, caching, and performance optimization
 
 **It's literally a development environment that makes AI assistance useful.** 🤯
 
+## 🗄️ Database Support
+
+NOORMME supports multiple database systems with the same API:
+
+### SQLite - Perfect for:
+- 🚀 **Prototyping & MVPs** - Get started in seconds
+- 📱 **Edge deployments** - Cloudflare Workers, Vercel Edge, etc.
+- 💻 **Local-first apps** - Embedded databases in desktop/mobile apps
+- 🧪 **Testing** - Fast, isolated test environments
+- 💰 **Small to medium apps** - No database server needed
+
+### PostgreSQL - Perfect for:
+- 🏢 **Production applications** - Battle-tested reliability
+- 📊 **Complex queries** - Advanced SQL features
+- 🔒 **Multi-user systems** - Robust concurrency handling
+- 📈 **Scaling** - Handle millions of records
+- 🌐 **Traditional deployments** - Client-server architecture
+
 ## ⚡ Get Started in 60 Seconds (No, Really)
 
 ### 1. Install It (The Easy Part)
@@ -66,19 +85,55 @@ npx noormme init
 ```
 
 ### 3. Point at Your Database (The "Wait, That's It?" Part)
+
+#### Option A: SQLite (Simplest)
 ```typescript
 import { NOORMME } from 'noormme'
 
 const db = new NOORMME({
   dialect: 'sqlite',
   connection: {
-    database: './your-database.sqlite'  // Point to your existing database
+    database: './your-database.sqlite'
+  }
+})
+
+await db.initialize()
+```
+
+#### Option B: PostgreSQL (Production-Ready)
+```typescript
+import { NOORMME } from 'noormme'
+
+const db = new NOORMME({
+  dialect: 'postgresql',
+  connection: {
+    host: 'localhost',
+    port: 5432,
+    database: 'your_database',
+    username: 'postgres',
+    password: 'your_password'
   }
 })
 
 await db.initialize()
 ```
 
+#### Option C: Connection String (Easiest)
+```typescript
+import { NOORMME } from 'noormme'
+
+// SQLite
+const db = new NOORMME('sqlite:./your-database.sqlite')
+
+// PostgreSQL
+// const db = new NOORMME('postgresql://user:password@localhost:5432/database')
+
+// Or use DATABASE_URL environment variable
+// const db = new NOORMME()  // Reads from process.env.DATABASE_URL
+
+await db.initialize()
+```
+
 ### 4. Start Building with AI Assistance (The "I'm a Genius Now" Part)
 ```typescript
 // NOORMME automatically finds your 'users' table and creates methods
@@ -247,10 +302,50 @@ const featuredProducts = await productRepo.findManyByFeatured(true)
 const pendingOrders = await orderRepo.findManyByStatus('pending')
 ```
 
+### Production App with PostgreSQL (The "I'm Going Big" Example)
+```typescript
+// Connect to PostgreSQL for production-grade performance
+const db = new NOORMME({
+  dialect: 'postgresql',
+  connection: {
+    host: process.env.DB_HOST || 'localhost',
+    port: parseInt(process.env.DB_PORT || '5432'),
+    database: process.env.DB_NAME || 'myapp',
+    username: process.env.DB_USER || 'postgres',
+    password: process.env.DB_PASSWORD,
+    ssl: process.env.NODE_ENV === 'production',
+    pool: {
+      max: 20,  // Maximum connections
+      min: 5,   // Minimum connections
+      idleTimeoutMillis: 30000,
+    }
+  }
+})
+
+await db.initialize()
+
+// Same API as SQLite - just more powerful!
+const userRepo = db.getRepository('users')
+const users = await userRepo.findAll()
+
+// Advanced PostgreSQL features work seamlessly
+const analytics = await db.getKysely()
+  .selectFrom('orders')
+  .select(({ fn }) => [
+    fn.count('id').as('total_orders'),
+    fn.sum('amount').as('total_revenue'),
+    fn.avg('amount').as('avg_order_value'),
+  ])
+  .where('created_at', '>=', new Date('2024-01-01'))
+  .groupBy('user_id')
+  .execute()
+```
+
 ## 🔧 Configuration (Optional, Because We're Not Dictators)
 
 For most people, the default settings work perfectly. But if you want to customize (because you're a special snowflake):
 
+### SQLite Configuration
 ```typescript
 const db = new NOORMME({
   dialect: 'sqlite',
@@ -269,6 +364,183 @@ const db = new NOORMME({
 })
 ```
 
+### PostgreSQL Configuration
+```typescript
+const db = new NOORMME({
+  dialect: 'postgresql',
+  connection: {
+    host: 'localhost',
+    port: 5432,
+    database: 'myapp',
+    username: 'postgres',
+    password: 'secret',
+    ssl: true,  // Enable SSL
+    pool: {
+      max: 20,                    // Maximum pool size
+      min: 5,                     // Minimum pool size
+      idleTimeoutMillis: 30000,   // Close idle connections after 30s
+      connectionTimeoutMillis: 2000, // Timeout for acquiring connection
+    }
+  },
+  automation: {
+    enableAutoOptimization: true,
+    enableIndexRecommendations: true,
+    enableQueryAnalysis: true,
+  },
+  performance: {
+    enableCaching: true,
+    maxCacheSize: 1000
+  }
+})
+```
+
+### PostgreSQL-Specific Features (The Power Tools)
+
+NOORMME provides comprehensive support for PostgreSQL-specific features:
+
+#### Array Types
+```typescript
+import { PostgresArrayHelpers } from 'noormme/helpers/postgresql'
+
+// Create table with array columns
+await db.kysely.schema
+  .createTable('posts')
+  .addColumn('tags', 'text[]')
+  .addColumn('scores', 'integer[]')
+  .execute()
+
+// Query with array operations
+const posts = await db.kysely
+  .selectFrom('posts')
+  .where(PostgresArrayHelpers.contains('tags', ['typescript']))
+  .execute()
+```
+
+#### JSON/JSONB Operations
+```typescript
+import { PostgresJSONHelpers } from 'noormme/helpers/postgresql'
+
+// Extract and query JSON fields
+const users = await db.kysely
+  .selectFrom('users')
+  .select(PostgresJSONHelpers.extract('metadata', 'email').as('email'))
+  .where(PostgresJSONHelpers.hasKey('metadata', 'phone'))
+  .execute()
+```
+
+#### Full-Text Search
+```typescript
+import { PostgresFullTextHelpers } from 'noormme/helpers/postgresql'
+
+// Add full-text search
+await PostgresFullTextHelpers.addGeneratedTSVectorColumn(
+  db.kysely, 'articles', 'search_vector', ['title', 'content']
+)
+
+// Search with ranking
+const results = await db.kysely
+  .selectFrom('articles')
+  .select(PostgresFullTextHelpers.rank('search_vector', 'typescript').as('rank'))
+  .where(PostgresFullTextHelpers.match('search_vector', 'typescript'))
+  .orderBy('rank', 'desc')
+  .execute()
+```
+
+#### Materialized Views
+```typescript
+import { PostgresMaterializedViewHelpers } from 'noormme/helpers/postgresql'
+
+// Create and manage materialized views
+await PostgresMaterializedViewHelpers.create(
+  db.kysely, 'user_stats',
+  sql`SELECT user_id, COUNT(*) as post_count FROM posts GROUP BY user_id`
+)
+
+await PostgresMaterializedViewHelpers.refresh(db.kysely, 'user_stats', {
+  concurrently: true
+})
+```
+
+**📚 Learn More:** 
+- [PostgreSQL Features Documentation](docs/postgresql-features.md) for detailed feature guides
+- [PostgreSQL Support Documentation](docs/postgresql/POSTGRESQL_SUPPORT.md) for comprehensive overview
+
+### Database Migration Tools (The "Time to Move" Feature)
+
+NOORMME provides powerful tools for migrating databases between SQLite and PostgreSQL:
+
+#### Automated Migration
+
+```typescript
+import { createMigrationManager } from 'noormme/helpers/postgresql'
+
+// Source database (SQLite)
+const sourceDb = new NOORMME('sqlite:./source.sqlite')
+
+// Target database (PostgreSQL)
+const targetDb = new NOORMME('postgresql://user:pass@localhost/target')
+
+await sourceDb.initialize()
+await targetDb.initialize()
+
+// Create migration manager
+const migrationManager = createMigrationManager(
+  sourceDb.getKysely(),
+  targetDb.getKysely(),
+  {
+    source: {
+      dialect: 'sqlite',
+      database: './source.sqlite',
+    },
+    target: {
+      dialect: 'postgresql',
+      database: 'target',
+      host: 'localhost',
+      port: 5432,
+      username: 'user',
+      password: 'pass',
+    },
+    options: {
+      batchSize: 1000,
+      verbose: true,
+    },
+  }
+)
+
+// Perform complete migration (schema + data)
+const result = await migrationManager.migrate()
+console.log(`Migrated ${result.rowsMigrated} rows in ${(result.duration / 1000).toFixed(2)}s`)
+```
+
+#### Schema Comparison & Sync
+
+```typescript
+// Compare schemas
+const comparison = await migrationManager.compareSchemas()
+console.log(`Differences: ${comparison.differences.length}`)
+
+// Generate sync SQL
+const syncResult = await migrationManager.syncSchema({
+  generateSQL: true,
+  apply: false,  // Preview changes without applying
+})
+
+syncResult.sqlStatements.forEach(sql => console.log(sql))
+```
+
+#### Key Migration Features
+
+- ✅ **Bidirectional Migration** - SQLite ↔ PostgreSQL
+- ✅ **Automatic Type Conversion** - Smart mapping between database types
+- ✅ **Value Transformation** - Handle booleans, arrays, JSON, and dates
+- ✅ **Batch Processing** - Efficient large dataset migration
+- ✅ **Parallel Migration** - Multi-table concurrent processing
+- ✅ **Progress Tracking** - Real-time migration progress
+- ✅ **Schema Diff** - Detect schema differences
+- ✅ **Verification** - Automated post-migration checks
+
+**📚 Learn More:** See [Migration Tools Documentation](docs/migration-tools.md) for detailed guides and examples.
+
 ## 🚀 Production Ready (Because We're Not Playing Around)
 
 NOORMME is already running in production applications with real-world success stories. It includes:
@@ -294,10 +566,15 @@ The DreamBeesArt application successfully migrated from Drizzle ORM to NOORMME w
 A: Nope! NOORMME handles most things automatically. You only need SQL for complex queries (and even then, we'll help you).
 
 **Q: Can I use my existing database?**
-A: Yes! Just point NOORMME at your existing SQLite file and it figures everything out (because we're not picky).
+A: Yes! Just point NOORMME at your existing SQLite or PostgreSQL database and it figures everything out (because we're not picky).
+
+**Q: Should I use SQLite or PostgreSQL?**
+A: Start with SQLite for prototyping and small apps (it's faster to set up). Switch to PostgreSQL when you need multi-user support, complex queries, or scaling. The API is identical, so switching is easy!
 
 **Q: Is this really production-ready?**
-A: Absolutely. Real applications are using it right now with better performance than PostgreSQL (because we're not lying).
+A: Absolutely. Real applications are using it right now:
+- SQLite with WAL mode for edge deployments and local-first apps
+- PostgreSQL for traditional production deployments with millions of records
 
 **Q: What if I'm already using another ORM?**
 A: NOORMME works alongside other tools. You can migrate gradually or use both (because we're not territorial).
@@ -309,7 +586,10 @@ A: NOORMME works with JavaScript too, but TypeScript gives you the best experien
 A: NOORMME includes Cursor IDE context rules that make AI assistance actually useful. The AI understands your project structure and generates code that follows your conventions (because we're not savages).
 
 **Q: What makes this different from other toolkits?**
-A: NOORMME combines database automation, organized architecture, and AI-ready patterns in one integrated toolkit. It's not just an ORM - it's a complete development environment (because we're ambitious).
+A: NOORMME combines database automation, organized architecture, and AI-ready patterns in one integrated toolkit. It's not just an ORM - it's a complete development environment that supports both SQLite and PostgreSQL with the same API (because we're ambitious).
+
+**Q: Can I migrate from SQLite to PostgreSQL later?**
+A: Yes! Since NOORMME uses the same API for both databases, migrating is as simple as changing the connection config. Your application code stays the same!
 
 **Q: Will this make me a better developer?**
 A: Probably not, but it will make you feel like one (which is half the battle).

package/dist/cjs/dialect/postgresql/postgresql-adapter.d.ts

@@ -0,0 +1,81 @@
+import { Kysely } from '../../kysely.js';
+import { DialectAdapterBase } from '../dialect-adapter-base.js';
+import { MigrationLockOptions } from '../dialect-adapter.js';
+export declare class PostgresAdapter extends DialectAdapterBase {
+    #private;
+    /**
+     * Whether or not this dialect supports transactional DDL.
+     *
+     * If this is true, migrations are executed inside a transaction.
+     */
+    get supportsTransactionalDdl(): boolean;
+    /**
+     * Whether or not this dialect supports the `returning` in inserts
+     * updates and deletes.
+     */
+    get supportsReturning(): boolean;
+    /**
+     * This method is used to acquire a lock for the migrations so that
+     * it's not possible for two migration operations to run in parallel.
+     *
+     * Most dialects have explicit locks that can be used, like advisory locks
+     * in PostgreSQL and the get_lock function in MySQL.
+     *
+     * If the dialect doesn't have explicit locks the {@link MigrationLockOptions.lockTable}
+     * created by Kysely can be used instead. You can access it through the `options` object.
+     * The lock table has two columns `id` and `is_locked` and there's only one row in the table
+     * whose id is {@link MigrationLockOptions.lockRowId}. `is_locked` is an integer. Kysely
+     * takes care of creating the lock table and inserting the one single row to it before this
+     * method is executed. If the dialect supports schemas and the user has specified a custom
+     * schema in their migration settings, the options object also contains the schema name in
+     * {@link MigrationLockOptions.lockTableSchema}.
+     *
+     * Here's an example of how you might implement this method for a dialect that doesn't
+     * have explicit locks but supports `FOR UPDATE` row locks and transactional DDL:
+     *
+     * ```ts
+     * import { DialectAdapterBase, type MigrationLockOptions, Kysely } from 'kysely'
+     *
+     * export class MyAdapter extends DialectAdapterBase {
+     *   override async acquireMigrationLock(
+     *     db: Kysely<any>,
+     *     options: MigrationLockOptions
+     *   ): Promise<void> {
+     *     const queryDb = options.lockTableSchema
+     *       ? db.withSchema(options.lockTableSchema)
+     *       : db
+     *
+     *     // Since our imaginary dialect supports transactional DDL and has
+     *     // row locks, we can simply take a row lock here and it will guarantee
+     *     // all subsequent calls to this method from other transactions will
+     *     // wait until this transaction finishes.
+     *     await queryDb
+     *       .selectFrom(options.lockTable)
+     *       .selectAll()
+     *       .where('id', '=', options.lockRowId)
+     *       .forUpdate()
+     *       .execute()
+     *   }
+     *
+     *   override async releaseMigrationLock() {
+     *     // noop
+     *   }
+     * }
+     * ```
+     *
+     * If `supportsTransactionalDdl` is `true` then the `db` passed to this method
+     * is a transaction inside which the migrations will be executed. Otherwise
+     * `db` is a single connection (session) that will be used to execute the
+     * migrations.
+     */
+    acquireMigrationLock(db: Kysely<any>, opt: MigrationLockOptions): Promise<void>;
+    /**
+     * Releases the migration lock. See {@link acquireMigrationLock}.
+     *
+     * If `supportsTransactionalDdl` is `true` then the `db` passed to this method
+     * is a transaction inside which the migrations were executed. Otherwise `db`
+     * is a single connection (session) that was used to execute the migrations
+     * and the `acquireMigrationLock` call.
+     */
+    releaseMigrationLock(_db: Kysely<any>, _opt: MigrationLockOptions): Promise<void>;
+}

package/dist/cjs/dialect/postgresql/postgresql-adapter.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresAdapter = void 0;
+const dialect_adapter_base_js_1 = require("../dialect-adapter-base.js");
+// Random id for our migration lock
+const MIGRATION_LOCK_ID = '0.0.1';
+class PostgresAdapter extends dialect_adapter_base_js_1.DialectAdapterBase {
+    get supportsTransactionalDdl() {
+        return true;
+    }
+    get supportsReturning() {
+        return true;
+    }
+    async acquireMigrationLock(db, opt) {
+        const lockTable = opt.lockTable ?? 'kysely_migration_lock';
+        // Postgres uses advisory locks. We need to create a unique lock id
+        // from the lock table name. We use a simple hash function for that.
+        const lockId = this.#hashString(lockTable);
+        await db
+            .selectFrom(lockTable)
+            .selectAll()
+            .where('id', '=', MIGRATION_LOCK_ID)
+            .forUpdate()
+            .execute();
+    }
+    async releaseMigrationLock(_db, _opt) {
+        // Nothing to do here. The migration lock is automatically released
+        // when the transaction is committed/rolled back.
+    }
+    #hashString(str) {
+        let hash = 0;
+        for (let i = 0; i < str.length; i++) {
+            const chr = str.charCodeAt(i);
+            hash = (hash << 5) - hash + chr;
+            hash |= 0; // Convert to 32bit integer
+        }
+        return hash;
+    }
+}
+exports.PostgresAdapter = PostgresAdapter;

package/dist/cjs/dialect/postgresql/postgresql-dialect-config.d.ts

@@ -0,0 +1,65 @@
+import { DatabaseConnection } from '../../driver/database-connection.js';
+import type { PoolConfig } from 'pg';
+/**
+ * Config for the PostgreSQL dialect.
+ */
+export interface PostgresDialectConfig {
+    /**
+     * A postgres Pool instance or a function that returns one.
+     *
+     * If a function is provided, it's called once when the first query is executed.
+     *
+     * https://node-postgres.com/apis/pool
+     */
+    pool?: PostgresPool | (() => Promise<PostgresPool>);
+    /**
+     * Pool configuration for PostgreSQL
+     *
+     * https://node-postgres.com/apis/pool
+     */
+    poolConfig?: PoolConfig;
+    /**
+     * Called once for each created connection.
+     *
+     * This is a NOORMME specific feature and does not come from the `pg` module.
+     */
+    onCreateConnection?: (connection: DatabaseConnection) => Promise<void>;
+    /**
+     * Cursor constructor for streaming queries.
+     */
+    cursor?: PostgresCursorConstructor;
+}
+/**
+ * This interface is the subset of pg Pool that NOORMME needs.
+ *
+ * We don't use the type from `pg` here to not have a dependency to it.
+ *
+ * https://node-postgres.com/apis/pool
+ */
+export interface PostgresPool {
+    connect(): Promise<PostgresPoolClient>;
+    end(): Promise<void>;
+    query<R = any>(sql: string, parameters?: ReadonlyArray<unknown>): Promise<PostgresQueryResult<R>>;
+}
+export interface PostgresPoolClient {
+    query<R = any>(sql: string, parameters?: ReadonlyArray<unknown>): Promise<PostgresQueryResult<R>>;
+    release(): void;
+}
+export interface PostgresQueryResult<R = any> {
+    command: string;
+    rowCount: number | null;
+    rows: R[];
+}
+/**
+ * https://github.com/brianc/node-pg-cursor
+ */
+export interface PostgresCursorConstructor {
+    new (text: string, values: unknown[], config?: unknown): PostgresCursor;
+}
+/**
+ * https://github.com/brianc/node-pg-cursor
+ */
+export interface PostgresCursor extends AsyncIterableIterator<any> {
+    read(rowCount: number): Promise<any[]>;
+    close(): Promise<void>;
+}

package/dist/cjs/dialect/postgresql/postgresql-dialect-config.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/dialect/postgresql/postgresql-dialect.d.ts

@@ -0,0 +1,80 @@
+import { Driver } from '../../driver/driver.js';
+import { Kysely } from '../../kysely.js';
+import { QueryCompiler } from '../../query-compiler/query-compiler.js';
+import { Dialect } from '../dialect.js';
+import { DatabaseIntrospector } from '../database-introspector.js';
+import { DialectAdapter } from '../dialect-adapter.js';
+import { PostgresDialectConfig } from './postgresql-dialect-config.js';
+/**
+ * PostgreSQL dialect that uses the [pg](https://github.com/brianc/node-postgres) library.
+ *
+ * The constructor takes an instance of {@link PostgresDialectConfig}.
+ *
+ * ```ts
+ * import { Pool } from 'pg'
+ *
+ * new PostgresDialect({
+ *   pool: new Pool({
+ *     host: 'localhost',
+ *     database: 'my_database',
+ *     user: 'postgres',
+ *     password: 'postgres',
+ *     port: 5432,
+ *     max: 10,
+ *   })
+ * })
+ * ```
+ *
+ * Alternatively, you can use poolConfig:
+ *
+ * ```ts
+ * new PostgresDialect({
+ *   poolConfig: {
+ *     host: 'localhost',
+ *     database: 'my_database',
+ *     user: 'postgres',
+ *     password: 'postgres',
+ *     port: 5432,
+ *     max: 10,
+ *   }
+ * })
+ * ```
+ *
+ * If you want the pool to only be created once it's first used, `pool`
+ * can be a function:
+ *
+ * ```ts
+ * import { Pool } from 'pg'
+ *
+ * new PostgresDialect({
+ *   pool: async () => new Pool({
+ *     host: 'localhost',
+ *     database: 'my_database',
+ *   })
+ * })
+ * ```
+ */
+export declare class PostgresDialect implements Dialect {
+    #private;
+    constructor(config: PostgresDialectConfig);
+    /**
+     * Creates a driver for the dialect.
+     */
+    createDriver(): Driver;
+    /**
+     * Creates a query compiler for the dialect.
+     */
+    createQueryCompiler(): QueryCompiler;
+    /**
+     * Creates an adapter for the dialect.
+     */
+    createAdapter(): DialectAdapter;
+    /**
+     * Creates a database introspector that can be used to get database metadata
+     * such as the table names and column names of those tables.
+     *
+     * `db` never has any plugins installed. It's created using
+     * {@link Kysely.withoutPlugins}.
+     */
+    createIntrospector(db: Kysely<any>): DatabaseIntrospector;
+}