@xemahq/biome-database-sdk 0.1.1

package/src/lib/migration-runner.ts

@@ -0,0 +1,177 @@
+import { execSync } from 'child_process';
+import { Logger } from '@nestjs/common';
+import type { BiomeMigrationOptions, BiomeMigrationResult } from './types';
+
+const logger = new Logger('BiomeMigrationRunner');
+
+/**
+ * Runs migrations for a biome using the specified migration system.
+ * Supports Prisma, Flyway, Drizzle, and custom runners via CLI.
+ *
+ * Optionally triggers a backup before running (for safety).
+ * Returns migration result with timing and error details.
+ */
+export async function runBiomeMigration(
+  options: BiomeMigrationOptions,
+): Promise<BiomeMigrationResult> {
+  const {
+    databaseUrl,
+    migrationsPath,
+    migrationType,
+    dryRun = false,
+    backupBeforeRun = false,
+    biomeId = 'unknown',
+    orgDatabasePoolApiUrl,
+    databaseId,
+  } = options;
+
+  if (!databaseUrl) {
+    return {
+      success: false,
+      migrationsRun: [],
+      errors: ['databaseUrl is required'],
+      duration: 0,
+    };
+  }
+
+  const startTime = Date.now();
+
+  try {
+    // Optional: trigger backup before migration
+    if (backupBeforeRun && orgDatabasePoolApiUrl && databaseId) {
+      const backupId = await triggerBackup(
+        orgDatabasePoolApiUrl,
+        databaseId,
+        biomeId,
+      );
+      logger.log(`[${biomeId}] Backup triggered: ${backupId}`);
+    }
+
+    // Run the migrations
+    const cmd = buildMigrationCommand(
+      migrationType,
+      migrationsPath,
+      dryRun,
+    );
+
+    logger.log(`[${biomeId}] Running: ${cmd}`);
+
+    const output = execSync(cmd, {
+      env: { ...process.env, DATABASE_URL: databaseUrl },
+      encoding: 'utf-8',
+    });
+
+    logger.log(`[${biomeId}] Migrations completed:\n${output}`);
+
+    const duration = Date.now() - startTime;
+    return {
+      success: true,
+      migrationsRun: parseAppliedMigrations(output, migrationType),
+      duration,
+    };
+  } catch (err) {
+    const errorMsg = err instanceof Error ? err.message : String(err);
+    const duration = Date.now() - startTime;
+
+    logger.error(
+      `[${biomeId}] Migration failed: ${errorMsg}`,
+      err instanceof Error ? err.stack : undefined,
+    );
+
+    return {
+      success: false,
+      migrationsRun: [],
+      errors: [errorMsg],
+      duration,
+    };
+  }
+}
+
+/**
+ * Builds the CLI command for running migrations based on the migration system.
+ */
+function buildMigrationCommand(
+  migrationType: string,
+  migrationsPath: string,
+  dryRun: boolean,
+): string {
+  const dryRunFlag = dryRun ? '--dry-run' : '';
+
+  switch (migrationType) {
+    case 'prisma':
+      return `npx prisma migrate deploy ${dryRunFlag}`.trim();
+    case 'flyway':
+      return `flyway -locations=filesystem:${migrationsPath} migrate ${dryRunFlag}`.trim();
+    case 'drizzle':
+      return `drizzle-kit migrate --config=drizzle.config.ts ${dryRunFlag}`.trim();
+    default:
+      throw new Error(`Unsupported migration type: ${migrationType}`);
+  }
+}
+
+/**
+ * Parses the output of a migration command to extract applied migration names.
+ */
+function parseAppliedMigrations(output: string, migrationType: string): string[] {
+  const migrations: string[] = [];
+
+  switch (migrationType) {
+    case 'prisma': {
+      // Prisma format: "Migrate created: 20240101120000_init"
+      const matches = output.match(/Migrate created: (\S+)/g) || [];
+      matches.forEach((m) => {
+        const name = m.replace('Migrate created: ', '');
+        migrations.push(name);
+      });
+      break;
+    }
+    case 'flyway': {
+      // Flyway format: "Successfully applied 2 migration(s) ..."
+      const matches = output.match(/V\d+__\S+/g) || [];
+      migrations.push(...matches);
+      break;
+    }
+    case 'drizzle': {
+      // Drizzle format: varies; look for file names
+      const matches = output.match(/\d+_\S+\.sql/g) || [];
+      migrations.push(...matches);
+      break;
+    }
+  }
+
+  return migrations;
+}
+
+/**
+ * Triggers a backup in org-database-pool-api before running migrations.
+ * This is a safety measure to allow rollback if needed.
+ */
+async function triggerBackup(
+  poolApiUrl: string,
+  databaseId: string,
+  biomeId: string,
+): Promise<string> {
+  try {
+    const response = await fetch(
+      `${poolApiUrl}/databases/${databaseId}/snapshot`,
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Biome-Id': biomeId,
+        },
+      },
+    );
+
+    if (!response.ok) {
+      throw new Error(`Backup failed: ${response.statusText}`);
+    }
+
+    const data = await response.json() as { backupId: string };
+    return data.backupId;
+  } catch (err) {
+    const errorMsg = err instanceof Error ? err.message : String(err);
+    logger.warn(`[${biomeId}] Failed to trigger backup: ${errorMsg}`);
+    throw err;
+  }
+}

