@onivoro/server-typeorm-postgres 24.0.0 → 24.0.2

package/README.md

@@ -1,6 +1,6 @@
 # @onivoro/server-typeorm-postgres
 
-A comprehensive TypeORM PostgreSQL integration library for NestJS applications, providing custom repositories, migration utilities, decorators, and enhanced PostgreSQL-specific functionality for enterprise-scale database operations.
+A TypeORM PostgreSQL integration library providing repository patterns, SQL generation utilities, migration base classes, and PostgreSQL/Redshift-specific optimizations for enterprise-scale applications.
 
 ## Installation
 
@@ -10,43 +10,30 @@ npm install @onivoro/server-typeorm-postgres
 
 ## Features
 
-- **TypeORM PostgreSQL Module**: Complete NestJS module for PostgreSQL integration
-- **Custom Repository Classes**: Enhanced repository patterns with pagination and utilities
-- **Migration Base Classes**: Structured migration classes for database schema management
-- **Custom Decorators**: PostgreSQL-specific column decorators and table definitions
-- **Redshift Support**: Amazon Redshift repository integration
-- **SQL Writer Utilities**: Advanced SQL generation and execution utilities
-- **Data Source Factory**: Flexible data source configuration and creation
-- **Pagination Support**: Built-in pagination utilities and interfaces
+- **TypeORM Repository Pattern**: Enhanced repository with PostgreSQL-specific features
+- **Redshift Repository**: Specialized repository for Amazon Redshift operations
+- **SQL Writer**: Static utility class for PostgreSQL DDL generation
+- **Migration Base Classes**: Simplified migration classes for common operations
+- **Custom Decorators**: Table and column decorators for entity definitions
+- **Pagination Support**: Abstract paging repository for custom implementations
 - **Type Safety**: Full TypeScript support with comprehensive type definitions
-- **PostgreSQL Optimizations**: PostgreSQL-specific optimizations and best practices
 
 ## Quick Start
 
-### Import the Module
+### Module Import
 
 ```typescript
 import { ServerTypeormPostgresModule } from '@onivoro/server-typeorm-postgres';
 
 @Module({
   imports: [
-    ServerTypeormPostgresModule.forRoot({
-      host: 'localhost',
-      port: 5432,
-      username: 'postgres',
-      password: 'password',
-      database: 'myapp',
-      entities: [User, Product, Order],
-      synchronize: false,
-      logging: true,
-      ssl: process.env.NODE_ENV === 'production' ? { rejectUnauthorized: false } : false
-    })
+    ServerTypeormPostgresModule
   ],
 })
 export class AppModule {}
 ```
 
-### Define Entities with Custom Decorators
+### Entity Definition with Custom Decorators
 
 ```typescript
 import { 
@@ -55,10 +42,8 @@ import {
   TableColumn, 
   NullableTableColumn 
 } from '@onivoro/server-typeorm-postgres';
-import { Entity } from 'typeorm';
 
-@Entity()
-@Table('users')
+@Table({ name: 'users' })
 export class User {
   @PrimaryTableColumn()
   id: number;
@@ -69,850 +54,671 @@ export class User {
   @TableColumn({ type: 'varchar', length: 100 })
   firstName: string;
 
-  @TableColumn({ type: 'varchar', length: 100 })
-  lastName: string;
-
   @NullableTableColumn({ type: 'timestamp' })
   lastLoginAt?: Date;
 
   @TableColumn({ type: 'boolean', default: true })
   isActive: boolean;
 
-  @TableColumn({ type: 'jsonb' })
+  @TableColumn({ type: 'jsonb', default: '{}' })
   metadata: Record<string, any>;
 
   @TableColumn({ type: 'timestamp', default: () => 'CURRENT_TIMESTAMP' })
   createdAt: Date;
 
-  @TableColumn({ 
-    type: 'timestamp', 
-    default: () => 'CURRENT_TIMESTAMP',
-    onUpdate: 'CURRENT_TIMESTAMP'
-  })
-  updatedAt: Date;
-
   @NullableTableColumn({ type: 'timestamp' })
   deletedAt?: Date;
 }
 ```
 
-### Use Custom Repository
+## Repository Classes
+
+### TypeOrmRepository
+
+Enhanced repository with PostgreSQL-specific methods:
 
 ```typescript
 import { Injectable } from '@nestjs/common';
-import { TypeOrmRepository, TypeOrmPagingRepository } from '@onivoro/server-typeorm-postgres';
+import { TypeOrmRepository } from '@onivoro/server-typeorm-postgres';
+import { EntityManager } from 'typeorm';
 import { User } from './user.entity';
 
 @Injectable()
-export class UserRepository extends TypeOrmPagingRepository<User> {
-  constructor() {
-    super(User);
+export class UserRepository extends TypeOrmRepository<User> {
+  constructor(entityManager: EntityManager) {
+    super(User, entityManager);
   }
 
-  async findByEmail(email: string): Promise<User | null> {
-    return this.findOne({ where: { email } });
+  // Core methods available:
+  async findByEmail(email: string): Promise<User> {
+    return this.getOne({ where: { email } });
   }
 
   async findActiveUsers(): Promise<User[]> {
-    return this.find({ 
-      where: { isActive: true, deletedAt: null } 
+    return this.getMany({ 
+      where: { isActive: true } 
     });
   }
 
-  async findUsersWithMetadata(key: string, value: any): Promise<User[]> {
-    return this.createQueryBuilder('user')
-      .where('user.metadata @> :metadata', { 
-        metadata: JSON.stringify({ [key]: value }) 
-      })
-      .getMany();
+  async findUsersWithCount(): Promise<[User[], number]> {
+    return this.getManyAndCount({ 
+      where: { isActive: true } 
+    });
   }
 
-  async softDelete(id: number): Promise<void> {
-    await this.update(id, { deletedAt: new Date() });
+  async createUser(userData: Partial<User>): Promise<User> {
+    return this.postOne(userData);
   }
-}
-```
-
-## Configuration
-
-### Data Source Configuration
-
-```typescript
-import { dataSourceConfigFactory } from '@onivoro/server-typeorm-postgres';
 
-const config = dataSourceConfigFactory({
-  host: process.env.DB_HOST,
-  port: parseInt(process.env.DB_PORT),
-  username: process.env.DB_USERNAME,
-  password: process.env.DB_PASSWORD,
-  database: process.env.DB_DATABASE,
-  entities: [User, Product, Order],
-  migrations: ['src/migrations/*.ts'],
-  synchronize: false,
-  logging: process.env.NODE_ENV === 'development',
-  ssl: process.env.NODE_ENV === 'production' ? { rejectUnauthorized: false } : false,
-  extra: {
-    max: 20, // Connection pool size
-    idleTimeoutMillis: 30000,
-    connectionTimeoutMillis: 2000,
+  async createUsers(usersData: Partial<User>[]): Promise<User[]> {
+    return this.postMany(usersData);
   }
-});
-```
-
-### Dynamic Module Configuration
-
-```typescript
-import { Module } from '@nestjs/common';
-import { ServerTypeormPostgresModule } from '@onivoro/server-typeorm-postgres';
-import { ConfigService } from '@nestjs/config';
-
-@Module({
-  imports: [
-    ServerTypeormPostgresModule.forRootAsync({
-      useFactory: (configService: ConfigService) => ({
-        host: configService.get('DATABASE_HOST'),
-        port: configService.get('DATABASE_PORT'),
-        username: configService.get('DATABASE_USERNAME'),
-        password: configService.get('DATABASE_PASSWORD'),
-        database: configService.get('DATABASE_NAME'),
-        entities: [__dirname + '/**/*.entity{.ts,.js}'],
-        migrations: [__dirname + '/migrations/*{.ts,.js}'],
-        synchronize: configService.get('NODE_ENV') === 'development',
-        logging: configService.get('DATABASE_LOGGING') === 'true',
-        ssl: configService.get('NODE_ENV') === 'production' ? {
-          rejectUnauthorized: false
-        } : false
-      }),
-      inject: [ConfigService]
-    })
-  ],
-})
-export class DatabaseModule {}
-```
 
