drizzle-multitenant 1.0.5 → 1.0.6

package/.claude/settings.local.json

@@ -12,7 +12,9 @@
       "Bash(ls:*)",
       "Bash(npm run test:*)",
       "Bash(node ./dist/cli/index.js:*)",
-      "Bash(npx tsc:*)"
+      "Bash(npx tsc:*)",
+      "Bash(git filter-branch:*)",
+      "Bash(git add:*)"
     ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drizzle-multitenant",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "Multi-tenancy toolkit for Drizzle ORM with schema isolation, tenant context, and parallel migrations",
   "type": "module",
   "main": "./dist/index.js",

package/proposals/drizzle-kit-compatibility.md

@@ -1,499 +0,0 @@
-# Proposal: Drizzle-Kit Native Compatibility
-
-> **Status**: Proposal
-> **Priority**: P0 (Critical for Adoption)
-> **Effort**: 6-8 hours
-> **Date**: 2024-12-24
-
-## Problem Statement
-
-`drizzle-multitenant` currently cannot work with databases that have existing migrations applied via:
-1. **drizzle-kit migrate** (standard Drizzle ORM workflow)
-2. **Custom migration scripts** with different table structures
-
-When running `npx drizzle-multitenant status`, users see errors like:
-
-```
-column "name" does not exist
-```
-
-This happens because `drizzle-multitenant` expects a specific table structure that differs from what `drizzle-kit` and other tools create.
-
-## Migration Table Formats
-
-### 1. drizzle-multitenant (current)
-
-```sql
-CREATE TABLE "__drizzle_migrations" (
-  id SERIAL PRIMARY KEY,
-  name VARCHAR(255) NOT NULL UNIQUE,
-  applied_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
-);
-```
-
-**Tracking method**: Filename without extension (e.g., `0001_initial_schema`)
-
-### 2. drizzle-kit (standard Drizzle ORM)
-
-```sql
-CREATE TABLE "__drizzle_migrations" (
-  id SERIAL PRIMARY KEY,
-  hash TEXT NOT NULL,
-  created_at BIGINT NOT NULL
-);
-```
-
-**Tracking method**: SHA-256 hash of migration file content
-
-### 3. Custom Scripts (e.g., PrimeSys-v2 legacy)
-
-```sql
-CREATE TABLE "__drizzle_tenant_migrations" (
-  id SERIAL PRIMARY KEY,
-  hash TEXT NOT NULL,
-  created_at BIGINT NOT NULL
-);
-```
-
-**Tracking method**: SHA-256 hash (same as drizzle-kit, different table name)
-
-## Proposed Solution
-
-### 1. Auto-Detection of Table Format
-
-The migrator should automatically detect the existing table structure and adapt:
-
-```typescript
-// src/migrator/table-format.ts
-export type TableFormat = 'name' | 'hash' | 'drizzle-kit';
-
-export interface DetectedFormat {
-  format: TableFormat;
-  tableName: string;
-  columns: {
-    identifier: 'name' | 'hash';
-    timestamp: 'applied_at' | 'created_at';
-    timestampType: 'timestamp' | 'bigint';
-  };
-}
-
-export async function detectTableFormat(
-  pool: Pool,
-  schemaName: string,
-  tableName: string
-): Promise<DetectedFormat | null> {
-  // Check if table exists
-  const tableExists = await pool.query(`
-    SELECT 1 FROM information_schema.tables
-    WHERE table_schema = $1 AND table_name = $2
-  `, [schemaName, tableName]);
-
-  if (tableExists.rowCount === 0) return null;
-
-  // Check columns
-  const columns = await pool.query(`
-    SELECT column_name, data_type
-    FROM information_schema.columns
-    WHERE table_schema = $1 AND table_name = $2
-  `, [schemaName, tableName]);
-
-  const columnMap = new Map(columns.rows.map(r => [r.column_name, r.data_type]));
-
-  if (columnMap.has('name')) {
-    return {
-      format: 'name',
-      tableName,
-      columns: {
-        identifier: 'name',
-        timestamp: 'applied_at',
-        timestampType: 'timestamp',
-      },
-    };
-  }
-
-  if (columnMap.has('hash')) {
-    const timestampType = columnMap.get('created_at');
-    return {
-      format: timestampType === 'bigint' ? 'drizzle-kit' : 'hash',
-      tableName,
-      columns: {
-        identifier: 'hash',
-        timestamp: 'created_at',
-        timestampType: timestampType === 'bigint' ? 'bigint' : 'timestamp',
-      },
-    };
-  }
-
-  return null;
-}
-```
-
-### 2. Format-Aware Migration Tracking
-
-Update the `Migrator` class to work with any detected format:
-
-```typescript
-// src/migrator/migrator.ts
-
-interface MigrationIdentifier {
-  name: string;  // Filename without extension
-  hash: string;  // SHA-256 of content
-}
-
-private async getAppliedMigrations(
-  pool: Pool,
-  schemaName: string,
-  format: DetectedFormat
-): Promise<AppliedMigration[]> {
-  const identifierColumn = format.columns.identifier;
-  const timestampColumn = format.columns.timestamp;
-
-  const result = await pool.query(
-    `SELECT id, ${identifierColumn} as identifier, ${timestampColumn} as applied_at
-     FROM "${schemaName}"."${format.tableName}"
-     ORDER BY id`
-  );
-
-  return result.rows.map((row) => ({
-    id: row.id,
-    identifier: row.identifier,
-    appliedAt: format.columns.timestampType === 'bigint'
-      ? new Date(parseInt(row.applied_at))
-      : row.applied_at,
-  }));
-}
-
-private isMigrationApplied(
-  migration: MigrationFile,
-  appliedIdentifiers: Set<string>,
-  format: DetectedFormat
-): boolean {
-  if (format.columns.identifier === 'name') {
-    return appliedIdentifiers.has(migration.name);
-  }
-  // Hash-based: check both hash AND name for backwards compatibility
-  return appliedIdentifiers.has(migration.hash) ||
-         appliedIdentifiers.has(migration.name);
-}
-
-private async recordMigration(
-  pool: Pool,
-  schemaName: string,
-  migration: MigrationFile,
-  format: DetectedFormat
-): Promise<void> {
-  const identifierColumn = format.columns.identifier;
-  const timestampColumn = format.columns.timestamp;
-  const identifier = format.columns.identifier === 'name'
-    ? migration.name
-    : migration.hash;
-  const timestamp = format.columns.timestampType === 'bigint'
-    ? Date.now()
-    : new Date();
-
-  await pool.query(
-    `INSERT INTO "${schemaName}"."${format.tableName}"
-     (${identifierColumn}, ${timestampColumn}) VALUES ($1, $2)`,
-    [identifier, timestamp]
-  );
-}
-```
-
-### 3. Configuration Options
-
-Allow explicit format configuration with sensible defaults:
-
-```typescript
-// src/migrator/types.ts
-export interface MigratorConfig {
-  migrationsFolder: string;
-  tenantDiscovery: () => Promise<string[]>;
-
-  /**
-   * Migration table name
-   * @default "__drizzle_migrations"
-   */
-  migrationsTable?: string;
-
-  /**
-   * Table format for tracking migrations
-   * - "auto": Auto-detect existing format, use "name" for new tables
-   * - "name": Use filename (drizzle-multitenant native)
-   * - "hash": Use SHA-256 hash (drizzle-kit compatible)
-   * - "drizzle-kit": Exact drizzle-kit format (hash + bigint timestamp)
-   * @default "auto"
-   */
-  tableFormat?: 'auto' | 'name' | 'hash' | 'drizzle-kit';
-
-  /**
-   * When using "auto" format and no table exists, which format to create
-   * @default "name"
-   */
-  defaultFormat?: 'name' | 'hash' | 'drizzle-kit';
-
-  hooks?: MigratorHooks;
-}
-```
-
-### 4. Migration File Enhancement
-
-Add hash computation to migration files:
-
-```typescript
-// src/migrator/migrator.ts
-import { createHash } from 'node:crypto';
-
-private async loadMigrations(): Promise<MigrationFile[]> {
-  const files = await readdir(this.migratorConfig.migrationsFolder);
-  const migrations: MigrationFile[] = [];
-
-  for (const file of files) {
-    if (!file.endsWith('.sql')) continue;
-
-    const filePath = join(this.migratorConfig.migrationsFolder, file);
-    const content = await readFile(filePath, 'utf-8');
-
-    const match = file.match(/^(\d+)_/);
-    const timestamp = match?.[1] ? parseInt(match[1], 10) : 0;
-
-    migrations.push({
-      name: basename(file, '.sql'),
-      path: filePath,
-      sql: content,
-      timestamp,
-      hash: createHash('sha256').update(content).digest('hex'), // NEW
-    });
-  }
-
-  return migrations.sort((a, b) => a.timestamp - b.timestamp);
-}
-```
-
-### 5. CLI Updates
-
-Update status command to show format information:
-
-```bash
-$ npx drizzle-multitenant status -c tenant.config.ts
-
-Migration Status:
-┌──────────────────────────────────────┬──────────────────────┬────────┬─────────┬─────────┬──────────────┐
-│ Tenant                               │ Schema               │ Format │ Applied │ Pending │ Status       │
-├──────────────────────────────────────┼──────────────────────┼────────┼─────────┼─────────┼──────────────┤
-│ abc-123                              │ empresa_abc_123      │ hash   │ 45      │ 3       │ ✓ Behind     │
-│ def-456                              │ empresa_def_456      │ name   │ 48      │ 0       │ ✓ Up to date │
-│ ghi-789                              │ empresa_ghi_789      │ (new)  │ 0       │ 48      │ ○ New tenant │
-└──────────────────────────────────────┴──────────────────────┴────────┴─────────┴─────────┴──────────────┘
-```
-
-### 6. New CLI Command: `convert-format`
-
-For users who want to standardize on a single format:
-
-```bash
-# Preview conversion
-npx drizzle-multitenant convert-format --to=name --dry-run
-
-# Convert all tenants from hash to name format
-npx drizzle-multitenant convert-format --to=name
-
-# Convert specific tenant
-npx drizzle-multitenant convert-format --to=name --tenant=abc-123
-```
-
-Implementation:
-
-```typescript
-// src/cli/commands/convert-format.ts
-async function convertFormat(
-  pool: Pool,
-  schemaName: string,
-  tableName: string,
-  migrations: MigrationFile[],
-  targetFormat: 'name' | 'hash'
-): Promise<void> {
-  const migrationMap = new Map(
-    migrations.map(m => [m.hash, m.name])
-  );
-
-  // Read current records
-  const current = await pool.query(
-    `SELECT id, hash FROM "${schemaName}"."${tableName}" ORDER BY id`
-  );
-
-  await pool.query('BEGIN');
-
-  try {
-    // Add name column if converting to name format
-    if (targetFormat === 'name') {
-      await pool.query(`
-        ALTER TABLE "${schemaName}"."${tableName}"
-        ADD COLUMN IF NOT EXISTS name VARCHAR(255)
-      `);
-
-      // Populate name from hash using migration files
-      for (const row of current.rows) {
-        const name = migrationMap.get(row.hash);
-        if (name) {
-          await pool.query(
-            `UPDATE "${schemaName}"."${tableName}"
-             SET name = $1 WHERE id = $2`,
-            [name, row.id]
-          );
-        }
-      }
-
-      // Make name NOT NULL and add unique constraint
-      await pool.query(`
-        ALTER TABLE "${schemaName}"."${tableName}"
-        ALTER COLUMN name SET NOT NULL,
-        ADD CONSTRAINT ${tableName}_name_unique UNIQUE (name)
-      `);
-
-      // Optionally drop hash column
-      // await pool.query(`ALTER TABLE ... DROP COLUMN hash`);
-    }
-
-    await pool.query('COMMIT');
-  } catch (error) {
-    await pool.query('ROLLBACK');
-    throw error;
-  }
-}
-```
-
-## Implementation Plan
-
-### Phase 1: Detection & Read Compatibility (2 hours)
-
-1. Implement `detectTableFormat()` function
-2. Update `getAppliedMigrations()` to handle all formats
-3. Update `isMigrationApplied()` for hash-based comparison
-4. Update `getTenantStatus()` to show format in status
-
-### Phase 2: Write Compatibility (2 hours)
-
-1. Add hash computation to `loadMigrations()`
-2. Update `recordMigration()` to use detected format
-3. Update `ensureMigrationsTable()` to create correct format
-4. Add `tableFormat` config option
-
-### Phase 3: CLI Updates (2 hours)
-
-1. Update `status` command output
-2. Add `convert-format` command
-3. Update `--dry-run` to show format info
-4. Add format info to `migrate` command output
-
-### Phase 4: Testing & Documentation (2 hours)
-
-1. Unit tests for format detection
-2. Integration tests with all formats
-3. Update README with format documentation
-4. Add migration guide for existing users
-
-## Backwards Compatibility
-
-- **Existing drizzle-multitenant users**: No changes needed, default behavior preserved
-- **drizzle-kit users**: Works automatically with `tableFormat: "auto"` (default)
-- **Custom script users**: Set `tableFormat: "hash"` or let auto-detection handle it
-
-## Configuration Examples
-
-### New Project (drizzle-multitenant native)
-
-```typescript
-export default {
-  ...config,
-  migrations: {
-    tenantFolder: "./drizzle/tenant",
-    tenantDiscovery: discoverTenants,
-    // Uses default: tableFormat: "auto", defaultFormat: "name"
-  },
-};
-```
-
-### Migrating from drizzle-kit
-
-```typescript
-export default {
-  ...config,
-  migrations: {
-    tenantFolder: "./drizzle/tenant",
-    tenantDiscovery: discoverTenants,
-    migrationsTable: "__drizzle_migrations",
-    tableFormat: "auto", // Auto-detects drizzle-kit format
-  },
-};
-```
-
-### Explicit drizzle-kit Compatibility
-
-```typescript
-export default {
-  ...config,
-  migrations: {
-    tenantFolder: "./drizzle/tenant",
-    tenantDiscovery: discoverTenants,
-    migrationsTable: "__drizzle_migrations",
-    tableFormat: "drizzle-kit", // Forces drizzle-kit format
-  },
-};
-```
-
-### Legacy Custom Script
-
-```typescript
-export default {
-  ...config,
-  migrations: {
-    tenantFolder: "./drizzle/tenant",
-    tenantDiscovery: discoverTenants,
-    migrationsTable: "__drizzle_tenant_migrations", // Custom table name
-    tableFormat: "hash", // Uses hash-based tracking
-  },
-};
-```
-
-## Success Criteria
-
-1. `npx drizzle-multitenant status` works with existing drizzle-kit databases
-2. `npx drizzle-multitenant migrate` applies new migrations to drizzle-kit databases
-3. No data loss or duplicate migrations during format transition
-4. Clear error messages when format detection fails
-5. Documentation covers all migration scenarios
-
-## Related
-
-- [Improvements from PrimeSys](./improvements-from-primesys.md) - Section 3
-- [drizzle-multitenant Roadmap](../roadmap.md)
-- [Drizzle ORM Migrations Docs](https://orm.drizzle.team/docs/migrations)
-- [Drizzle Kit Migrate](https://orm.drizzle.team/docs/drizzle-kit-migrate)
-
-## Appendix: Table Structure Reference
-
-### drizzle-kit Internal Structure
-
-Based on Drizzle ORM source code, `drizzle-kit migrate` creates:
-
-```sql
-CREATE TABLE IF NOT EXISTS "__drizzle_migrations" (
-  id SERIAL PRIMARY KEY,
-  hash TEXT NOT NULL,
-  created_at BIGINT NOT NULL  -- Unix timestamp in milliseconds
-);
-```
-
-The hash is computed as SHA-256 of the migration file content, allowing drizzle-kit to detect if a migration file was modified after being applied.
-
-### Why Hash-Based Tracking?
-
-- **Content verification**: Detects if migration files were modified
-- **Idempotency**: Same content = same hash, prevents accidental re-runs
-- **drizzle-kit compatibility**: Matches drizzle-kit's internal behavior
-
-### Why Name-Based Tracking?
-
-- **Human readable**: Easy to see which migrations are applied
-- **Debug friendly**: `SELECT * FROM __drizzle_migrations` shows migration names
-- **Simpler**: No hash computation needed