package/src/lib/org-managed-db.module.ts

@@ -0,0 +1,187 @@
+import { Global, Inject, Injectable, Logger, Module, OnModuleInit } from '@nestjs/common';
+import type { OrgManagedDatabaseOptions, ConnectionGrant } from './types';
+
+export const ORG_MANAGED_DATABASE_OPTIONS = 'ORG_MANAGED_DATABASE_OPTIONS';
+
+const logger = new Logger('OrgManagedDatabaseModule');
+
+/**
+ * Service that manages connections to org-managed databases via org-database-pool-api.
+ */
+@Injectable()
+export class OrgManagedDatabaseService implements OnModuleInit {
+  private refreshInterval?: NodeJS.Timeout;
+  private currentGrant?: ConnectionGrant;
+
+  constructor(
+    @Inject(ORG_MANAGED_DATABASE_OPTIONS)
+    private readonly options: OrgManagedDatabaseOptions,
+  ) {}
+
+  async onModuleInit(): Promise<void> {
+    if (!this.options.databaseId) {
+      logger.warn('databaseId not provided; org-managed database integration disabled');
+      return;
+    }
+
+    await this.refreshConnection();
+
+    const refreshInterval = this.options.refreshConnInterval || 30_000;
+    this.refreshInterval = setInterval(() => {
+      this.refreshConnection().catch((err) => {
+        logger.error('Failed to refresh org-managed database connection', err);
+      });
+    }, refreshInterval);
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    if (this.refreshInterval) {
+      clearInterval(this.refreshInterval);
+    }
+  }
+
+  async getConnectionGrant(): Promise<ConnectionGrant> {
+    if (!this.currentGrant) {
+      await this.refreshConnection();
+    }
+
+    const now = new Date();
+    const timeToExpiry = this.currentGrant!.expiresAt.getTime() - now.getTime();
+
+    if (timeToExpiry < 5000) {
+      await this.refreshConnection();
+    }
+
+    return this.currentGrant!;
+  }
+
+  async getDatabaseUrl(): Promise<string> {
+    const grant = await this.getConnectionGrant();
+    return grant.databaseUrl;
+  }
+
+  private async refreshConnection(): Promise<void> {
+    if (!this.options.databaseId) {
+      throw new Error('databaseId is required for org-managed database');
+    }
+
+    try {
+      const database = await this.fetchJson<{ schemaName: string; orgId: string }>(
+        `${this.options.poolApiUrl}/databases/${this.options.databaseId}`,
+      );
+      const roleName = this.rolesForSchema(database.schemaName).rwRoleName;
+      const grant = await this.fetchJson<{
+        host: string;
+        port: number;
+        database: string;
+        schema: string;
+        user: string;
+        password: string;
+        expiresAt: string;
+      }>(`${this.options.poolApiUrl}/connections/mint`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Biome-Id': this.options.biomeId || 'unknown',
+        },
+        body: JSON.stringify({
+          databaseId: this.options.databaseId,
+          schemaName: database.schemaName,
+          roleName,
+          ttlSeconds: 600,
+        }),
+      });
+
+      this.currentGrant = {
+        databaseUrl: this.buildPostgresUrl({
+          host: grant.host,
+          port: grant.port,
+          database: grant.database,
+          user: grant.user,
+          password: grant.password,
+          schema: grant.schema,
+        }),
+        host: grant.host,
+        port: grant.port,
+        database: grant.database,
+        schema: grant.schema,
+        user: grant.user,
+        password: grant.password,
+        expiresAt: new Date(grant.expiresAt),
+        databaseId: this.options.databaseId,
+        schemaName: database.schemaName,
+        roleName,
+      };
+
+      logger.log(
+        `Connection grant refreshed for database ${this.options.databaseId}; expires at ${grant.expiresAt}`,
+      );
+    } catch (err) {
+      logger.error(
+        `Failed to refresh org-managed database connection: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+      throw err;
+    }
+  }
+
+  private rolesForSchema(schemaName: string): {
+    rwRoleName: string;
+    roRoleName: string;
+  } {
+    const base = schemaName.toLowerCase().replace(/[^a-z0-9_]/g, '_').slice(0, 54);
+    return {
+      rwRoleName: `${base}_rw`,
+      roRoleName: `${base}_ro`,
+    };
+  }
+
+  private buildPostgresUrl(input: {
+    host: string;
+    port: number;
+    database: string;
+    user: string;
+    password: string;
+    schema: string;
+  }): string {
+    const user = encodeURIComponent(input.user);
+    const password = encodeURIComponent(input.password);
+    const schema = encodeURIComponent(input.schema);
+
+    return `postgresql://${user}:${password}@${input.host}:${input.port}/${input.database}?schema=${schema}`;
+  }
+
+  private async fetchJson<T>(url: string, init?: RequestInit): Promise<T> {
+    const response = await fetch(url, init);
+    if (!response.ok) {
+      throw new Error(`Request failed: ${response.status} ${response.statusText} (${url})`);
+    }
+    return (await response.json()) as T;
+  }
+}
+
+@Global()
+@Module({
+  providers: [OrgManagedDatabaseService],
+  exports: [OrgManagedDatabaseService],
+})
+export class OrgManagedDatabaseModule {
+  static register(options: OrgManagedDatabaseOptions) {
+    return {
+      module: OrgManagedDatabaseModule,
+      providers: [
+        {
+          provide: ORG_MANAGED_DATABASE_OPTIONS,
+          useValue: options,
+        },
+        OrgManagedDatabaseService,
+      ],
+      exports: [OrgManagedDatabaseService],
+    };
+  }
+}
+
+export function hasOrgDatabaseConfig(): boolean {
+  return Boolean(process.env.ORG_DATABASE_POOL_API_URL && process.env.ORG_DATABASE_ID);
+}

