drizzle-multitenant 1.0.8 → 1.0.10

package/dist/index.js

@@ -39,6 +39,26 @@ function validateConfig(config) {
   if (config.isolation.poolTtlMs !== void 0 && config.isolation.poolTtlMs < 0) {
     throw new Error("[drizzle-multitenant] isolation.poolTtlMs must be non-negative");
   }
+  if (config.connection.retry) {
+    const retry = config.connection.retry;
+    if (retry.maxAttempts !== void 0 && retry.maxAttempts < 1) {
+      throw new Error("[drizzle-multitenant] connection.retry.maxAttempts must be at least 1");
+    }
+    if (retry.initialDelayMs !== void 0 && retry.initialDelayMs < 0) {
+      throw new Error("[drizzle-multitenant] connection.retry.initialDelayMs must be non-negative");
+    }
+    if (retry.maxDelayMs !== void 0 && retry.maxDelayMs < 0) {
+      throw new Error("[drizzle-multitenant] connection.retry.maxDelayMs must be non-negative");
+    }
+    if (retry.backoffMultiplier !== void 0 && retry.backoffMultiplier < 1) {
+      throw new Error("[drizzle-multitenant] connection.retry.backoffMultiplier must be at least 1");
+    }
+    if (retry.initialDelayMs !== void 0 && retry.maxDelayMs !== void 0 && retry.initialDelayMs > retry.maxDelayMs) {
+      throw new Error(
+        "[drizzle-multitenant] connection.retry.initialDelayMs cannot be greater than maxDelayMs"
+      );
+    }
+  }
 }
 
 // src/types.ts
@@ -52,14 +72,270 @@ var DEFAULT_CONFIG = {
     max: 10,
     idleTimeoutMillis: 3e4,
     connectionTimeoutMillis: 5e3
+  },
+  retry: {
+    maxAttempts: 3,
+    initialDelayMs: 100,
+    maxDelayMs: 5e3,
+    backoffMultiplier: 2,
+    jitter: true
+  }
+};
+
+// src/debug.ts
+var PREFIX = "[drizzle-multitenant]";
+var DEFAULT_SLOW_QUERY_THRESHOLD = 1e3;
+var DebugLogger = class {
+  enabled;
+  logQueries;
+  logPoolEvents;
+  slowQueryThreshold;
+  logger;
+  constructor(config) {
+    this.enabled = config?.enabled ?? false;
+    this.logQueries = config?.logQueries ?? true;
+    this.logPoolEvents = config?.logPoolEvents ?? true;
+    this.slowQueryThreshold = config?.slowQueryThreshold ?? DEFAULT_SLOW_QUERY_THRESHOLD;
+    this.logger = config?.logger ?? this.defaultLogger;
+  }
+  /**
+   * Check if debug mode is enabled
+   */
+  isEnabled() {
+    return this.enabled;
+  }
+  /**
+   * Log a query execution
+   */
+  logQuery(tenantId, query, durationMs) {
+    if (!this.enabled || !this.logQueries) return;
+    const isSlowQuery = durationMs >= this.slowQueryThreshold;
+    const type = isSlowQuery ? "slow_query" : "query";
+    const context = {
+      type,
+      tenantId,
+      query: this.truncateQuery(query),
+      durationMs
+    };
+    if (isSlowQuery) {
+      this.logger(
+        `${PREFIX} tenant=${tenantId} SLOW_QUERY duration=${durationMs}ms query="${this.truncateQuery(query)}"`,
+        context
+      );
+    } else {
+      this.logger(
+        `${PREFIX} tenant=${tenantId} query="${this.truncateQuery(query)}" duration=${durationMs}ms`,
+        context
+      );
+    }
+  }
+  /**
+   * Log pool creation
+   */
+  logPoolCreated(tenantId, schemaName) {
+    if (!this.enabled || !this.logPoolEvents) return;
+    const context = {
+      type: "pool_created",
+      tenantId,
+      schemaName
+    };
+    this.logger(
+      `${PREFIX} tenant=${tenantId} POOL_CREATED schema=${schemaName}`,
+      context
+    );
+  }
+  /**
+   * Log pool eviction
+   */
+  logPoolEvicted(tenantId, schemaName, reason) {
+    if (!this.enabled || !this.logPoolEvents) return;
+    const context = {
+      type: "pool_evicted",
+      tenantId,
+      schemaName,
+      metadata: reason ? { reason } : void 0
+    };
+    const reasonStr = reason ? ` reason=${reason}` : "";
+    this.logger(
+      `${PREFIX} tenant=${tenantId} POOL_EVICTED schema=${schemaName}${reasonStr}`,
+      context
+    );
+  }
+  /**
+   * Log pool error
+   */
+  logPoolError(tenantId, error) {
+    if (!this.enabled || !this.logPoolEvents) return;
+    const context = {
+      type: "pool_error",
+      tenantId,
+      error: error.message
+    };
+    this.logger(
+      `${PREFIX} tenant=${tenantId} POOL_ERROR error="${error.message}"`,
+      context
+    );
+  }
+  /**
+   * Log warmup event
+   */
+  logWarmup(tenantId, success, durationMs, alreadyWarm) {
+    if (!this.enabled || !this.logPoolEvents) return;
+    const context = {
+      type: "warmup",
+      tenantId,
+      durationMs,
+      metadata: { success, alreadyWarm }
+    };
+    const status = alreadyWarm ? "already_warm" : success ? "success" : "failed";
+    this.logger(
+      `${PREFIX} tenant=${tenantId} WARMUP status=${status} duration=${durationMs}ms`,
+      context
+    );
+  }
+  /**
+   * Log connection retry event
+   */
+  logConnectionRetry(identifier, attempt, maxAttempts, error, delayMs) {
+    if (!this.enabled || !this.logPoolEvents) return;
+    const context = {
+      type: "connection_retry",
+      tenantId: identifier,
+      error: error.message,
+      metadata: { attempt, maxAttempts, delayMs }
+    };
+    this.logger(
+      `${PREFIX} tenant=${identifier} CONNECTION_RETRY attempt=${attempt}/${maxAttempts} delay=${delayMs}ms error="${error.message}"`,
+      context
+    );
+  }
+  /**
+   * Log connection success after retries
+   */
+  logConnectionSuccess(identifier, attempts, totalTimeMs) {
+    if (!this.enabled || !this.logPoolEvents) return;
+    const context = {
+      type: "pool_created",
+      tenantId: identifier,
+      durationMs: totalTimeMs,
+      metadata: { attempts }
+    };
+    if (attempts > 1) {
+      this.logger(
+        `${PREFIX} tenant=${identifier} CONNECTION_SUCCESS attempts=${attempts} totalTime=${totalTimeMs}ms`,
+        context
+      );
+    }
+  }
+  /**
+   * Log a custom debug message
+   */
+  log(message, context) {
+    if (!this.enabled) return;
+    this.logger(`${PREFIX} ${message}`, context);
+  }
+  /**
+   * Default logger implementation using console
+   */
+  defaultLogger(message, _context) {
+    console.log(message);
+  }
+  /**
+   * Truncate long queries for readability
+   */
+  truncateQuery(query, maxLength = 100) {
+    const normalized = query.replace(/\s+/g, " ").trim();
+    if (normalized.length <= maxLength) {
+      return normalized;
+    }
+    return normalized.substring(0, maxLength - 3) + "...";
   }
 };
