@happyvertical/sql 0.74.8

package/dist/postgres.d.ts

@@ -0,0 +1,77 @@
+import { DatabaseInterface } from './shared/types';
+/**
+ * Configuration options for PostgreSQL database connections
+ */
+export interface PostgresOptions {
+    /**
+     * Connection URL for PostgreSQL
+     */
+    url?: string;
+    /**
+     * Database name
+     */
+    database?: string;
+    /**
+     * Database server hostname
+     */
+    host?: string;
+    /**
+     * Username for authentication
+     */
+    user?: string;
+    /**
+     * Password for authentication
+     */
+    password?: string;
+    /**
+     * Port number for the PostgreSQL server
+     */
+    port?: number;
+    /**
+     * Cache key for connection pooling.
+     * If provided, the same dbid returns the same cached connection.
+     * When omitted, a key is derived from the connection URL.
+     */
+    dbid?: string;
+    /**
+     * Maximum number of connections in the pool.
+     * Defaults to 20. The pg library defaults to 10, which is too low
+     * for applications with many SMRT collections.
+     */
+    max?: number;
+    /**
+     * Schema definitions for tables.
+     * Accepts a record or a lazy function (see SchemasOption).
+     *
+     * **Postgres ignores this option** — tables are managed by migrations.
+     * The option exists so callers can pass schemas uniformly to all adapters
+     * without knowing the adapter type. Only JSON/DuckDB adapters resolve it.
+     */
+    schemas?: import('./shared/types').SchemasOption;
+}
+/**
+ * Clears the PostgreSQL connection cache.
+ * Useful for test isolation and reconnection scenarios.
+ */
+export declare function clearPostgresConnectionCache(): void;
+/**
+ * Creates a PostgreSQL database adapter
+ *
+ * Loads configuration from environment variables with backward compatibility:
+ * - First checks HAVE_SQL_* environment variables (new standard)
+ * - Falls back to SQLOO_* environment variables (legacy)
+ * - User-provided options always take precedence
+ *
+ * Environment variables:
+ * - HAVE_SQL_URL / SQLOO_URL → Connection string (takes precedence)
+ * - HAVE_SQL_DATABASE / SQLOO_DATABASE → Database name
+ * - HAVE_SQL_HOST / SQLOO_HOST → Host (default: 'localhost')
+ * - HAVE_SQL_USER / SQLOO_USER → Username
+ * - HAVE_SQL_PASSWORD / SQLOO_PASSWORD → Password
+ * - HAVE_SQL_PORT / SQLOO_PORT → Port (default: 5432)
+ *
+ * @param options - PostgreSQL connection options
+ * @returns Database interface for PostgreSQL
+ */
+export declare function getDatabase(options?: PostgresOptions): Promise<DatabaseInterface>;
+//# sourceMappingURL=postgres.d.ts.map

package/dist/postgres.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../src/postgres.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAIV,iBAAiB,EAYlB,MAAM,gBAAgB,CAAC;AAGxB;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,OAAO,gBAAgB,EAAE,aAAa,CAAC;CAClD;AAiBD;;;GAGG;AACH,wBAAgB,4BAA4B,IAAI,IAAI,CAGnD;AA4YD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,WAAW,CAC/B,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,iBAAiB,CAAC,CA8C5B"}

package/dist/schema-manager.d.ts

@@ -0,0 +1,86 @@
+import { DatabaseInterface, SchemaInitializationOptions } from './shared/types.js';
+/**
+ * Result returned by DatabaseSchemaManager.initializeSchemas()
+ *
+ * Contains the list of schemas that were successfully initialized,
+ * any that were skipped (already up to date), errors encountered,
+ * and the total execution time in milliseconds.
+ */
+export interface SchemaInitializationResult {
+    initialized: string[];
+    skipped: string[];
+    errors: Array<{
+        schema: string;
+        error: string;
+    }>;
+    executionTime: number;
+}
+/**
+ * Manages schema initialization from JSON manifests with dependency resolution
+ *
+ * Handles topological sorting of schema dependencies, table creation,
+ * index and trigger setup, and version tracking to avoid redundant re-initialization.
+ */
+export declare class DatabaseSchemaManager {
+    private static initializationLock;
+    private initializedSchemas;
+    private schemaVersions;
+    /**
+     * Initializes database schemas from a JSON manifest with dependency resolution
+     *
+     * Schemas are topologically sorted by their declared dependencies and
+     * initialized in order. Supports legacy raw-SQL schemas via the `schema` option,
+     * JSON manifests via the `manifest` option, and schema overrides for extending
+     * base schemas.
+     *
+     * @param db - Database interface to execute DDL against
+     * @param options - Schema initialization options (manifest, overrides, force, debug)
+     * @returns Result with lists of initialized/skipped schemas, errors, and execution time
+     */
+    initializeSchemas(db: DatabaseInterface, options: SchemaInitializationOptions): Promise<SchemaInitializationResult>;
+    /**
+     * Initialize a single schema
+     */
+    private initializeSchema;
+    /**
+     * Perform the actual schema initialization
+     */
+    private performSchemaInitialization;
+    /**
+     * Create table from schema definition
+     */
+    private createTable;
+    /**
+     * Create index from definition
+     */
+    private createIndex;
+    /**
+     * Create trigger from definition
+     */
+    private createTrigger;
+    /**
+     * Update schema if changes are detected
+     */
+    private updateSchemaIfNeeded;
+    /**
+     * Build dependency graph from schemas
+     */
+    private buildDependencyGraph;
+    /**
+     * Resolve dependencies using topological sort
+     */
+    private resolveDependencies;
+    /**
+     * Check if schema is up to date
+     */
+    private isSchemaUpToDate;
+    /**
+     * Mark schema as initialized
+     */
+    private markSchemaInitialized;
+    /**
+     * Reset initialization state (for testing)
+     */
+    reset(): void;
+}
+//# sourceMappingURL=schema-manager.d.ts.map