package/src/lib/prisma-factory.ts

@@ -0,0 +1,101 @@
+import { Logger } from '@nestjs/common';
+import type { CreateBiomePrismaClientOptions } from './types';
+
+const logger = new Logger('BiomePrismaFactory');
+
+interface PrismaClientLike {
+  $on(event: 'error' | 'warn', handler: (event: { message: string; stack?: string }) => void): void;
+  $connect(): Promise<void>;
+  $disconnect(): Promise<void>;
+}
+
+const { PrismaClient } = require('@prisma/client') as {
+  PrismaClient: new (options: {
+    datasources: {
+      db: {
+        url: string;
+      };
+    };
+    log: Array<{
+      emit: 'event';
+      level: 'error' | 'warn' | 'info' | 'debug';
+    }>;
+  }) => PrismaClientLike;
+};
+
+/**
+ * Creates a Prisma client for a biome with standardized error handling and logging.
+ */
+export function createBiomePrismaClient(
+  options: CreateBiomePrismaClientOptions,
+): PrismaClientLike {
+  const { databaseUrl, biomeId = 'unknown', schema, logLevel = 'warn' } = options;
+
+  if (!databaseUrl) {
+    throw new Error('[BiomePrismaFactory] databaseUrl is required');
+  }
+
+  // Build datasource URL with schema if provided
+  let finalUrl = databaseUrl;
+  if (schema && !databaseUrl.includes(`schema=${schema}`)) {
+    const separator = databaseUrl.includes('?') ? '&' : '?';
+    finalUrl = `${databaseUrl}${separator}schema=${schema}`;
+  }
+
+  const client = new PrismaClient({
+    datasources: {
+      db: {
+        url: finalUrl,
+      },
+    },
+    log: [
+      {
+        emit: 'event',
+        level: logLevel as any,
+      },
+    ],
+  });
+
+  // Set up event listeners
+  client.$on('error', (event) => {
+    logger.error(
+      `[${biomeId}] Prisma error: ${event.message}`,
+      event.stack,
+    );
+  });
+
+  client.$on('warn', (event) => {
+    logger.warn(`[${biomeId}] Prisma warn: ${event.message}`);
+  });
+
+  // Test the connection on startup
+  client.$connect()
+    .then(() => {
+      const schemaLabel = schema ? `${schema} schema` : 'default schema';
+      logger.log(`[${biomeId}] Prisma client connected to ${schemaLabel}`);
+    })
+    .catch((err) => {
+      logger.error(
+        `[${biomeId}] Failed to connect Prisma client: ${err.message}`,
+        err.stack,
+      );
+    });
+
+  return client;
+}
+
+/**
+ * Gracefully disconnects a Prisma client.
+ */
+export async function disconnectBiomePrismaClient(
+  client: PrismaClientLike,
+  biomeId: string = 'unknown',
+): Promise<void> {
+  try {
+    await client.$disconnect();
+    logger.log(`[${biomeId}] Prisma client disconnected`);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    logger.error(`[${biomeId}] Failed to disconnect Prisma client: ${message}`);
+  }
+}