+function createDebugLogger(config) {
+  return new DebugLogger(config);
+}
+
+// src/retry.ts
+function isRetryableError(error) {
+  const message = error.message.toLowerCase();
+  if (message.includes("econnrefused") || message.includes("econnreset") || message.includes("etimedout") || message.includes("enotfound") || message.includes("connection refused") || message.includes("connection reset") || message.includes("connection terminated") || message.includes("connection timed out") || message.includes("timeout expired") || message.includes("socket hang up")) {
+    return true;
+  }
+  if (message.includes("too many connections") || message.includes("sorry, too many clients") || message.includes("the database system is starting up") || message.includes("the database system is shutting down") || message.includes("server closed the connection unexpectedly") || message.includes("could not connect to server")) {
+    return true;
+  }
+  if (message.includes("ssl connection") || message.includes("ssl handshake")) {
+    return true;
+  }
+  return false;
+}
+function calculateDelay(attempt, config) {
+  const exponentialDelay = config.initialDelayMs * Math.pow(config.backoffMultiplier, attempt);
+  const cappedDelay = Math.min(exponentialDelay, config.maxDelayMs);
+  if (config.jitter) {
+    const jitterFactor = 1 + Math.random() * 0.25;
+    return Math.floor(cappedDelay * jitterFactor);
+  }
+  return Math.floor(cappedDelay);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function withRetry(operation, config) {
+  const retryConfig = {
+    maxAttempts: config?.maxAttempts ?? DEFAULT_CONFIG.retry.maxAttempts,
+    initialDelayMs: config?.initialDelayMs ?? DEFAULT_CONFIG.retry.initialDelayMs,
+    maxDelayMs: config?.maxDelayMs ?? DEFAULT_CONFIG.retry.maxDelayMs,
+    backoffMultiplier: config?.backoffMultiplier ?? DEFAULT_CONFIG.retry.backoffMultiplier,
+    jitter: config?.jitter ?? DEFAULT_CONFIG.retry.jitter,
+    isRetryable: config?.isRetryable ?? isRetryableError,
+    onRetry: config?.onRetry
+  };
+  const startTime = Date.now();
+  let lastError = null;
+  for (let attempt = 0; attempt < retryConfig.maxAttempts; attempt++) {
+    try {
+      const result = await operation();
+      return {
+        result,
+        attempts: attempt + 1,
+        totalTimeMs: Date.now() - startTime
+      };
+    } catch (error) {
+      lastError = error;
+      const isLastAttempt = attempt >= retryConfig.maxAttempts - 1;
+      if (isLastAttempt || !retryConfig.isRetryable(lastError)) {
+        throw lastError;
+      }
+      const delay = calculateDelay(attempt, retryConfig);
+      retryConfig.onRetry?.(attempt + 1, lastError, delay);
+      await sleep(delay);
+    }
+  }
+  throw lastError ?? new Error("Retry failed with no error");
+}
+function createRetrier(config) {
+  return (operation) => {
+    return withRetry(operation, config);
+  };
+}
 
 // src/pool.ts
 var PoolManager = class {
   constructor(config) {
     this.config = config;
     const maxPools = config.isolation.maxPools ?? DEFAULT_CONFIG.maxPools;
+    this.debugLogger = createDebugLogger(config.debug);
+    const userRetry = config.connection.retry ?? {};
+    this.retryConfig = {
+      maxAttempts: userRetry.maxAttempts ?? DEFAULT_CONFIG.retry.maxAttempts,
+      initialDelayMs: userRetry.initialDelayMs ?? DEFAULT_CONFIG.retry.initialDelayMs,
+      maxDelayMs: userRetry.maxDelayMs ?? DEFAULT_CONFIG.retry.maxDelayMs,
+      backoffMultiplier: userRetry.backoffMultiplier ?? DEFAULT_CONFIG.retry.backoffMultiplier,
+      jitter: userRetry.jitter ?? DEFAULT_CONFIG.retry.jitter,
+      isRetryable: userRetry.isRetryable ?? isRetryableError,
+      onRetry: userRetry.onRetry
+    };
     this.pools = new LRUCache({
       max: maxPools,
       dispose: (entry, key) => {
@@ -70,10 +346,14 @@ var PoolManager = class {
   }
   pools;
   tenantIdBySchema = /* @__PURE__ */ new Map();
+  pendingConnections = /* @__PURE__ */ new Map();
   sharedPool = null;
   sharedDb = null;
+  sharedDbPending = null;
   cleanupInterval = null;
   disposed = false;
+  debugLogger;
+  retryConfig;
   /**
    * Get or create a database connection for a tenant
    */
@@ -85,11 +365,85 @@ var PoolManager = class {
       entry = this.createPoolEntry(tenantId, schemaName);
       this.pools.set(schemaName, entry);
       this.tenantIdBySchema.set(schemaName, tenantId);
+      this.debugLogger.logPoolCreated(tenantId, schemaName);
       void this.config.hooks?.onPoolCreated?.(tenantId);
     }
     entry.lastAccess = Date.now();
     return entry.db;
   }
+  /**
+   * Get or create a database connection for a tenant with retry and validation
+   *
+   * This async version validates the connection by executing a ping query
+   * and retries on transient failures with exponential backoff.
+   *
+   * @example
+   * ```typescript
+   * // Get tenant database with automatic retry
+   * const db = await manager.getDbAsync('tenant-123');
+   *
+   * // Queries will use the validated connection
+   * const users = await db.select().from(users);
+   * ```
+   */
+  async getDbAsync(tenantId) {
+    this.ensureNotDisposed();
+    const schemaName = this.config.isolation.schemaNameTemplate(tenantId);
+    let entry = this.pools.get(schemaName);
+    if (entry) {
+      entry.lastAccess = Date.now();
+      return entry.db;
+    }
+    const pending = this.pendingConnections.get(schemaName);
+    if (pending) {
+      entry = await pending;
+      entry.lastAccess = Date.now();
+      return entry.db;
+    }
+    const connectionPromise = this.connectWithRetry(tenantId, schemaName);
+    this.pendingConnections.set(schemaName, connectionPromise);
+    try {
+      entry = await connectionPromise;
+      this.pools.set(schemaName, entry);
+      this.tenantIdBySchema.set(schemaName, tenantId);
+      this.debugLogger.logPoolCreated(tenantId, schemaName);
+      void this.config.hooks?.onPoolCreated?.(tenantId);
+      entry.lastAccess = Date.now();
+      return entry.db;
+    } finally {
+      this.pendingConnections.delete(schemaName);
+    }
+  }
+  /**
+   * Connect to a tenant database with retry logic
+   */
+  async connectWithRetry(tenantId, schemaName) {
+    const maxAttempts = this.retryConfig.maxAttempts;
+    const result = await withRetry(
+      async () => {
+        const entry = this.createPoolEntry(tenantId, schemaName);
+        try {
+          await entry.pool.query("SELECT 1");
+          return entry;
+        } catch (error) {
+          try {
+            await entry.pool.end();
+          } catch {
+          }
+          throw error;
+        }
+      },
+      {
+        ...this.retryConfig,
+        onRetry: (attempt, error, delayMs) => {
+          this.debugLogger.logConnectionRetry(tenantId, attempt, maxAttempts, error, delayMs);
+          this.retryConfig.onRetry?.(attempt, error, delayMs);
+        }
+      }
+    );
+    this.debugLogger.logConnectionSuccess(tenantId, result.attempts, result.totalTimeMs);
+    return result.result;
+  }
   /**
    * Get or create the shared database connection
    */
@@ -110,6 +464,78 @@ var PoolManager = class {
     }
     return this.sharedDb;
   }
+  /**
+   * Get or create the shared database connection with retry and validation
+   *
+   * This async version validates the connection by executing a ping query
+   * and retries on transient failures with exponential backoff.
+   *
+   * @example
+   * ```typescript
+   * // Get shared database with automatic retry
+   * const sharedDb = await manager.getSharedDbAsync();
+   *
+   * // Queries will use the validated connection
+   * const plans = await sharedDb.select().from(plans);
+   * ```
+   */
+  async getSharedDbAsync() {
+    this.ensureNotDisposed();
+    if (this.sharedDb) {
+      return this.sharedDb;
+    }
+    if (this.sharedDbPending) {
+      return this.sharedDbPending;
+    }
+    this.sharedDbPending = this.connectSharedWithRetry();
+    try {
+      const db = await this.sharedDbPending;
+      return db;
+    } finally {
+      this.sharedDbPending = null;
+    }
+  }
+  /**
+   * Connect to shared database with retry logic
+   */
+  async connectSharedWithRetry() {
+    const maxAttempts = this.retryConfig.maxAttempts;
+    const result = await withRetry(
+      async () => {
+        const pool = new Pool({
+          connectionString: this.config.connection.url,
+          ...DEFAULT_CONFIG.poolConfig,
+          ...this.config.connection.poolConfig
+        });
+        try {
+          await pool.query("SELECT 1");
+          pool.on("error", (err) => {
+            void this.config.hooks?.onError?.("shared", err);
+          });
+          this.sharedPool = pool;
+          this.sharedDb = drizzle(pool, {
+            schema: this.config.schemas.shared
+          });
+          return this.sharedDb;
+        } catch (error) {
+          try {
+            await pool.end();
+          } catch {
+          }
+          throw error;
+        }
+      },
+      {
+        ...this.retryConfig,
+        onRetry: (attempt, error, delayMs) => {
+          this.debugLogger.logConnectionRetry("shared", attempt, maxAttempts, error, delayMs);
+          this.retryConfig.onRetry?.(attempt, error, delayMs);
+        }
+      }
+    );
+    this.debugLogger.logConnectionSuccess("shared", result.attempts, result.totalTimeMs);
+    return result.result;
+  }
   /**
    * Get schema name for a tenant
    */
@@ -135,13 +561,77 @@ var PoolManager = class {
   getActiveTenantIds() {
     return Array.from(this.tenantIdBySchema.values());
   }
+  /**
+   * Get the retry configuration
+   */
+  getRetryConfig() {
+    return { ...this.retryConfig };
+  }
+  /**
+   * Pre-warm pools for specified tenants to reduce cold start latency
+   *
+   * Uses automatic retry with exponential backoff for connection failures.
+   */
+  async warmup(tenantIds, options = {}) {
+    this.ensureNotDisposed();
+    const startTime = Date.now();
+    const { concurrency = 10, ping = true, onProgress } = options;
+    const results = [];
+    for (let i = 0; i < tenantIds.length; i += concurrency) {
+      const batch = tenantIds.slice(i, i + concurrency);
+      const batchResults = await Promise.all(
+        batch.map(async (tenantId) => {
+          const tenantStart = Date.now();
+          onProgress?.(tenantId, "starting");
+          try {
+            const alreadyWarm = this.hasPool(tenantId);
+            if (ping) {
+              await this.getDbAsync(tenantId);
+            } else {
+              this.getDb(tenantId);
+            }
+            const durationMs = Date.now() - tenantStart;
+            onProgress?.(tenantId, "completed");
+            this.debugLogger.logWarmup(tenantId, true, durationMs, alreadyWarm);
+            return {
+              tenantId,
+              success: true,
+              alreadyWarm,
+              durationMs
+            };
+          } catch (error) {
+            const durationMs = Date.now() - tenantStart;
+            onProgress?.(tenantId, "failed");
+            this.debugLogger.logWarmup(tenantId, false, durationMs, false);
+            return {
+              tenantId,
+              success: false,
+              alreadyWarm: false,
+              durationMs,
+              error: error.message
+            };
+          }
+        })
+      );
+      results.push(...batchResults);
+    }
+    return {
+      total: results.length,
+      succeeded: results.filter((r) => r.success).length,
+      failed: results.filter((r) => !r.success).length,
+      alreadyWarm: results.filter((r) => r.alreadyWarm).length,
+      durationMs: Date.now() - startTime,
+      details: results
+    };
+  }
   /**
    * Manually evict a tenant pool
    */
-  async evictPool(tenantId) {
+  async evictPool(tenantId, reason = "manual") {
     const schemaName = this.config.isolation.schemaNameTemplate(tenantId);
     const entry = this.pools.get(schemaName);
     if (entry) {
+      this.debugLogger.logPoolEvicted(tenantId, schemaName, reason);
       this.pools.delete(schemaName);
       this.tenantIdBySchema.delete(schemaName);
       await this.closePool(entry.pool, tenantId);
@@ -200,8 +690,9 @@ var PoolManager = class {
       options: `-c search_path=${schemaName},public`
     });
     pool.on("error", async (err) => {
+      this.debugLogger.logPoolError(tenantId, err);
       void this.config.hooks?.onError?.(tenantId, err);
-      await this.evictPool(tenantId);
+      await this.evictPool(tenantId, "error");
     });
     const db = drizzle(pool, {
       schema: this.config.schemas.tenant
@@ -219,6 +710,9 @@ var PoolManager = class {
   disposePoolEntry(entry, schemaName) {
     const tenantId = this.tenantIdBySchema.get(schemaName);
     this.tenantIdBySchema.delete(schemaName);
+    if (tenantId) {
+      this.debugLogger.logPoolEvicted(tenantId, schemaName, "lru_eviction");
+    }
     void this.closePool(entry.pool, tenantId ?? schemaName).then(() => {
       if (tenantId) {
         void this.config.hooks?.onPoolEvicted?.(tenantId);
@@ -249,7 +743,7 @@ var PoolManager = class {
     for (const schemaName of toEvict) {
       const tenantId = this.tenantIdBySchema.get(schemaName);
       if (tenantId) {
-        await this.evictPool(tenantId);
+        await this.evictPool(tenantId, "ttl_expired");
       }
     }
   }
@@ -271,9 +765,15 @@ function createTenantManager(config) {
     getDb(tenantId) {
       return poolManager.getDb(tenantId);
     },
+    async getDbAsync(tenantId) {
+      return poolManager.getDbAsync(tenantId);
+    },
     getSharedDb() {
       return poolManager.getSharedDb();
     },
+    async getSharedDbAsync() {
+      return poolManager.getSharedDbAsync();
+    },
     getSchemaName(tenantId) {
       return poolManager.getSchemaName(tenantId);
     },
@@ -286,9 +786,15 @@ function createTenantManager(config) {
     getActiveTenantIds() {
       return poolManager.getActiveTenantIds();
     },
+    getRetryConfig() {
+      return poolManager.getRetryConfig();
+    },
     async evictPool(tenantId) {
       await poolManager.evictPool(tenantId);
     },
+    async warmup(tenantIds, options) {
+      return poolManager.warmup(tenantIds, options);
+    },
     async dispose() {
       await poolManager.dispose();
     }
@@ -696,57 +1202,423 @@ var Migrator = class {
     }
   }
   /**
-   * Load migration files from the migrations folder
+   * Mark migrations as applied without executing SQL
+   * Useful for syncing tracking state with already-applied migrations
    */
-  async loadMigrations() {
-    const files = await readdir(this.migratorConfig.migrationsFolder);
-    const migrations = [];
-    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;
-      const hash = createHash("sha256").update(content).digest("hex");
-      migrations.push({
-        name: basename(file, ".sql"),
-        path: filePath,
-        sql: content,
-        timestamp,
-        hash
-      });
+  async markAsApplied(tenantId, options = {}) {
+    const startTime = Date.now();
+    const schemaName = this.tenantConfig.isolation.schemaNameTemplate(tenantId);
+    const markedMigrations = [];
+    const pool = await this.createPool(schemaName);
+    try {
+      await this.migratorConfig.hooks?.beforeTenant?.(tenantId);
+      const format = await this.getOrDetectFormat(pool, schemaName);
+      await this.ensureMigrationsTable(pool, schemaName, format);
+      const allMigrations = await this.loadMigrations();
+      const applied = await this.getAppliedMigrations(pool, schemaName, format);
+      const appliedSet = new Set(applied.map((m) => m.identifier));
+      const pending = allMigrations.filter(
+        (m) => !this.isMigrationApplied(m, appliedSet, format)
+      );
+      for (const migration of pending) {
+        const migrationStart = Date.now();
+        options.onProgress?.(tenantId, "migrating", migration.name);
+        await this.migratorConfig.hooks?.beforeMigration?.(tenantId, migration.name);
+        await this.recordMigration(pool, schemaName, migration, format);
+        await this.migratorConfig.hooks?.afterMigration?.(
+          tenantId,
+          migration.name,
+          Date.now() - migrationStart
+        );
+        markedMigrations.push(migration.name);
+      }
+      const result = {
+        tenantId,
+        schemaName,
+        success: true,
+        appliedMigrations: markedMigrations,
+        durationMs: Date.now() - startTime,
+        format: format.format
+      };
+      await this.migratorConfig.hooks?.afterTenant?.(tenantId, result);
+      return result;
+    } catch (error) {
+      const result = {
+        tenantId,
+        schemaName,
+        success: false,
+        appliedMigrations: markedMigrations,
+        error: error.message,
+        durationMs: Date.now() - startTime
+      };
+      await this.migratorConfig.hooks?.afterTenant?.(tenantId, result);
+      return result;
+    } finally {
+      await pool.end();
     }
-    return migrations.sort((a, b) => a.timestamp - b.timestamp);
-  }
-  /**
-   * Create a pool for a specific schema
-   */
-  async createPool(schemaName) {
-    return new Pool({
-      connectionString: this.tenantConfig.connection.url,
-      ...this.tenantConfig.connection.poolConfig,
-      options: `-c search_path="${schemaName}",public`
-    });
-  }
-  /**
-   * Ensure migrations table exists with the correct format
-   */
-  async ensureMigrationsTable(pool, schemaName, format) {
-    const { identifier, timestamp, timestampType } = format.columns;
-    const identifierCol = identifier === "name" ? "name VARCHAR(255) NOT NULL UNIQUE" : "hash TEXT NOT NULL";
-    const timestampCol = timestampType === "bigint" ? `${timestamp} BIGINT NOT NULL` : `${timestamp} TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP`;
-    await pool.query(`
-      CREATE TABLE IF NOT EXISTS "${schemaName}"."${format.tableName}" (
-        id SERIAL PRIMARY KEY,
-        ${identifierCol},
-        ${timestampCol}
-      )
-    `);
   }
   /**
-   * Check if migrations table exists
+   * Mark migrations as applied for all tenants without executing SQL
+   * Useful for syncing tracking state with already-applied migrations
    */
-  async migrationsTableExists(pool, schemaName) {
+  async markAllAsApplied(options = {}) {
+    const {
+      concurrency = 10,
+      onProgress,
+      onError
+    } = options;
+    const tenantIds = await this.migratorConfig.tenantDiscovery();
+    const results = [];
+    let aborted = false;
+    for (let i = 0; i < tenantIds.length && !aborted; i += concurrency) {
+      const batch = tenantIds.slice(i, i + concurrency);
+      const batchResults = await Promise.all(
+        batch.map(async (tenantId) => {
+          if (aborted) {
+            return this.createSkippedResult(tenantId);
+          }
+          try {
+            onProgress?.(tenantId, "starting");
+            const result = await this.markAsApplied(tenantId, { onProgress });
+            onProgress?.(tenantId, result.success ? "completed" : "failed");
+            return result;
+          } catch (error) {
+            onProgress?.(tenantId, "failed");
+            const action = onError?.(tenantId, error);
+            if (action === "abort") {
+              aborted = true;
+            }
+            return this.createErrorResult(tenantId, error);
+          }
+        })
+      );
+      results.push(...batchResults);
+    }
+    if (aborted) {
+      const remaining = tenantIds.slice(results.length);
+      for (const tenantId of remaining) {
+        results.push(this.createSkippedResult(tenantId));
+      }
+    }
+    return this.aggregateResults(results);
+  }
+  /**
+   * Get sync status for all tenants
+   * Detects divergences between migrations on disk and tracking in database
+   */
+  async getSyncStatus() {
+    const tenantIds = await this.migratorConfig.tenantDiscovery();
+    const migrations = await this.loadMigrations();
+    const statuses = [];
+    for (const tenantId of tenantIds) {
+      statuses.push(await this.getTenantSyncStatus(tenantId, migrations));
+    }
+    return {
+      total: statuses.length,
+      inSync: statuses.filter((s) => s.inSync && !s.error).length,
+      outOfSync: statuses.filter((s) => !s.inSync && !s.error).length,
+      error: statuses.filter((s) => !!s.error).length,
+      details: statuses
+    };
+  }
+  /**
+   * Get sync status for a specific tenant
+   */
+  async getTenantSyncStatus(tenantId, migrations) {
+    const schemaName = this.tenantConfig.isolation.schemaNameTemplate(tenantId);
+    const pool = await this.createPool(schemaName);
+    try {
+      const allMigrations = migrations ?? await this.loadMigrations();
+      const migrationNames = new Set(allMigrations.map((m) => m.name));
+      const migrationHashes = new Set(allMigrations.map((m) => m.hash));
+      const tableExists = await this.migrationsTableExists(pool, schemaName);
+      if (!tableExists) {
+        return {
+          tenantId,
+          schemaName,
+          missing: allMigrations.map((m) => m.name),
+          orphans: [],
+          inSync: allMigrations.length === 0,
+          format: null
+        };
+      }
+      const format = await this.getOrDetectFormat(pool, schemaName);
+      const applied = await this.getAppliedMigrations(pool, schemaName, format);
+      const appliedIdentifiers = new Set(applied.map((m) => m.identifier));
+      const missing = allMigrations.filter((m) => !this.isMigrationApplied(m, appliedIdentifiers, format)).map((m) => m.name);
+      const orphans = applied.filter((m) => {
+        if (format.columns.identifier === "name") {
+          return !migrationNames.has(m.identifier);
+        }
+        return !migrationHashes.has(m.identifier) && !migrationNames.has(m.identifier);
+      }).map((m) => m.identifier);
+      return {
+        tenantId,
+        schemaName,
+        missing,
+        orphans,
+        inSync: missing.length === 0 && orphans.length === 0,
+        format: format.format
+      };
+    } catch (error) {
+      return {
+        tenantId,
+        schemaName,
+        missing: [],
+        orphans: [],
+        inSync: false,
+        format: null,
+        error: error.message
+      };
+    } finally {
+      await pool.end();
+    }
+  }
+  /**
+   * Mark missing migrations as applied for a tenant
+   */
+  async markMissing(tenantId) {
+    const startTime = Date.now();
+    const schemaName = this.tenantConfig.isolation.schemaNameTemplate(tenantId);
+    const markedMigrations = [];
+    const pool = await this.createPool(schemaName);
+    try {
+      const syncStatus = await this.getTenantSyncStatus(tenantId);
+      if (syncStatus.error) {
+        return {
+          tenantId,
+          schemaName,
+          success: false,
+          markedMigrations: [],
+          removedOrphans: [],
+          error: syncStatus.error,
+          durationMs: Date.now() - startTime
+        };
+      }
+      if (syncStatus.missing.length === 0) {
+        return {
+          tenantId,
+          schemaName,
+          success: true,
+          markedMigrations: [],
+          removedOrphans: [],
+          durationMs: Date.now() - startTime
+        };
+      }
+      const format = await this.getOrDetectFormat(pool, schemaName);
+      await this.ensureMigrationsTable(pool, schemaName, format);
+      const allMigrations = await this.loadMigrations();
+      const missingSet = new Set(syncStatus.missing);
+      for (const migration of allMigrations) {
+        if (missingSet.has(migration.name)) {
+          await this.recordMigration(pool, schemaName, migration, format);
+          markedMigrations.push(migration.name);
+        }
+      }
+      return {
+        tenantId,
+        schemaName,
+        success: true,
+        markedMigrations,
+        removedOrphans: [],
+        durationMs: Date.now() - startTime
+      };
+    } catch (error) {
+      return {
+        tenantId,
+        schemaName,
+        success: false,
+        markedMigrations,
+        removedOrphans: [],
+        error: error.message,
+        durationMs: Date.now() - startTime
+      };
+    } finally {
+      await pool.end();
+    }
+  }
+  /**
+   * Mark missing migrations as applied for all tenants
+   */
+  async markAllMissing(options = {}) {
+    const { concurrency = 10, onProgress, onError } = options;
+    const tenantIds = await this.migratorConfig.tenantDiscovery();
+    const results = [];
+    let aborted = false;
+    for (let i = 0; i < tenantIds.length && !aborted; i += concurrency) {
+      const batch = tenantIds.slice(i, i + concurrency);
+      const batchResults = await Promise.all(
+        batch.map(async (tenantId) => {
+          if (aborted) {
+            return this.createSkippedSyncResult(tenantId);
+          }
+          try {
+            onProgress?.(tenantId, "starting");
+            const result = await this.markMissing(tenantId);
+            onProgress?.(tenantId, result.success ? "completed" : "failed");
+            return result;
+          } catch (error) {
+            onProgress?.(tenantId, "failed");
+            const action = onError?.(tenantId, error);
+            if (action === "abort") {
+              aborted = true;
+            }
+            return this.createErrorSyncResult(tenantId, error);
+          }
+        })
+      );
+      results.push(...batchResults);
+    }
+    return this.aggregateSyncResults(results);
+  }
+  /**
+   * Remove orphan migration records for a tenant
+   */
+  async cleanOrphans(tenantId) {
+    const startTime = Date.now();
+    const schemaName = this.tenantConfig.isolation.schemaNameTemplate(tenantId);
+    const removedOrphans = [];
+    const pool = await this.createPool(schemaName);
+    try {
+      const syncStatus = await this.getTenantSyncStatus(tenantId);
+      if (syncStatus.error) {
+        return {
+          tenantId,
+          schemaName,
+          success: false,
+          markedMigrations: [],
+          removedOrphans: [],
+          error: syncStatus.error,
+          durationMs: Date.now() - startTime
+        };
+      }
+      if (syncStatus.orphans.length === 0) {
+        return {
+          tenantId,
+          schemaName,
+          success: true,
+          markedMigrations: [],
+          removedOrphans: [],
+          durationMs: Date.now() - startTime
+        };
+      }
+      const format = await this.getOrDetectFormat(pool, schemaName);
+      const identifierColumn = format.columns.identifier;
+      for (const orphan of syncStatus.orphans) {
+        await pool.query(
+          `DELETE FROM "${schemaName}"."${format.tableName}" WHERE "${identifierColumn}" = $1`,
+          [orphan]
+        );
+        removedOrphans.push(orphan);
+      }
+      return {
+        tenantId,
+        schemaName,
+        success: true,
+        markedMigrations: [],
+        removedOrphans,
+        durationMs: Date.now() - startTime
+      };
+    } catch (error) {
+      return {
+        tenantId,
+        schemaName,
+        success: false,
+        markedMigrations: [],
+        removedOrphans,
+        error: error.message,
+        durationMs: Date.now() - startTime
+      };
+    } finally {
+      await pool.end();
+    }
+  }
+  /**
+   * Remove orphan migration records for all tenants
+   */
+  async cleanAllOrphans(options = {}) {
+    const { concurrency = 10, onProgress, onError } = options;
+    const tenantIds = await this.migratorConfig.tenantDiscovery();
+    const results = [];
+    let aborted = false;
+    for (let i = 0; i < tenantIds.length && !aborted; i += concurrency) {
+      const batch = tenantIds.slice(i, i + concurrency);
+      const batchResults = await Promise.all(
+        batch.map(async (tenantId) => {
+          if (aborted) {
+            return this.createSkippedSyncResult(tenantId);
+          }
+          try {
+            onProgress?.(tenantId, "starting");
+            const result = await this.cleanOrphans(tenantId);
+            onProgress?.(tenantId, result.success ? "completed" : "failed");
+            return result;
+          } catch (error) {
+            onProgress?.(tenantId, "failed");
+            const action = onError?.(tenantId, error);
+            if (action === "abort") {
+              aborted = true;
+            }
+            return this.createErrorSyncResult(tenantId, error);
+          }
+        })
+      );
+      results.push(...batchResults);
+    }
+    return this.aggregateSyncResults(results);
+  }
+  /**
+   * Load migration files from the migrations folder
+   */
+  async loadMigrations() {
+    const files = await readdir(this.migratorConfig.migrationsFolder);
+    const migrations = [];
+    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;
+      const hash = createHash("sha256").update(content).digest("hex");
+      migrations.push({
+        name: basename(file, ".sql"),
+        path: filePath,
+        sql: content,
+        timestamp,
+        hash
+      });
+    }
+    return migrations.sort((a, b) => a.timestamp - b.timestamp);
+  }
+  /**
+   * Create a pool for a specific schema
+   */
+  async createPool(schemaName) {
+    return new Pool({
+      connectionString: this.tenantConfig.connection.url,
+      ...this.tenantConfig.connection.poolConfig,
+      options: `-c search_path="${schemaName}",public`
+    });
+  }
+  /**
+   * Ensure migrations table exists with the correct format
+   */
+  async ensureMigrationsTable(pool, schemaName, format) {
+    const { identifier, timestamp, timestampType } = format.columns;
+    const identifierCol = identifier === "name" ? "name VARCHAR(255) NOT NULL UNIQUE" : "hash TEXT NOT NULL";
+    const timestampCol = timestampType === "bigint" ? `${timestamp} BIGINT NOT NULL` : `${timestamp} TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP`;
+    await pool.query(`
+      CREATE TABLE IF NOT EXISTS "${schemaName}"."${format.tableName}" (
+        id SERIAL PRIMARY KEY,
+        ${identifierCol},
+        ${timestampCol}
+      )
+    `);
+  }
+  /**
+   * Check if migrations table exists
+   */
+  async migrationsTableExists(pool, schemaName) {
     const result = await pool.query(
       `SELECT 1 FROM information_schema.tables
        WHERE table_schema = $1 AND table_name = $2`,
@@ -824,6 +1696,19 @@ var Migrator = class {
       client.release();
     }
   }
+  /**
+   * Record a migration as applied without executing SQL
+   * Used by markAsApplied to sync tracking state
+   */
+  async recordMigration(pool, schemaName, migration, format) {
+    const { identifier, timestamp, timestampType } = format.columns;
+    const identifierValue = identifier === "name" ? migration.name : migration.hash;
+    const timestampValue = timestampType === "bigint" ? Date.now() : /* @__PURE__ */ new Date();
+    await pool.query(
+      `INSERT INTO "${schemaName}"."${format.tableName}" ("${identifier}", "${timestamp}") VALUES ($1, $2)`,
+      [identifierValue, timestampValue]
+    );
+  }
   /**
    * Create a skipped result
    */
@@ -862,6 +1747,45 @@ var Migrator = class {
       details: results
     };
   }
+  /**
+   * Create a skipped sync result
+   */
+  createSkippedSyncResult(tenantId) {
+    return {
+      tenantId,
+      schemaName: this.tenantConfig.isolation.schemaNameTemplate(tenantId),
+      success: false,
+      markedMigrations: [],
+      removedOrphans: [],
+      error: "Skipped due to abort",
+      durationMs: 0
+    };
+  }
+  /**
+   * Create an error sync result
+   */
+  createErrorSyncResult(tenantId, error) {
+    return {
+      tenantId,
+      schemaName: this.tenantConfig.isolation.schemaNameTemplate(tenantId),
+      success: false,
+      markedMigrations: [],
+      removedOrphans: [],
+      error: error.message,
+      durationMs: 0
+    };
+  }
+  /**
+   * Aggregate sync results
+   */
+  aggregateSyncResults(results) {
+    return {
+      total: results.length,
+      succeeded: results.filter((r) => r.success).length,
+      failed: results.filter((r) => !r.success).length,
+      details: results
+    };
+  }
 };
 function createMigrator(tenantConfig, migratorConfig) {
   return new Migrator(tenantConfig, migratorConfig);
@@ -1078,7 +2002,214 @@ function buildCrossSchemaSelect(fields, tenantSchema, _sharedSchema) {
   };
   return { columns, getSchema };
 }
+function extractTablesFromSchema(schema) {
+  const tables = /* @__PURE__ */ new Set();
+  for (const value of Object.values(schema)) {
+    if (value && typeof value === "object" && "_" in value) {
+      const branded = value;
+      if (branded._?.brand === "Table") {
+        tables.add(value);
+      }
+    }
+  }
+  return tables;
+}
+function isSharedTable(table, sharedTables) {
+  return sharedTables.has(table);
+}
+var WithSharedQueryBuilder = class {
+  constructor(tenantDb, sharedTables, tenantSchemaName, sharedSchemaName = "public") {
+    this.tenantDb = tenantDb;
+    this.sharedTables = sharedTables;
+    this.tenantSchemaName = tenantSchemaName;
+    this.sharedSchemaName = sharedSchemaName;
+  }
+  fromTable = null;
+  joins = [];
+  selectFields = {};
+  whereCondition = null;
+  orderByFields = [];
+  limitValue = null;
+  offsetValue = null;
+  /**
+   * Set the main table to query from
+   * Automatically detects if it's a tenant or shared table
+   */
+  from(table) {
+    const isShared = isSharedTable(table, this.sharedTables);
+    this.fromTable = {
+      table,
+      isShared,
+      schemaName: isShared ? this.sharedSchemaName : this.tenantSchemaName
+    };
+    return this;
+  }
+  /**
+   * Add a left join with automatic schema detection
+   */
+  leftJoin(table, condition) {
+    return this.addJoin(table, condition, "left");
+  }
+  /**
+   * Add an inner join with automatic schema detection
+   */
+  innerJoin(table, condition) {
+    return this.addJoin(table, condition, "inner");
+  }
+  /**
+   * Add a right join with automatic schema detection
+   */
+  rightJoin(table, condition) {
+    return this.addJoin(table, condition, "right");
+  }
+  /**
+   * Add a full outer join with automatic schema detection
+   */
+  fullJoin(table, condition) {
+    return this.addJoin(table, condition, "full");
+  }
+  /**
+   * Select specific fields
+   */
+  select(fields) {
+    this.selectFields = fields;
+    return this;
+  }
+  /**
+   * Add a WHERE condition
+   */
+  where(condition) {
+    this.whereCondition = condition;
+    return this;
+  }
+  /**
+   * Add ORDER BY
+   */
+  orderBy(...fields) {
+    this.orderByFields = fields;
+    return this;
+  }
+  /**
+   * Set LIMIT
+   */
+  limit(value) {
+    this.limitValue = value;
+    return this;
+  }
+  /**
+   * Set OFFSET
+   */
+  offset(value) {
+    this.offsetValue = value;
+    return this;
+  }
+  /**
+   * Execute the query and return typed results
+   */
+  async execute() {
+    if (!this.fromTable) {
+      throw new Error("[drizzle-multitenant] No table specified. Use .from() first.");
+    }
+    const sqlQuery = this.buildSql();
+    const result = await this.tenantDb.execute(sqlQuery);
+    return result.rows;
+  }
+  /**
+   * Add a join to the query
+   */
+  addJoin(table, condition, type) {
+    const isShared = isSharedTable(table, this.sharedTables);
+    this.joins.push({
+      table,
+      isShared,
+      schemaName: isShared ? this.sharedSchemaName : this.tenantSchemaName,
+      condition,
+      type
+    });
+    return this;
+  }
+  /**
+   * Build the SQL query
+   */
+  buildSql() {
+    if (!this.fromTable) {
+      throw new Error("[drizzle-multitenant] No table specified");
+    }
+    const parts = [];
+    const selectParts = Object.entries(this.selectFields).map(([alias, column]) => {
+      const columnName = column.name;
+      const tableName = this.getTableAliasForColumn(column);
+      if (tableName) {
+        return sql`${sql.raw(`"${tableName}"."${columnName}"`)} as ${sql.raw(`"${alias}"`)}`;
+      }
+      return sql`${sql.raw(`"${columnName}"`)} as ${sql.raw(`"${alias}"`)}`;
+    });
+    if (selectParts.length === 0) {
+      parts.push(sql`SELECT *`);
+    } else {
+      parts.push(sql`SELECT ${sql.join(selectParts, sql`, `)}`);
+    }
+    const fromTableName = getTableName(this.fromTable.table);
+    const fromTableRef = `"${this.fromTable.schemaName}"."${fromTableName}"`;
+    parts.push(sql` FROM ${sql.raw(fromTableRef)} "${sql.raw(fromTableName)}"`);
+    for (const join2 of this.joins) {
+      const joinTableName = getTableName(join2.table);
+      const joinTableRef = `"${join2.schemaName}"."${joinTableName}"`;
+      const joinKeyword = this.getJoinKeyword(join2.type);
+      parts.push(
+        sql` ${sql.raw(joinKeyword)} ${sql.raw(joinTableRef)} "${sql.raw(joinTableName)}" ON ${join2.condition}`
+      );
+    }
+    if (this.whereCondition) {
+      parts.push(sql` WHERE ${this.whereCondition}`);
+    }
+    if (this.orderByFields.length > 0) {
+      parts.push(sql` ORDER BY ${sql.join(this.orderByFields, sql`, `)}`);
+    }
+    if (this.limitValue !== null) {
+      parts.push(sql` LIMIT ${sql.raw(this.limitValue.toString())}`);
+    }
+    if (this.offsetValue !== null) {
+      parts.push(sql` OFFSET ${sql.raw(this.offsetValue.toString())}`);
+    }
+    return sql.join(parts, sql``);
+  }
+  /**
+   * Get table alias for a column (used in SELECT)
+   */
+  getTableAliasForColumn(column) {
+    const columnTable = column.table;
+    if (columnTable) {
+      return getTableName(columnTable);
+    }
+    return null;
+  }
+  /**
+   * Get SQL keyword for join type
+   */
+  getJoinKeyword(type) {
+    switch (type) {
+      case "inner":
+        return "INNER JOIN";
+      case "left":
+        return "LEFT JOIN";
+      case "right":
+        return "RIGHT JOIN";
+      case "full":
+        return "FULL OUTER JOIN";
+    }
+  }
+};
+function withShared(tenantDb, _sharedDb, schemas, options) {
+  const sharedTables = extractTablesFromSchema(schemas.shared);
+  return new WithSharedQueryBuilder(
+    tenantDb,
+    sharedTables,
+    options?.tenantSchema ?? "tenant",
+    options?.sharedSchema ?? "public"
+  );
+}
 
-export { CrossSchemaQueryBuilder, DEFAULT_CONFIG, Migrator, buildCrossSchemaSelect, createCrossSchemaQuery, createMigrator, createTenantContext, createTenantManager, crossSchemaRaw, defineConfig, withSharedLookup };
+export { CrossSchemaQueryBuilder, DEFAULT_CONFIG, Migrator, WithSharedQueryBuilder, buildCrossSchemaSelect, calculateDelay, createCrossSchemaQuery, createMigrator, createRetrier, createTenantContext, createTenantManager, crossSchemaRaw, defineConfig, isRetryableError, withRetry, withShared, withSharedLookup };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map