package/dist/schema-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-manager.d.ts","sourceRoot":"","sources":["../src/schema-manager.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,iBAAiB,EAGjB,2BAA2B,EAE5B,MAAM,mBAAmB,CAAC;AAE3B;;;;;;GAMG;AACH,MAAM,WAAW,0BAA0B;IACzC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjD,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAoC;IACrE,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,cAAc,CAA6B;IAEnD;;;;;;;;;;;OAWG;IACG,iBAAiB,CACrB,EAAE,EAAE,iBAAiB,EACrB,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,0BAA0B,CAAC;IAgGtC;;OAEG;YACW,gBAAgB;IAwC9B;;OAEG;YACW,2BAA2B;IA8CzC;;OAEG;YACW,WAAW;IAmCzB;;OAEG;YACW,WAAW;IAYzB;;OAEG;YACW,aAAa;IAY3B;;OAEG;YACW,oBAAoB;IAWlC;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAuB5B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAkC3B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAOxB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAK7B;;OAEG;IACH,KAAK,IAAI,IAAI;CAKd"}

package/dist/shared/alter-utils.d.ts

@@ -0,0 +1,83 @@
+import { ColumnDefinitionWithName, IndexDefinition } from './types.js';
+/**
+ * Database dialect type for SQL generation
+ */
+export type DatabaseDialect = 'sqlite' | 'postgres' | 'duckdb';
+/**
+ * Generates an ALTER TABLE ADD COLUMN statement
+ *
+ * @param table - Table name
+ * @param column - Column definition with name
+ * @param dialect - Database dialect
+ * @returns SQL statement string
+ *
+ * @example
+ * ```typescript
+ * const sql = generateAddColumnStatement('users', {
+ *   name: 'email',
+ *   type: 'TEXT',
+ *   unique: true,
+ *   notNull: false
+ * }, 'sqlite');
+ * // Returns: "ALTER TABLE users ADD COLUMN email TEXT UNIQUE"
+ * ```
+ */
+export declare function generateAddColumnStatement(table: string, column: ColumnDefinitionWithName, _dialect: DatabaseDialect): string;
+/**
+ * Generates a DEFAULT clause for a column definition
+ *
+ * Handles proper formatting and escaping of default values based on column type.
+ *
+ * @param columnType - SQL column type (TEXT, INTEGER, BOOLEAN, etc.)
+ * @param defaultValue - Default value to format
+ * @returns Formatted default value string
+ *
+ * @example
+ * ```typescript
+ * generateDefaultClause('TEXT', 'hello'); // Returns: "'hello'"
+ * generateDefaultClause('INTEGER', 42);   // Returns: "42"
+ * generateDefaultClause('BOOLEAN', true); // Returns: "true"
+ * generateDefaultClause('TEXT', null);    // Returns: "NULL"
+ * ```
+ */
+export declare function generateDefaultClause(columnType: string, defaultValue: any): string;
+/**
+ * Generates a CREATE INDEX statement
+ *
+ * @param table - Table name
+ * @param index - Index definition
+ * @returns SQL CREATE INDEX statement
+ *
+ * @example
+ * ```typescript
+ * const sql = generateCreateIndexStatement('users', {
+ *   name: 'idx_users_email',
+ *   columns: ['email'],
+ *   unique: true
+ * });
+ * // Returns: "CREATE UNIQUE INDEX idx_users_email ON users (email)"
+ * ```
+ */
+export declare function generateCreateIndexStatement(table: string, index: IndexDefinition): string;
+/**
+ * Validates a table name to prevent SQL injection
+ *
+ * @param tableName - Table name to validate
+ * @throws Error if table name contains invalid characters
+ */
+export declare function validateTableName(tableName: string): void;
+/**
+ * Validates a column name to prevent SQL injection
+ *
+ * @param columnName - Column name to validate
+ * @throws Error if column name contains invalid characters
+ */
+export declare function validateColumnName(columnName: string): void;
+/**
+ * Validates an index name to prevent SQL injection
+ *
+ * @param indexName - Index name to validate
+ * @throws Error if index name contains invalid characters
+ */
+export declare function validateIndexName(indexName: string): void;
+//# sourceMappingURL=alter-utils.d.ts.map