-## Usage Examples
-
-### Migration Base Classes
+  async updateUser(id: number, updates: Partial<User>): Promise<void> {
+    // patch() uses TypeORM's update() method
+    await this.patch({ id }, updates);
+  }
 
-```typescript
-import { 
-  TableMigrationBase, 
-  ColumnMigrationBase,
-  IndexMigrationBase,
-  DropTableMigrationBase 
-} from '@onivoro/server-typeorm-postgres';
-import { MigrationInterface, QueryRunner } from 'typeorm';
+  async replaceUser(id: number, userData: Partial<User>): Promise<void> {
+    // put() uses TypeORM's save() method
+    await this.put({ id }, userData);
+  }
 
-export class CreateUsersTable1234567890 extends TableMigrationBase implements MigrationInterface {
-  public async up(queryRunner: QueryRunner): Promise<void> {
-    await this.createTable(queryRunner, 'users', [
-      this.createColumn('id', 'SERIAL', { isPrimary: true }),
-      this.createColumn('email', 'VARCHAR(255)', { isUnique: true, isNullable: false }),
-      this.createColumn('first_name', 'VARCHAR(100)', { isNullable: false }),
-      this.createColumn('last_name', 'VARCHAR(100)', { isNullable: false }),
-      this.createColumn('metadata', 'JSONB', { default: "'{}'" }),
-      this.createColumn('is_active', 'BOOLEAN', { default: true }),
-      this.createColumn('created_at', 'TIMESTAMP', { default: 'CURRENT_TIMESTAMP' }),
-      this.createColumn('updated_at', 'TIMESTAMP', { default: 'CURRENT_TIMESTAMP' }),
-      this.createColumn('deleted_at', 'TIMESTAMP', { isNullable: true })
-    ]);
+  async deleteUser(id: number): Promise<void> {
+    await this.delete({ id });
+  }
 
-    // Add indexes
-    await this.createIndex(queryRunner, 'users', ['email']);
-    await this.createIndex(queryRunner, 'users', ['is_active']);
-    await this.createIndex(queryRunner, 'users', ['created_at']);
+  async softDeleteUser(id: number): Promise<void> {
+    await this.softDelete({ id });
   }
 
-  public async down(queryRunner: QueryRunner): Promise<void> {
-    await this.dropTable(queryRunner, 'users');
+  // Transaction support
+  async createUserInTransaction(userData: Partial<User>, entityManager: EntityManager): Promise<User> {
+    const txRepository = this.forTransaction(entityManager);
+    return txRepository.postOne(userData);
   }
-}
 
-export class AddUserProfileColumns1234567891 extends ColumnMigrationBase implements MigrationInterface {
-  public async up(queryRunner: QueryRunner): Promise<void> {
-    await this.addColumn(queryRunner, 'users', 'phone_number', 'VARCHAR(20)', { isNullable: true });
-    await this.addColumn(queryRunner, 'users', 'date_of_birth', 'DATE', { isNullable: true });
-    await this.addColumn(queryRunner, 'users', 'avatar_url', 'TEXT', { isNullable: true });
+  // Custom queries with mapping
+  async findUsersByMetadata(key: string, value: any): Promise<User[]> {
+    const query = `
+      SELECT * FROM ${this.getTableNameExpression()}
+      WHERE metadata->>'${key}' = $1
+      AND deleted_at IS NULL
+    `;
+    return this.queryAndMap(query, [value]);
   }
 
-  public async down(queryRunner: QueryRunner): Promise<void> {
-    await this.dropColumn(queryRunner, 'users', 'avatar_url');
-    await this.dropColumn(queryRunner, 'users', 'date_of_birth');
-    await this.dropColumn(queryRunner, 'users', 'phone_number');
+  // Using ILike for case-insensitive search
+  async searchUsers(searchTerm: string): Promise<User[]> {
+    const filters = this.buildWhereILike({
+      firstName: searchTerm,
+      lastName: searchTerm,
+      email: searchTerm
+    });
+    
+    return this.getMany({ where: filters });
   }
 }
 ```
 