package/src/lib/types.ts

@@ -0,0 +1,113 @@
+/**
+ * Type definitions for the Biome Database SDK.
+ * Used by biome API services to initialize, discover, and manage databases.
+ */
+
+export type MigrationType = 'prisma' | 'flyway' | 'drizzle' | 'custom';
+
+/**
+ * Configuration for a single database in a multi-database setup.
+ */
+export interface DatabaseConfig {
+  name: string;
+  schema?: string;
+}
+
+/**
+ * Options for ensureDatabaseUrls helper.
+ */
+export interface EnsureDatabaseUrlsOptions {
+  singleDatabase?: boolean;
+  dbName?: string;
+  dbSchema?: string;
+  databases?: Record<string, DatabaseConfig>;
+}
+
+/**
+ * Options for Prisma client factory.
+ */
+export interface CreateBiomePrismaClientOptions {
+  databaseUrl: string;
+  biomeId?: string;
+  schema?: string;
+  logLevel?: 'error' | 'warn' | 'info' | 'debug';
+}
+
+/**
+ * Options for migration discovery.
+ */
+export interface DiscoverMigrationsOptions {
+  searchPaths: string[];
+  migrationType: MigrationType;
+}
+
+/**
+ * Result of migration discovery.
+ */
+export interface DiscoveredMigrations {
+  applied: MigrationRecord[];
+  pending: MigrationRecord[];
+  errors?: string[];
+}
+
+/**
+ * A single migration record.
+ */
+export interface MigrationRecord {
+  name: string;
+  checksum?: string;
+  appliedAt?: Date;
+  path: string;
+}
+
+/**
+ * Options for running a migration.
+ */
+export interface BiomeMigrationOptions {
+  databaseUrl: string;
+  migrationsPath: string;
+  migrationType: MigrationType;
+  dryRun?: boolean;
+  backupBeforeRun?: boolean;
+  biomeId?: string;
+  orgDatabasePoolApiUrl?: string;
+  databaseId?: string;
+}
+
+/**
+ * Result of running a migration.
+ */
+export interface BiomeMigrationResult {
+  success: boolean;
+  migrationsRun: string[];
+  errors?: string[];
+  backupId?: string;
+  duration: number;
+}
+
+/**
+ * Options for org-managed database attachment.
+ */
+export interface OrgManagedDatabaseOptions {
+  poolApiUrl: string;
+  refreshConnInterval?: number;
+  databaseId?: string;
+  biomeId?: string;
+}
+
+/**
+ * Connection grant from org-database-pool-api.
+ */
+export interface ConnectionGrant {
+  databaseUrl: string;
+  host: string;
+  port: number;
+  database: string;
+  schema: string;
+  user: string;
+  password: string;
+  expiresAt: Date;
+  databaseId: string;
+  schemaName: string;
+  roleName: string;
+}