package/dist/shared/alter-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alter-utils.d.ts","sourceRoot":"","sources":["../../src/shared/alter-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,wBAAwB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE5E;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE/D;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,wBAAwB,EAChC,QAAQ,EAAE,eAAe,GACxB,MAAM,CAkDR;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,GAAG,GAChB,MAAM,CAkER;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,eAAe,GACrB,MAAM,CA0BR;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAMzD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAM3D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAMzD"}

package/dist/shared/duckdb-schema-utils.d.ts

@@ -0,0 +1,86 @@
+/**
+ * DuckDB-specific schema transformation utilities
+ *
+ * DuckDB has a known limitation (issue #12684) where ON CONFLICT clauses
+ * fail with UNIQUE INDEX but work with inline UNIQUE constraints.
+ *
+ * This module provides utilities to transform SMRT-generated schemas
+ * (which use separate CREATE UNIQUE INDEX statements) into DuckDB-compatible
+ * schemas (which use inline UNIQUE constraints).
+ */
+/**
+ * Index definition extracted from CREATE INDEX statement
+ */
+interface ParsedIndex {
+    name: string;
+    columns: string[];
+    unique: boolean;
+    sql: string;
+}
+/**
+ * Parses a CREATE INDEX statement to extract index details
+ *
+ * @param indexSQL - CREATE INDEX statement
+ * @returns Parsed index definition or null if parsing fails
+ *
+ * @example
+ * ```typescript
+ * const index = parseIndexStatement(
+ *   'CREATE UNIQUE INDEX ds_slug_context_idx ON ds (slug, context)'
+ * );
+ * // Returns: {
+ * //   name: 'ds_slug_context_idx',
+ * //   columns: ['slug', 'context'],
+ * //   unique: true,
+ * //   sql: '...'
+ * // }
+ * ```
+ */
+export declare function parseIndexStatement(indexSQL: string): ParsedIndex | null;
+/**
+ * Converts UNIQUE INDEX statements to inline UNIQUE constraints for DuckDB compatibility
+ *
+ * DuckDB's ON CONFLICT clause requires inline UNIQUE constraints, not separate indexes.
+ * This function transforms SMRT-generated schemas to work with DuckDB's limitations.
+ *
+ * @param ddl - CREATE TABLE DDL statement
+ * @param indexes - Array of CREATE INDEX statements (optional)
+ * @returns Transformed DDL with inline UNIQUE constraints and filtered index list
+ *
+ * @example
+ * ```typescript
+ * const ddl = `
+ *   CREATE TABLE ds (
+ *     id TEXT PRIMARY KEY,
+ *     slug TEXT NOT NULL,
+ *     context TEXT NOT NULL
+ *   )
+ * `;
+ * const indexes = [
+ *   'CREATE UNIQUE INDEX ds_slug_context_idx ON ds (slug, context)'
+ * ];
+ *
+ * const result = convertUniqueIndexesToInlineConstraints(ddl, indexes);
+ * // result.ddl:
+ * //   CREATE TABLE ds (
+ * //     id TEXT PRIMARY KEY,
+ * //     slug TEXT NOT NULL,
+ * //     context TEXT NOT NULL,
+ * //     UNIQUE(slug, context)
+ * //   )
+ * // result.indexes: []  (UNIQUE index removed, non-UNIQUE indexes preserved)
+ * ```
+ */
+export declare function convertUniqueIndexesToInlineConstraints(ddl: string, indexes?: string[]): {
+    ddl: string;
+    indexes: string[];
+};
+/**
+ * Checks if a schema definition contains UNIQUE indexes that need conversion
+ *
+ * @param indexes - Array of CREATE INDEX statements
+ * @returns True if any UNIQUE indexes are present
+ */
+export declare function hasUniqueIndexes(indexes?: string[]): boolean;
+export {};
+//# sourceMappingURL=duckdb-schema-utils.d.ts.map

package/dist/shared/duckdb-schema-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duckdb-schema-utils.d.ts","sourceRoot":"","sources":["../../src/shared/duckdb-schema-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;GAEG;AACH,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CA0BxE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,uCAAuC,CACrD,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,MAAM,EAAE,GACjB;IACD,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CA4EA;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAS5D"}