-### Advanced Repository Usage
+### TypeOrmPagingRepository
+
+Abstract base class for implementing pagination:
 
 ```typescript
 import { Injectable } from '@nestjs/common';
-import { TypeOrmPagingRepository, PageParams, PagedData } from '@onivoro/server-typeorm-postgres';
+import { TypeOrmPagingRepository, IPageParams, IPagedData } from '@onivoro/server-typeorm-postgres';
+import { EntityManager, FindManyOptions } from 'typeorm';
 import { User } from './user.entity';
-import { FindOptionsWhere, ILike, Raw, Between } from 'typeorm';
 
-@Injectable()
-export class AdvancedUserRepository extends TypeOrmPagingRepository<User> {
-  constructor() {
-    super(User);
-  }
+// Define your custom params interface
+interface UserPageParams {
+  isActive?: boolean;
+  search?: string;
+  departmentId?: number;
+}
 
-  async searchUsersWithFullText(
-    searchTerm: string,
-    pageParams: PageParams
-  ): Promise<PagedData<User>> {
-    // PostgreSQL full-text search
-    return this.findWithPaging(
-      {
-        where: Raw(alias => `to_tsvector('english', ${alias}.first_name || ' ' || ${alias}.last_name || ' ' || ${alias}.email) @@ plainto_tsquery('english', :searchTerm)`, { searchTerm }),
-        order: { createdAt: 'DESC' }
-      },
-      pageParams
-    );
+@Injectable()
+export class UserPagingRepository extends TypeOrmPagingRepository<User, UserPageParams> {
+  constructor(entityManager: EntityManager) {
+    super(User, entityManager);
   }
 
-  async findUsersByMetadataPath(
-    jsonPath: string,
-    value: any,
-    pageParams: PageParams
-  ): Promise<PagedData<User>> {
-    return this.findWithPaging(
-      {
-        where: Raw(alias => `${alias}.metadata #>> :path = :value`, { 
-          path: `{${jsonPath}}`,
-          value: String(value)
-        })
-      },
-      pageParams
-    );
-  }
+  // You must implement the abstract getPage method
+  async getPage(pageParams: IPageParams, params: UserPageParams): Promise<IPagedData<User>> {
+    const { page, limit } = pageParams;
+    const skip = this.getSkip(page, limit);
 
-  async findUsersWithArrayContains(
-    metadataKey: string,
-    containsValue: string
-  ): Promise<User[]> {
-    return this.createQueryBuilder('user')
-      .where(`user.metadata->:key @> :value`, {
-        key: metadataKey,
-        value: JSON.stringify([containsValue])
-      })
-      .getMany();
-  }
+    // Build where conditions
+    const where = this.removeFalseyKeys({
+      isActive: params.isActive,
+      departmentId: params.departmentId
+    });
 
-  async findUsersByDateRange(
-    startDate: Date,
-    endDate: Date,
-    pageParams: PageParams
-  ): Promise<PagedData<User>> {
-    return this.findWithPaging(
-      {
-        where: {
-          createdAt: Between(startDate, endDate),
-          deletedAt: null
-        },
-        order: { createdAt: 'DESC' }
-      },
-      pageParams
-    );
-  }
+    // Add search conditions if provided
+    if (params.search) {
+      Object.assign(where, this.buildWhereILike({
+        firstName: params.search,
+        lastName: params.search,
+        email: params.search
+      }));
+    }
 
-  async getUserAggregateStats(): Promise<{
-    total: number;
-    active: number;
-    inactive: number;
-    avgMetadataSize: number;
-    recentRegistrations: number;
-  }> {
-    const result = await this.createQueryBuilder('user')
-      .select([
-        'COUNT(*) as total',
-        'COUNT(CASE WHEN user.isActive = true THEN 1 END) as active',
-        'COUNT(CASE WHEN user.isActive = false THEN 1 END) as inactive',
-        'AVG(jsonb_array_length(user.metadata)) as avgMetadataSize',
-        `COUNT(CASE WHEN user.createdAt >= :weekAgo THEN 1 END) as recentRegistrations`
-      ])
-      .where('user.deletedAt IS NULL')
-      .setParameter('weekAgo', new Date(Date.now() - 7 * 24 * 60 * 60 * 1000))
-      .getRawOne();
+    const [data, total] = await this.getManyAndCount({
+      where,
+      skip,
+      take: limit,
+      order: { createdAt: 'DESC' }
+    });
 
     return {
-      total: parseInt(result.total),
-      active: parseInt(result.active),
-      inactive: parseInt(result.inactive),
-      avgMetadataSize: parseFloat(result.avgmetadatasize) || 0,
-      recentRegistrations: parseInt(result.recentregistrations)
+      data,
+      total,
+      page,
+      limit,
+      totalPages: Math.ceil(total / limit),
+      hasNext: page < Math.ceil(total / limit),
+      hasPrev: page > 1
     };
   }
+
+  // You can add additional helper methods
+  getCacheKey(pageParams: IPageParams, params: UserPageParams): string {
+    return this.getPagingKey(pageParams.page, pageParams.limit) + '_' + JSON.stringify(params);
+  }
 }
 ```
 
-### Redshift Integration
+### RedshiftRepository
+
+Specialized repository for Amazon Redshift with custom SQL building:
 
 ```typescript
 import { Injectable } from '@nestjs/common';
 import { RedshiftRepository } from '@onivoro/server-typeorm-postgres';
+import { EntityManager } from 'typeorm';
+import { AnalyticsEvent } from './analytics-event.entity';
 
 @Injectable()