package/src/lib/url-builder.ts

@@ -0,0 +1,96 @@
+import type { DatabaseConfig, EnsureDatabaseUrlsOptions } from './types';
+
+/**
+ * Ensures DATABASE_URL is set by constructing it from component env vars if needed.
+ * Supports both single-database and multi-database biomes.
+ *
+ * Priority: existing DATABASE_URL > constructed from DB_* vars
+ *
+ * Throws if incomplete and no DATABASE_URL is already set.
+ */
+export function ensureDatabaseUrls(options: EnsureDatabaseUrlsOptions = {}): void {
+  const {
+    singleDatabase = true,
+    dbName,
+    dbSchema,
+    databases,
+  } = options;
+
+  if (singleDatabase) {
+    ensureSingleDatabase(dbName, dbSchema);
+  } else {
+    ensureMultiDatabase(databases || {});
+  }
+}
+
+/**
+ * Single-database setup. Constructs DATABASE_URL if not already set.
+ */
+function ensureSingleDatabase(dbName?: string, dbSchema?: string): void {
+  if (process.env.DATABASE_URL) {
+    return;
+  }
+
+  const {
+    DB_USER,
+    DB_PASSWORD,
+    DB_HOST,
+    DB_PORT,
+    DB_NAME,
+    DB_SCHEMA,
+    DB_SSL_PARAMS,
+  } = process.env;
+
+  const user = DB_USER;
+  const password = DB_PASSWORD;
+  const host = DB_HOST;
+  const port = DB_PORT;
+  const name = DB_NAME || dbName || 'xema';
+  const schema = DB_SCHEMA || dbSchema;
+  const ssl = DB_SSL_PARAMS;
+
+  if (!user || !password || !host || !port) {
+    throw new Error(
+      '[BiomeDatabase] DATABASE_URL not set and incomplete DB_* env vars. ' +
+      'Set DATABASE_URL or provide DB_USER, DB_PASSWORD, DB_HOST, DB_PORT',
+    );
+  }
+
+  const base = `postgresql://${user}:${encodeURIComponent(password)}@${host}:${port}/${name}`;
+  const schemaPart = schema ? `schema=${schema}` : null;
+  const params = [schemaPart, ssl].filter(Boolean).join('&');
+  process.env.DATABASE_URL = params ? `${base}?${params}` : base;
+}
+
+/**
+ * Multi-database setup. Constructs DATABASE_URL_* env vars for each database.
+ */
+function ensureMultiDatabase(databases: Record<string, DatabaseConfig>): void {
+  for (const [key, config] of Object.entries(databases)) {
+    const envKey = key === 'main' ? 'DATABASE_URL' : `DATABASE_URL_${key.toUpperCase()}`;
+
+    if (process.env[envKey]) {
+      continue;  // already set, skip
+    }
+
+    const {
+      DB_USER,
+      DB_PASSWORD,
+      DB_HOST,
+      DB_PORT,
+      DB_SSL_PARAMS,
+    } = process.env;
+
+    if (!DB_USER || !DB_PASSWORD || !DB_HOST || !DB_PORT) {
+      throw new Error(
+        `[BiomeDatabase] ${envKey} not set and incomplete DB_* env vars. ` +
+        'Set DATABASE_URL or provide DB_USER, DB_PASSWORD, DB_HOST, DB_PORT',
+      );
+    }
+
+    const base = `postgresql://${DB_USER}:${encodeURIComponent(DB_PASSWORD)}@${DB_HOST}:${DB_PORT}/${config.name}`;
+    const schemaPart = config.schema ? `schema=${config.schema}` : null;
+    const params = [schemaPart, DB_SSL_PARAMS].filter(Boolean).join('&');
+    process.env[envKey] = params ? `${base}?${params}` : base;
+  }
+}