-export class AnalyticsRepository extends RedshiftRepository {
-  constructor() {
-    super();
+export class AnalyticsRepository extends RedshiftRepository<AnalyticsEvent> {
+  constructor(entityManager: EntityManager) {
+    super(AnalyticsEvent, entityManager);
   }
 
-  async getUserActivitySummary(startDate: Date, endDate: Date) {
-    return this.query(`
-      SELECT 
-        u.id,
-        u.email,
-        COUNT(a.id) as activity_count,
-        MAX(a.created_at) as last_activity,
-        AVG(a.duration) as avg_duration
-      FROM users u
-      LEFT JOIN user_activities a ON u.id = a.user_id
-      WHERE a.created_at BETWEEN $1 AND $2
-      GROUP BY u.id, u.email
-      ORDER BY activity_count DESC
-      LIMIT 100
-    `, [startDate, endDate]);
+  // RedshiftRepository overrides several methods for Redshift compatibility
+  async createAnalyticsEvent(event: Partial<AnalyticsEvent>): Promise<AnalyticsEvent> {
+    // Uses custom SQL building and retrieval
+    return this.postOne(event);
   }
 
-  async getMonthlyUserGrowth() {
-    return this.query(`
-      SELECT 
-        DATE_TRUNC('month', created_at) as month,
-        COUNT(*) as new_users,
-        SUM(COUNT(*)) OVER (ORDER BY DATE_TRUNC('month', created_at)) as cumulative_users
-      FROM users
-      WHERE deleted_at IS NULL
-      GROUP BY DATE_TRUNC('month', created_at)
-      ORDER BY month
-    `);
+  async bulkInsertEvents(events: Partial<AnalyticsEvent>[]): Promise<AnalyticsEvent[]> {
+    // Uses optimized bulk insert
+    return this.postMany(events);
   }
 
-  async getUserSegmentAnalysis() {
-    return this.query(`
-      WITH user_segments AS (
-        SELECT 
-          u.id,
-          u.metadata->>'segment' as segment,
-          COUNT(o.id) as order_count,
-          SUM(o.total_amount) as total_spent
-        FROM users u
-        LEFT JOIN orders o ON u.id = o.user_id
-        WHERE u.deleted_at IS NULL
-        GROUP BY u.id, u.metadata->>'segment'
-      )
+  // Performance-optimized methods unique to RedshiftRepository
+  async insertWithoutReturn(event: Partial<AnalyticsEvent>): Promise<void> {
+    // Inserts without performing retrieval query
+    await this.postOneWithoutReturn(event);
+  }
+
+  async bulkInsertWithoutReturn(events: Partial<AnalyticsEvent>[]): Promise<void> {
+    // NOTE: Currently throws NotImplementedException
+    // await this.postManyWithoutReturn(events);
+  }
+
+  // Custom analytics queries
+  async getEventAnalytics(startDate: Date, endDate: Date) {
+    const query = `
       SELECT 
-        segment,
-        COUNT(*) as user_count,
-        AVG(order_count) as avg_orders_per_user,
-        AVG(total_spent) as avg_spend_per_user,
-        SUM(total_spent) as total_segment_revenue
-      FROM user_segments
-      GROUP BY segment
-      ORDER BY total_segment_revenue DESC
-    `);
+        event_type,
+        COUNT(*) as event_count,
+        COUNT(DISTINCT user_id) as unique_users,
+        DATE_TRUNC('day', created_at) as event_date
+      FROM ${this.getTableNameExpression()}
+      WHERE created_at BETWEEN $1 AND $2
+      GROUP BY event_type, event_date
+      ORDER BY event_date DESC, event_count DESC
+    `;
+    
+    return this.query(query, [startDate, endDate]);
+  }
+
+  // Redshift handles JSONB differently
+  async findEventsByJsonData(key: string, value: any): Promise<AnalyticsEvent[]> {
+    // JSON_PARSE is used automatically for jsonb columns in Redshift
+    const query = `
+      SELECT * FROM ${this.getTableNameExpression()}
+      WHERE JSON_EXTRACT_PATH_TEXT(event_data, '${key}') = $1
+    `;
+    
+    return this.queryAndMap(query, [value]);
   }
 }
 ```
 
-### SQL Writer Utilities
+## SQL Writer
+
+Static utility class for generating PostgreSQL DDL:
 
 ```typescript
-import { Injectable } from '@nestjs/common';
 import { SqlWriter } from '@onivoro/server-typeorm-postgres';
-import { DataSource } from 'typeorm';
-
-@Injectable()
-export class ReportingService {
-  private sqlWriter: SqlWriter;
-
-  constructor(private dataSource: DataSource) {
-    this.sqlWriter = new SqlWriter(dataSource);
-  }
-
-  async generateUserReport(filters: {
-    startDate?: Date;
-    endDate?: Date;
-    segment?: string;
-    isActive?: boolean;
-  }) {
-    const query = this.sqlWriter
-      .select([
-        'u.id',
-        'u.email',
-        'u.first_name',
-        'u.last_name',
-        'u.metadata',
-        'u.created_at',
-        'COUNT(o.id) as order_count',
-        'SUM(o.total_amount) as total_spent'
-      ])
-      .from('users', 'u')
-      .leftJoin('orders', 'o', 'u.id = o.user_id')
-      .where('u.deleted_at IS NULL');
-
-    if (filters.startDate) {
-      query.andWhere('u.created_at >= :startDate', { startDate: filters.startDate });
-    }
+import { TableColumnOptions } from 'typeorm';
+
+// Add single column
+const addColumnSql = SqlWriter.addColumn('users', {
+  name: 'phone_number',
+  type: 'varchar',
+  length: 20,
+  isNullable: true
+});
+// Returns: ALTER TABLE "users" ADD "phone_number" varchar(20)
+
+// Create table with multiple columns
+const createTableSql = SqlWriter.createTable('products', [
+  { name: 'id', type: 'serial', isPrimary: true },
+  { name: 'name', type: 'varchar', length: 255, isNullable: false },
+  { name: 'price', type: 'decimal', precision: 10, scale: 2 },
+  { name: 'metadata', type: 'jsonb', default: {} },
+  { name: 'created_at', type: 'timestamp', default: 'CURRENT_TIMESTAMP' }
+]);
+
+// Drop table
+const dropTableSql = SqlWriter.dropTable('products');
+// Returns: DROP TABLE "products";
+
+// Add multiple columns
+const addColumnsSql = SqlWriter.addColumns('products', [
+  { name: 'category_id', type: 'int', isNullable: true },
+  { name: 'sku', type: 'varchar', length: 50, isUnique: true }
+]);
+
+// Drop column
+const dropColumnSql = SqlWriter.dropColumn('products', { name: 'old_column' });
+// Returns: ALTER TABLE "products" DROP COLUMN old_column
+
+// Create indexes
+const createIndexSql = SqlWriter.createIndex('products', 'name', false);
+// Returns: CREATE INDEX IF NOT EXISTS products_name ON "products"(name)
+
+const createUniqueIndexSql = SqlWriter.createUniqueIndex('products', 'sku');
+// Returns: CREATE UNIQUE INDEX IF NOT EXISTS products_sku ON "products"(sku)
+
+// Drop index
+const dropIndexSql = SqlWriter.dropIndex('products_name');
+// Returns: DROP INDEX IF EXISTS products_name
+
+// Handle special default values
+const jsonbColumn: TableColumnOptions = {
+  name: 'settings',
+  type: 'jsonb',
+  default: { notifications: true, theme: 'light' }
+};
+const jsonbSql = SqlWriter.addColumn('users', jsonbColumn);
+// Returns: ALTER TABLE "users" ADD "settings" jsonb DEFAULT '{"notifications":true,"theme":"light"}'::jsonb
+
+// Boolean and numeric defaults
+const booleanSql = SqlWriter.addColumn('users', {
+  name: 'is_verified',
+  type: 'boolean',
+  default: false
+});
+// Returns: ALTER TABLE "users" ADD "is_verified" boolean DEFAULT FALSE
+```
 
-    if (filters.endDate) {
-      query.andWhere('u.created_at <= :endDate', { endDate: filters.endDate });
-    }
+## Migration Base Classes
 
-    if (filters.segment) {
-      query.andWhere("u.metadata->>'segment' = :segment", { segment: filters.segment });
-    }
+### TableMigrationBase
 
-    if (filters.isActive !== undefined) {
-      query.andWhere('u.is_active = :isActive', { isActive: filters.isActive });
-    }
+```typescript
+import { TableMigrationBase } from '@onivoro/server-typeorm-postgres';
+import { MigrationInterface } from 'typeorm';
 
-    return query
-      .groupBy(['u.id', 'u.email', 'u.first_name', 'u.last_name', 'u.metadata', 'u.created_at'])
-      .orderBy('u.created_at', 'DESC')
-      .execute();
+export class CreateUsersTable1234567890 extends TableMigrationBase implements MigrationInterface {
+  constructor() {
+    super('users', [
+      { name: 'id', type: 'serial', isPrimary: true },
+      { name: 'email', type: 'varchar', length: 255, isUnique: true, isNullable: false },
+      { name: 'first_name', type: 'varchar', length: 100, isNullable: false },
+      { name: 'metadata', type: 'jsonb', default: '{}' },
+      { name: 'is_active', type: 'boolean', default: true },
+      { name: 'created_at', type: 'timestamp', default: 'CURRENT_TIMESTAMP' },
+      { name: 'deleted_at', type: 'timestamp', isNullable: true }
+    ]);
   }
+}
+```
 
-  async generateDashboardMetrics() {
-    const queries = {
-      totalUsers: this.sqlWriter
-        .select('COUNT(*)')
-        .from('users')
-        .where('deleted_at IS NULL'),
-
-      activeUsers: this.sqlWriter
-        .select('COUNT(*)')
-        .from('users')
-        .where('deleted_at IS NULL')
-        .andWhere('is_active = true'),
-
-      newUsersThisMonth: this.sqlWriter
-        .select('COUNT(*)')
-        .from('users')
-        .where('deleted_at IS NULL')
-        .andWhere("created_at >= DATE_TRUNC('month', CURRENT_DATE)"),
-
-      totalOrders: this.sqlWriter
-        .select('COUNT(*)')
-        .from('orders'),
-
-      totalRevenue: this.sqlWriter
-        .select('SUM(total_amount)')
-        .from('orders')
-        .where("status != 'cancelled'")
-    };
+### ColumnMigrationBase
 
-    const results = await Promise.all(
-      Object.entries(queries).map(async ([key, query]) => [
-        key,
-        await query.getRawOne()
-      ])
-    );
+```typescript
+import { ColumnMigrationBase } from '@onivoro/server-typeorm-postgres';
 
-    return Object.fromEntries(results);
+export class AddUserPhoneNumber1234567891 extends ColumnMigrationBase {
+  constructor() {
+    super('users', {
+      name: 'phone_number',
+      type: 'varchar',
+      length: 20,
+      isNullable: true
+    });
   }
 }
 ```
 
-### Complex Entity Relationships
+### ColumnsMigrationBase
 
 ```typescript
-import { 
-  Table, 
-  PrimaryTableColumn, 
-  TableColumn, 
-  NullableTableColumn,
-  ManyToOneRelationOptions 
-} from '@onivoro/server-typeorm-postgres';
-import { Entity, ManyToOne, OneToMany, JoinColumn, Index } from 'typeorm';
-
-@Entity()
-@Table('orders')
-@Index(['userId', 'status'])
-@Index(['createdAt'])
-export class Order {
-  @PrimaryTableColumn()
-  id: number;
+import { ColumnsMigrationBase } from '@onivoro/server-typeorm-postgres';
 
-  @TableColumn({ type: 'varchar', length: 50, unique: true })
-  orderNumber: string;
-
-  @TableColumn({ type: 'decimal', precision: 12, scale: 2 })
-  totalAmount: number;
-
-  @TableColumn({ 
-    type: 'enum', 
-    enum: ['pending', 'processing', 'shipped', 'delivered', 'cancelled', 'refunded'] 
-  })
-  status: string;
-
-  @TableColumn({ type: 'int' })
-  userId: number;
-
-  @TableColumn({ type: 'jsonb', default: '{}' })
-  metadata: Record<string, any>;
-
-  @TableColumn({ type: 'timestamp', default: () => 'CURRENT_TIMESTAMP' })
-  createdAt: Date;
-
-  @NullableTableColumn({ type: 'timestamp' })
-  shippedAt?: Date;
-
-  @NullableTableColumn({ type: 'timestamp' })
-  deliveredAt?: Date;
-
-  @NullableTableColumn({ type: 'timestamp' })
-  cancelledAt?: Date;
-
-  // Full-text search column
-  @TableColumn({ type: 'tsvector', select: false })
-  searchVector: string;
-
-  // Relationships
-  @ManyToOne(() => User, user => user.orders, ManyToOneRelationOptions)
-  @JoinColumn({ name: 'userId' })
-  user: User;
-
-  @OneToMany(() => OrderItem, orderItem => orderItem.order, { cascade: true })
-  items: OrderItem[];
+export class AddUserContactInfo1234567892 extends ColumnsMigrationBase {
+  constructor() {
+    super('users', [
+      { name: 'phone_number', type: 'varchar', length: 20, isNullable: true },
+      { name: 'secondary_email', type: 'varchar', length: 255, isNullable: true },
+      { name: 'address', type: 'jsonb', isNullable: true }
+    ]);
+  }
 }
+```
 
-@Entity()
-@Table('order_items')
-@Index(['orderId', 'productId'])
-export class OrderItem {
-  @PrimaryTableColumn()
-  id: number;
-
-  @TableColumn({ type: 'int' })
-  orderId: number;
-
-  @TableColumn({ type: 'int' })
-  productId: number;
+### IndexMigrationBase
 
-  @TableColumn({ type: 'int' })
-  quantity: number;
+```typescript
+import { IndexMigrationBase } from '@onivoro/server-typeorm-postgres';
 
-  @TableColumn({ type: 'decimal', precision: 10, scale: 2 })
-  unitPrice: number;
+export class CreateUserEmailIndex1234567893 extends IndexMigrationBase {
+  constructor() {
+    super('users', 'email', true); // table, column, unique
+  }
+}
+```
 
-  @TableColumn({ type: 'decimal', precision: 10, scale: 2 })
-  totalPrice: number;
+### DropTableMigrationBase & DropColumnMigrationBase
 
-  @TableColumn({ type: 'jsonb', default: '{}' })
-  productSnapshot: Record<string, any>;
+```typescript
+import { DropTableMigrationBase, DropColumnMigrationBase } from '@onivoro/server-typeorm-postgres';
 
-  @ManyToOne(() => Order, order => order.items, ManyToOneRelationOptions)
-  @JoinColumn({ name: 'orderId' })
-  order: Order;
+export class DropLegacyUsersTable1234567894 extends DropTableMigrationBase {
+  constructor() {
+    super('legacy_users');
+  }
+}
 
-  @ManyToOne(() => Product, product => product.orderItems, ManyToOneRelationOptions)
-  @JoinColumn({ name: 'productId' })
-  product: Product;
+export class DropUserMiddleName1234567895 extends DropColumnMigrationBase {
+  constructor() {
+    super('users', { name: 'middle_name' });
+  }
 }
 ```
 
-### Advanced PostgreSQL Features
+## Building Repositories from Metadata
+
+Both TypeOrmRepository and RedshiftRepository support building instances from metadata:
 
 ```typescript
-import { Injectable } from '@nestjs/common';
+import { TypeOrmRepository, RedshiftRepository } from '@onivoro/server-typeorm-postgres';
 import { DataSource } from 'typeorm';
 
-@Injectable()
-export class PostgresAdvancedService {
-  constructor(private dataSource: DataSource) {}
-
-  async createFullTextSearchIndex(tableName: string, columns: string[]): Promise<void> {
-    const vectorColumn = `${tableName}_search_vector`;
-    const indexName = `idx_${tableName}_fulltext`;
-    
-    // Add tsvector column if it doesn't exist
-    await this.dataSource.query(`
-      ALTER TABLE ${tableName} 
-      ADD COLUMN IF NOT EXISTS ${vectorColumn} tsvector
-    `);
-
-    // Create trigger to update search vector
-    await this.dataSource.query(`
-      CREATE OR REPLACE FUNCTION update_${tableName}_search_vector() 
-      RETURNS trigger AS $$
-      BEGIN
-        NEW.${vectorColumn} := to_tsvector('english', ${columns.map(col => `COALESCE(NEW.${col}, '')`).join(" || ' ' || ")});
-        RETURN NEW;
-      END;
-      $$ LANGUAGE plpgsql;
-    `);
-
-    // Create trigger
-    await this.dataSource.query(`
-      DROP TRIGGER IF EXISTS trigger_${tableName}_search_vector ON ${tableName};
-      CREATE TRIGGER trigger_${tableName}_search_vector
-      BEFORE INSERT OR UPDATE ON ${tableName}
-      FOR EACH ROW EXECUTE FUNCTION update_${tableName}_search_vector();
-    `);
-
-    // Create GIN index
-    await this.dataSource.query(`
-      CREATE INDEX IF NOT EXISTS ${indexName} 
-      ON ${tableName} USING gin(${vectorColumn})
-    `);
-
-    // Update existing records
-    await this.dataSource.query(`
-      UPDATE ${tableName} 
-      SET ${vectorColumn} = to_tsvector('english', ${columns.map(col => `COALESCE(${col}, '')`).join(" || ' ' || ")})
-    `);
-  }
-
-  async performFullTextSearch(
-    tableName: string,
-    searchTerm: string,
-    limit: number = 10
-  ): Promise<any[]> {
-    const vectorColumn = `${tableName}_search_vector`;
-    
-    return this.dataSource.query(`
-      SELECT *, 
-             ts_rank(${vectorColumn}, plainto_tsquery('english', $1)) as rank
-      FROM ${tableName}
-      WHERE ${vectorColumn} @@ plainto_tsquery('english', $1)
-      ORDER BY rank DESC
-      LIMIT $2
-    `, [searchTerm, limit]);
-  }
-
-  async createPartitionedTable(
-    tableName: string,
-    partitionColumn: string,
-    partitionType: 'RANGE' | 'LIST' | 'HASH' = 'RANGE'
-  ): Promise<void> {
-    await this.dataSource.query(`
-      CREATE TABLE ${tableName}_partitioned (
-        LIKE ${tableName} INCLUDING ALL
-      ) PARTITION BY ${partitionType} (${partitionColumn})
-    `);
-  }
+// Define your entity type
+interface UserEvent {
+  id: number;
+  userId: number;
+  eventType: string;
+  eventData: any;
+  createdAt: Date;
+}
 
-  async createMonthlyPartitions(
-    tableName: string,
-    startDate: Date,
-    months: number
-  ): Promise<void> {
-    for (let i = 0; i < months; i++) {
-      const date = new Date(startDate);
-      date.setMonth(date.getMonth() + i);
-      
-      const year = date.getFullYear();
-      const month = String(date.getMonth() + 1).padStart(2, '0');
-      const partitionName = `${tableName}_${year}_${month}`;
-      
-      const startOfMonth = new Date(year, date.getMonth(), 1);
-      const startOfNextMonth = new Date(year, date.getMonth() + 1, 1);
-      
-      await this.dataSource.query(`
-        CREATE TABLE IF NOT EXISTS ${partitionName}
-        PARTITION OF ${tableName}_partitioned
-        FOR VALUES FROM ('${startOfMonth.toISOString()}') TO ('${startOfNextMonth.toISOString()}')
-      `);
+// Build TypeORM repository from metadata
+const userEventRepo = TypeOrmRepository.buildFromMetadata<UserEvent>(dataSource, {
+  schema: 'public',
+  table: 'user_events',
+  columns: {
+    id: { 
+      databasePath: 'id', 
+      type: 'int', 
+      propertyPath: 'id', 
+      isPrimary: true,
+      default: undefined 
+    },
+    userId: { 
+      databasePath: 'user_id', 
+      type: 'int', 
+      propertyPath: 'userId', 
+      isPrimary: false,
+      default: undefined 
+    },
+    eventType: { 
+      databasePath: 'event_type', 
+      type: 'varchar', 
+      propertyPath: 'eventType', 
+      isPrimary: false,
+      default: undefined 
+    },
+    eventData: { 
+      databasePath: 'event_data', 
+      type: 'jsonb', 
+      propertyPath: 'eventData', 
+      isPrimary: false,
+      default: {} 
+    },
+    createdAt: { 
+      databasePath: 'created_at', 
+      type: 'timestamp', 
+      propertyPath: 'createdAt', 
+      isPrimary: false,
+      default: 'CURRENT_TIMESTAMP' 
     }
   }
+});
 
-  async createHypertable(tableName: string, timeColumn: string): Promise<void> {
-    // For TimescaleDB extension
-    await this.dataSource.query(`
-      SELECT create_hypertable('${tableName}', '${timeColumn}', if_not_exists => TRUE)
-    `);
-  }
-
-  async analyzeTableStatistics(tableName: string): Promise<any> {
-    return this.dataSource.query(`
-      SELECT 
-        schemaname,
-        tablename,
-        attname,
-        n_distinct,
-        most_common_vals,
-        most_common_freqs,
-        histogram_bounds
-      FROM pg_stats 
-      WHERE tablename = $1
-    `, [tableName]);
+// Build Redshift repository from metadata
+const analyticsRepo = RedshiftRepository.buildFromMetadata<UserEvent>(redshiftDataSource, {
+  schema: 'analytics',
+  table: 'user_events',
+  columns: {
+    // Same column definitions as above
   }
+});
 
-  async getTableSize(tableName: string): Promise<any> {
-    return this.dataSource.query(`
-      SELECT 
-        pg_size_pretty(pg_total_relation_size($1)) as total_size,
-        pg_size_pretty(pg_relation_size($1)) as table_size,
-        pg_size_pretty(pg_indexes_size($1)) as indexes_size
-    `, [tableName]);
-  }
-}
+// Use the repositories
+const events = await userEventRepo.getMany({ where: { userId: 123 } });
+const recentEvent = await userEventRepo.getOne({ where: { id: 456 } });
 ```
 
-## API Reference
-
-### Repository Classes
-
-#### TypeOrmRepository<T>
-
-Base repository class with PostgreSQL optimizations:
+## Data Source Configuration
 
 ```typescript
-export class TypeOrmRepository<T> extends Repository<T> {
-  constructor(entity: EntityTarget<T>)
-}
-```
-
-#### TypeOrmPagingRepository<T>
-
-Repository with built-in pagination support:
+import { dataSourceFactory, dataSourceConfigFactory } from '@onivoro/server-typeorm-postgres';
+import { User, Product, Order } from './entities';
+
+// Using data source factory
+const dataSource = dataSourceFactory('postgres-main', {
+  host: 'localhost',
+  port: 5432,
+  username: 'postgres',
+  password: 'password',
+  database: 'myapp'
+}, [User, Product, Order]);
+
+// Using config factory for more control
+const config = dataSourceConfigFactory('postgres-main', {
+  host: process.env.DB_HOST,
+  port: parseInt(process.env.DB_PORT),
+  username: process.env.DB_USERNAME,
+  password: process.env.DB_PASSWORD,
+  database: process.env.DB_DATABASE,
+  ssl: process.env.NODE_ENV === 'production' ? { rejectUnauthorized: false } : false
+}, [User, Product, Order]);
 
-```typescript
-export class TypeOrmPagingRepository<T> extends TypeOrmRepository<T> {
-  async findWithPaging(
-    options: FindManyOptions<T>,
-    pageParams: PageParams
-  ): Promise<PagedData<T>>
-}
+const dataSource = new DataSource(config);
 ```
 
-#### RedshiftRepository
+## Type Definitions
 
-Repository for Amazon Redshift operations:
+### Core Types
 
 ```typescript
-export class RedshiftRepository {
-  async query(sql: string, parameters?: any[]): Promise<any[]>
-  async execute(sql: string, parameters?: any[]): Promise<void>
+// Table metadata
+interface TTableMeta {
+  databasePath: string;
+  type: string;
+  propertyPath: string;
+  isPrimary: boolean;
+  default?: any;
 }
-```
-
-### Migration Base Classes
 
-#### TableMigrationBase
-
-Base class for table creation migrations:
-
-```typescript
-export abstract class TableMigrationBase {
-  protected createTable(queryRunner: QueryRunner, tableName: string, columns: ColumnDefinition[]): Promise<void>
-  protected dropTable(queryRunner: QueryRunner, tableName: string): Promise<void>
-  protected createIndex(queryRunner: QueryRunner, tableName: string, columns: string[]): Promise<void>
+// Page parameters
+interface IPageParams {
+  page: number;
+  limit: number;
 }
-```
 
-#### ColumnMigrationBase
+// Paged data result
+interface IPagedData<T> {
+  data: T[];
+  total: number;
+  page: number;
+  limit: number;
+  totalPages: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+}
 
-Base class for column modifications:
+// Data source options
+interface IDataSourceOptions {
+  host: string;
+  port: number;
+  username: string;
+  password: string;
+  database: string;
+  ssl?: any;
+  extra?: any;
+}
 
-```typescript
-export abstract class ColumnMigrationBase {
-  protected addColumn(queryRunner: QueryRunner, tableName: string, columnName: string, type: string, options?: ColumnOptions): Promise<void>
-  protected dropColumn(queryRunner: QueryRunner, tableName: string, columnName: string): Promise<void>
-  protected changeColumn(queryRunner: QueryRunner, tableName: string, columnName: string, newType: string): Promise<void>
+// Entity provider interface
+interface IEntityProvider<TEntity, TFindOneOptions, TFindManyOptions, TFindOptionsWhere, TUpdateData> {
+  getOne(options: TFindOneOptions): Promise<TEntity>;
+  getMany(options: TFindManyOptions): Promise<TEntity[]>;
+  getManyAndCount(options: TFindManyOptions): Promise<[TEntity[], number]>;
+  postOne(body: Partial<TEntity>): Promise<TEntity>;
+  postMany(body: Partial<TEntity>[]): Promise<TEntity[]>;
+  delete(options: TFindOptionsWhere): Promise<void>;
+  softDelete(options: TFindOptionsWhere): Promise<void>;
+  put(options: TFindOptionsWhere, body: TUpdateData): Promise<void>;
+  patch(options: TFindOptionsWhere, body: TUpdateData): Promise<void>;
 }
 ```
 
-### SQL Writer
-
-#### SqlWriter
-
-Advanced SQL query builder:
+## Utility Functions
 
 ```typescript
-export class SqlWriter {
-  constructor(dataSource: DataSource)
-  
-  select(columns: string[]): SqlWriter
-  from(table: string, alias?: string): SqlWriter
-  leftJoin(table: string, alias: string, condition: string): SqlWriter
-  where(condition: string, parameters?: Record<string, any>): SqlWriter
-  groupBy(columns: string[]): SqlWriter
-  orderBy(column: string, direction?: 'ASC' | 'DESC'): SqlWriter
-  execute(): Promise<any[]>
-}
-```
+import { 
+  getSkip, 
+  getPagingKey, 
+  removeFalseyKeys,
+  generateDateQuery,
+  getApiTypeFromColumn 
+} from '@onivoro/server-typeorm-postgres';
 
-### Type Definitions
+// Calculate skip value for pagination
+const skip = getSkip(2, 20); // page 2, limit 20 = skip 20
 
-#### TableMeta
+// Generate cache key for pagination
+const cacheKey = getPagingKey(2, 20); // Returns: "page_2_limit_20"
 
-Table metadata type:
+// Remove falsey values from object
+const cleanedFilters = removeFalseyKeys({
+  name: 'John',
+  age: 0,        // Removed
+  active: false, // Kept (false is not falsey for this function)
+  email: '',     // Removed
+  dept: null     // Removed
+});
 
-```typescript
-interface TableMeta {
-  name: string;
-  schema?: string;
-  columns: ColumnMeta[];
-  indexes: IndexMeta[];
-}
+// Generate date range query
+const dateQuery = generateDateQuery('created_at', {
+  startDate: new Date('2024-01-01'),
+  endDate: new Date('2024-12-31')
+});
+
+// Get API type from TypeORM column metadata
+const apiType = getApiTypeFromColumn(columnMetadata);
 ```
 
 ## Best Practices
 
-1. **Use Indexes Wisely**: Create appropriate indexes for query performance
-2. **Leverage JSONB**: Use JSONB for flexible schema requirements
-3. **Partition Large Tables**: Use table partitioning for time-series data
-4. **Full-Text Search**: Implement PostgreSQL full-text search for text queries
-5. **Connection Pooling**: Configure proper connection pooling
-6. **Migration Strategy**: Use structured migration classes
-7. **Monitor Performance**: Use PostgreSQL statistics for performance monitoring
-8. **Backup Strategy**: Implement regular backup procedures
-
-## Performance Optimization
-
-```typescript
-// Example of optimized queries
-const optimizedQuery = repository
-  .createQueryBuilder('user')
-  .select(['user.id', 'user.email']) // Select only needed columns
-  .where('user.isActive = :active', { active: true })
-  .andWhere('user.createdAt > :date', { date: cutoffDate })
-  .orderBy('user.createdAt', 'DESC')
-  .limit(100)
-  .getMany();
-
-// Use indexes for better performance
-@Index(['email']) // Single column index
-@Index(['isActive', 'createdAt']) // Composite index
-export class User {
-  // Entity definition
-}
-```
+1. **Repository Pattern**: Extend TypeOrmRepository for standard PostgreSQL operations
+2. **Redshift Operations**: Use RedshiftRepository for analytics workloads with specific optimizations
+3. **Pagination**: Implement TypeOrmPagingRepository for consistent pagination across your app
+4. **Migrations**: Use migration base classes for consistent schema management
+5. **SQL Generation**: Use SqlWriter for complex DDL operations
+6. **Transactions**: Use `forTransaction()` to create transaction-scoped repositories
+7. **Performance**: For Redshift bulk inserts, use `postOneWithoutReturn()` when you don't need the inserted record back
+8. **Type Safety**: Leverage the strongly-typed column metadata for compile-time safety
 
 ## Testing
 
 ```typescript
 import { Test } from '@nestjs/testing';
-import { getRepositoryToken } from '@nestjs/typeorm';
-import { Repository } from 'typeorm';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { EntityManager } from 'typeorm';
+import { UserRepository } from './user.repository';
 import { User } from './user.entity';
-import { UserService } from './user.service';
 
-describe('UserService', () => {
-  let service: UserService;
-  let repository: Repository<User>;
+describe('UserRepository', () => {
+  let repository: UserRepository;
+  let entityManager: EntityManager;
 
   beforeEach(async () => {
     const module = await Test.createTestingModule({
-      providers: [
-        UserService,
-        {
-          provide: getRepositoryToken(User),
-          useClass: Repository,
-        },
+      imports: [
+        TypeOrmModule.forRoot({
+          type: 'postgres',
+          host: 'localhost',
+          port: 5432,
+          username: 'test',
+          password: 'test',
+          database: 'test_db',
+          entities: [User],
+          synchronize: true,
+        }),
+        TypeOrmModule.forFeature([User])
       ],
+      providers: [UserRepository],
     }).compile();
 
-    service = module.get<UserService>(UserService);
-    repository = module.get<Repository<User>>(getRepositoryToken(User));
+    entityManager = module.get<EntityManager>(EntityManager);
+    repository = new UserRepository(entityManager);
   });
 
-  it('should perform full-text search', async () => {
-    const searchResults = await service.searchUsers('john doe');
-    expect(searchResults.data).toBeDefined();
-    expect(Array.isArray(searchResults.data)).toBe(true);
+  it('should create and retrieve user', async () => {
+    const userData = {
+      email: 'test@example.com',
+      firstName: 'John',
+      isActive: true
+    };
+
+    const user = await repository.postOne(userData);
+    expect(user.id).toBeDefined();
+    expect(user.email).toBe('test@example.com');
+
+    const foundUser = await repository.getOne({ where: { id: user.id } });
+    expect(foundUser).toEqual(user);
+  });
+
+  it('should handle transactions', async () => {
+    await entityManager.transaction(async (transactionalEntityManager) => {
+      const txRepository = repository.forTransaction(transactionalEntityManager);
+      
+      await txRepository.postOne({
+        email: 'tx@example.com',
+        firstName: 'Transaction',
+        isActive: true
+      });
+
+      // Transaction will be rolled back after test
+    });
   });
 });
 ```