spindb 0.37.2 → 0.38.0

package/dist/core/version-migration.js

@@ -0,0 +1,260 @@
+/**
+ * Version migration utilities for detecting and updating outdated container versions
+ *
+ * Detects containers using versions that are no longer in the version maps
+ * (e.g., from the zonky.io era) and offers to migrate them to currently
+ * supported versions while preserving major version compatibility.
+ */
+import { existsSync } from 'fs';
+import { rm } from 'fs/promises';
+import { paths } from '../config/paths.js';
+import { containerManager } from './container-manager.js';
+import { platformService } from './platform-service.js';
+import { Engine, isFileBasedEngine } from '../types/index.js';
+// Import version maps from all engines
+import { POSTGRESQL_VERSION_MAP, SUPPORTED_MAJOR_VERSIONS as PG_MAJORS, } from '../engines/postgresql/version-maps.js';
+import { MYSQL_VERSION_MAP, SUPPORTED_MAJOR_VERSIONS as MYSQL_MAJORS, } from '../engines/mysql/version-maps.js';
+import { MARIADB_VERSION_MAP, SUPPORTED_MAJOR_VERSIONS as MARIADB_MAJORS, } from '../engines/mariadb/version-maps.js';
+import { MONGODB_VERSION_MAP, SUPPORTED_MAJOR_VERSIONS as MONGODB_MAJORS, } from '../engines/mongodb/version-maps.js';
+import { FERRETDB_VERSION_MAP, DOCUMENTDB_VERSION_MAP, SUPPORTED_MAJOR_VERSIONS as FERRET_MAJORS, } from '../engines/ferretdb/version-maps.js';
+import { REDIS_VERSION_MAP, SUPPORTED_MAJOR_VERSIONS as REDIS_MAJORS, } from '../engines/redis/version-maps.js';
+import { VALKEY_VERSION_MAP, SUPPORTED_MAJOR_VERSIONS as VALKEY_MAJORS, } from '../engines/valkey/version-maps.js';
+import { CLICKHOUSE_VERSION_MAP, SUPPORTED_MAJOR_VERSIONS as CH_MAJORS, } from '../engines/clickhouse/version-maps.js';
+import { QDRANT_VERSION_MAP, SUPPORTED_MAJOR_VERSIONS as QDRANT_MAJORS, } from '../engines/qdrant/version-maps.js';
+import { MEILISEARCH_VERSION_MAP, SUPPORTED_MAJOR_VERSIONS as MEILI_MAJORS, } from '../engines/meilisearch/version-maps.js';
+// Registry of version maps per engine
+const VERSION_MAPS = {
+    [Engine.PostgreSQL]: {
+        versionMap: POSTGRESQL_VERSION_MAP,
+        majorVersions: PG_MAJORS,
+    },
+    [Engine.MySQL]: {
+        versionMap: MYSQL_VERSION_MAP,
+        majorVersions: MYSQL_MAJORS,
+    },
+    [Engine.MariaDB]: {
+        versionMap: MARIADB_VERSION_MAP,
+        majorVersions: MARIADB_MAJORS,
+    },
+    [Engine.MongoDB]: {
+        versionMap: MONGODB_VERSION_MAP,
+        majorVersions: MONGODB_MAJORS,
+    },
+    [Engine.FerretDB]: {
+        versionMap: FERRETDB_VERSION_MAP,
+        majorVersions: FERRET_MAJORS,
+    },
+    [Engine.Redis]: {
+        versionMap: REDIS_VERSION_MAP,
+        majorVersions: REDIS_MAJORS,
+    },
+    [Engine.Valkey]: {
+        versionMap: VALKEY_VERSION_MAP,
+        majorVersions: VALKEY_MAJORS,
+    },
+    [Engine.ClickHouse]: {
+        versionMap: CLICKHOUSE_VERSION_MAP,
+        majorVersions: CH_MAJORS,
+    },
+    [Engine.Qdrant]: {
+        versionMap: QDRANT_VERSION_MAP,
+        majorVersions: QDRANT_MAJORS,
+    },
+    [Engine.Meilisearch]: {
+        versionMap: MEILISEARCH_VERSION_MAP,
+        majorVersions: MEILI_MAJORS,
+    },
+};
+// Separate map for FerretDB backend (DocumentDB)
+const DOCUMENTDB_INFO = {
+    versionMap: DOCUMENTDB_VERSION_MAP,
+    majorVersions: ['17'],
+};
+/**
+ * Find which major version a full version belongs to by checking prefixes
+ * against SUPPORTED_MAJOR_VERSIONS.
+ *
+ * Different engines use different major version formats:
+ * - PostgreSQL: Single digit (e.g., '17')
+ * - MySQL: Two-part (e.g., '8.4')
+ * - MariaDB: Two-part (e.g., '11.8')
+ * - MongoDB: Two-part (e.g., '8.0')
+ * - ClickHouse: Two-part YY.MM (e.g., '25.12')
+ * - Redis/Valkey: Single digit (e.g., '7', '8')
+ * - Qdrant/Meilisearch: Single digit (e.g., '1')
+ *
+ * @param engine - The database engine
+ * @param version - Full version string (e.g., '17.2.0')
+ * @returns Major version string or null if not found
+ */
+export function getMajorVersion(engine, version) {
+    const info = VERSION_MAPS[engine];
+    if (!info)
+        return null;
+    // Sort by length descending so "8.4" matches before "8"
+    const sorted = [...info.majorVersions].sort((a, b) => b.length - a.length);
+    for (const major of sorted) {
+        if (version.startsWith(major + '.') || version === major) {
+            return major;
+        }
+    }
+    return null;
+}
+/**
+ * Get the major version for FerretDB backend (DocumentDB).
+ * Backend versions use format like "17-0.107.0" where "17" is the major.
+ */
+export function getDocumentDBMajorVersion(version) {
+    // Format: "17-0.107.0" -> major is "17"
+    const dashIndex = version.indexOf('-');
+    if (dashIndex > 0) {
+        const major = version.substring(0, dashIndex);
+        if (DOCUMENTDB_INFO.majorVersions.includes(major)) {
+            return major;
+        }
+    }
+    return null;
+}
+/**
+ * Check if a version exists as a VALUE in the version map
+ * (not just a key).
+ *
+ * @param engine - The database engine
+ * @param version - Version string to check
+ * @returns True if the version is a supported full version
+ */
+export function isVersionSupported(engine, version) {
+    const info = VERSION_MAPS[engine];
+    if (!info)
+        return false;
+    const supportedVersions = Object.values(info.versionMap);
+    return supportedVersions.includes(version);
+}
+/**
+ * Check if a DocumentDB backend version is supported.
+ */
+export function isDocumentDBVersionSupported(version) {
+    const supportedVersions = Object.values(DOCUMENTDB_INFO.versionMap);
+    return supportedVersions.includes(version);
+}
+/**
+ * Get the current full version for a major version.
+ *
+ * @param engine - The database engine
+ * @param majorVersion - Major version (e.g., '17', '8.4')
+ * @returns Current full version or null if not found
+ */
+export function getTargetVersion(engine, majorVersion) {
+    const info = VERSION_MAPS[engine];
+    if (!info)
+        return null;
+    return info.versionMap[majorVersion] || null;
+}
+/**
+ * Get the current full version for a DocumentDB major version.
+ */
+export function getDocumentDBTargetVersion(majorVersion) {
+    return DOCUMENTDB_INFO.versionMap[majorVersion] || null;
+}
+/**
+ * Find all containers that have outdated versions.
+ * Returns containers whose versions are not in the current version maps.
+ *
+ * @returns Array of outdated container information
+ */
+export async function findOutdatedContainers() {
+    const containers = await containerManager.list();
+    const outdated = [];
+    for (const container of containers) {
+        const engine = container.engine;
+        // Skip file-based engines - they use simplified major versions (e.g., "3", "1")
+        // that always resolve to current
+        if (isFileBasedEngine(engine)) {
+            continue;
+        }
+        // Check main version
+        if (!isVersionSupported(engine, container.version)) {
+            const majorVersion = getMajorVersion(engine, container.version);
+            if (majorVersion) {
+                const targetVersion = getTargetVersion(engine, majorVersion);
+                if (targetVersion && targetVersion !== container.version) {
+                    outdated.push({
+                        container,
+                        currentVersion: container.version,
+                        targetVersion,
+                        majorVersion,
+                        field: 'version',
+                    });
+                }
+            }
+        }
+        // Check FerretDB backend version
+        if (engine === Engine.FerretDB && container.backendVersion) {
+            if (!isDocumentDBVersionSupported(container.backendVersion)) {
+                const majorVersion = getDocumentDBMajorVersion(container.backendVersion);
+                if (majorVersion) {
+                    const targetVersion = getDocumentDBTargetVersion(majorVersion);
+                    if (targetVersion && targetVersion !== container.backendVersion) {
+                        outdated.push({
+                            container,
+                            currentVersion: container.backendVersion,
+                            targetVersion,
+                            majorVersion,
+                            field: 'backendVersion',
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return outdated;
+}
+/**
+ * Update a container's version in its config file.
+ *
+ * @param name - Container name
+ * @param targetVersion - New version to set
+ * @param field - Which field to update ('version' or 'backendVersion')
+ */
+export async function migrateContainerVersion(name, targetVersion, field) {
+    await containerManager.updateConfig(name, { [field]: targetVersion });
+}
+/**
+ * Check if any containers are using a specific version.
+ *
+ * @param engine - The database engine
+ * @param version - The version to check
+ * @returns True if at least one container uses this version
+ */
+export async function isVersionInUse(engine, version) {
+    const containers = await containerManager.list();
+    return containers.some((c) => c.engine === engine &&
+        (c.version === version || c.backendVersion === version));
+}
+/**
+ * Delete an old binary directory from ~/.spindb/bin/
+ * Only deletes if no other containers are using this version.
+ *
+ * @param engine - The database engine
+ * @param oldVersion - The old version to remove
+ * @returns True if the binary was deleted, false if still in use or not found
+ */
+export async function deleteOldBinaryIfUnused(engine, oldVersion) {
+    // Check if any containers still use this version
+    if (await isVersionInUse(engine, oldVersion)) {
+        return false;
+    }
+    const platformInfo = platformService.getPlatformInfo();
+    const binaryPath = paths.getBinaryPath({
+        engine: engine,
+        version: oldVersion,
+        platform: platformInfo.platform,
+        arch: platformInfo.arch,
+    });
+    if (existsSync(binaryPath)) {
+        await rm(binaryPath, { recursive: true, force: true });
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=version-migration.js.map

package/dist/core/version-migration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-migration.js","sourceRoot":"","sources":["../../core/version-migration.ts"],"names":[],"mappings":"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"}

package/dist/core/version-utils.js

@@ -0,0 +1,91 @@
+/**
+ * Shared version comparison utilities
+ *
+ * Provides robust version comparison that handles prerelease suffixes
+ * like "11.8.0-rc1" or "7.4.7-beta2".
+ */
+/**
+ * Parse a version segment into numeric prefix and suffix
+ *
+ * Expected format: optional digits followed by optional suffix
+ * Examples:
+ *   "7"     -> { num: 7, suffix: "" }
+ *   "7-rc1" -> { num: 7, suffix: "-rc1" }
+ *   "0"     -> { num: 0, suffix: "" }
+ *
+ * Non-numeric segments (no leading digits):
+ *   "abc"   -> { num: -1, suffix: "abc" }
+ *   ""      -> { num: -1, suffix: "" }
+ *
+ * Use num === -1 to detect non-numeric segments. When comparing versions,
+ * non-numeric segments sort before numeric ones (since -1 < 0).
+ *
+ * @param segment - A single version segment (part between dots)
+ * @returns Object with numeric prefix and remaining suffix
+ */
+export function parseVersionSegment(segment) {
+    const match = segment.match(/^(\d+)(.*)$/);
+    if (!match) {
+        // Non-numeric segment: use -1 as sentinel so callers can distinguish
+        return { num: -1, suffix: segment };
+    }
+    return { num: parseInt(match[1], 10), suffix: match[2] };
+}
+/**
+ * Compare two version strings (e.g., "11.8.5" vs "11.8.4")
+ * Handles prerelease suffixes like "11.8.0-rc1" - empty suffix sorts after prerelease
+ * Returns positive if a > b, negative if a < b, 0 if equal
+ */
+export function compareVersions(a, b) {
+    const partsA = a.split('.');
+    const partsB = b.split('.');
+    for (let i = 0; i < Math.max(partsA.length, partsB.length); i++) {
+        const segA = parseVersionSegment(partsA[i] || '0');
+        const segB = parseVersionSegment(partsB[i] || '0');
+        // Compare numeric parts first
+        if (segA.num !== segB.num) {
+            return segA.num - segB.num;
+        }
+        // If numeric parts equal, compare suffixes
+        // Empty suffix (release) > prerelease suffix (e.g., "-rc1")
+        if (segA.suffix !== segB.suffix) {
+            if (segA.suffix === '')
+                return 1; // a is release, b is prerelease
+            if (segB.suffix === '')
+                return -1; // b is release, a is prerelease
+            // NOTE: Lexicographic comparison means -rc10 < -rc2 (incorrect for numeric suffixes).
+            // This is acceptable for hostdb versions which use single-digit prereleases.
+            // If multi-digit prereleases are needed, parse numeric suffix separately.
+            return segA.suffix.localeCompare(segB.suffix);
+        }
+    }
+    return 0;
+}
+/**
+ * Check if versionA is newer than versionB
+ * Convenience wrapper around compareVersions
+ */
+export function isNewerVersion(versionA, versionB) {
+    return compareVersions(versionA, versionB) > 0;
+}
+/**
+ * Regex pattern for validating semver-like version strings.
+ * Matches: X, X.Y, or X.Y.Z where each component is numeric.
+ * Examples: "8", "8.0", "8.0.40", "17", "17.7.0"
+ */
+export const SEMVER_LIKE_PATTERN = /^\d+(\.\d+){0,2}$/;
+/**
+ * Validate that a version string matches semver-like format (X, X.Y, or X.Y.Z).
+ * Used by engines that require strict version format validation (MySQL, PostgreSQL).
+ *
+ * @param version - Version string to validate
+ * @param engineName - Engine name for error message (e.g., 'MySQL', 'PostgreSQL')
+ * @throws TypeError if version format is invalid
+ */
+export function validateSemverLikeVersion(version, engineName) {
+    if (!SEMVER_LIKE_PATTERN.test(version)) {
+        throw new TypeError(`Invalid ${engineName} version format: "${version}". ` +
+            `Expected format: X, X.Y, or X.Y.Z (e.g., "8", "8.0", "8.0.40")`);
+    }
+}
+//# sourceMappingURL=version-utils.js.map

package/dist/core/version-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-utils.js","sourceRoot":"","sources":["../../core/version-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAe;IAIjD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,CAAA;IAC1C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,qEAAqE;QACrE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAA;IACrC,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAA;AAC1D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,CAAS,EAAE,CAAS;IAClD,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAC3B,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAE3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAChE,MAAM,IAAI,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAA;QAClD,MAAM,IAAI,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAA;QAElD,8BAA8B;QAC9B,IAAI,IAAI,CAAC,GAAG,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC;YAC1B,OAAO,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAA;QAC5B,CAAC;QAED,2CAA2C;QAC3C,4DAA4D;QAC5D,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC;YAChC,IAAI,IAAI,CAAC,MAAM,KAAK,EAAE;gBAAE,OAAO,CAAC,CAAA,CAAC,gCAAgC;YACjE,IAAI,IAAI,CAAC,MAAM,KAAK,EAAE;gBAAE,OAAO,CAAC,CAAC,CAAA,CAAC,gCAAgC;YAClE,sFAAsF;YACtF,6EAA6E;YAC7E,0EAA0E;YAC1E,OAAO,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAC/C,CAAC;IACH,CAAC;IACD,OAAO,CAAC,CAAA;AACV,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,QAAgB,EAAE,QAAgB;IAC/D,OAAO,eAAe,CAAC,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAA;AAChD,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,mBAAmB,CAAA;AAEtD;;;;;;;GAOG;AACH,MAAM,UAAU,yBAAyB,CACvC,OAAe,EACf,UAAkB;IAElB,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,SAAS,CACjB,WAAW,UAAU,qBAAqB,OAAO,KAAK;YACpD,gEAAgE,CACnE,CAAA;IACH,CAAC;AACH,CAAC"}

package/dist/engines/base-engine.js

@@ -0,0 +1,179 @@
+import { UnsupportedOperationError } from '../core/error-handler.js';
+import { stopPgweb } from '../core/pgweb-utils.js';
+/**
+ * Base class for database engines
+ * All engines (PostgreSQL, MySQL, SQLite) should extend this class
+ */
+export class BaseEngine {
+    /**
+     * Get the path to the psql client if available
+     * Default implementation throws; engines that can provide a bundled or
+     * configured psql should override this method.
+     */
+    async getPsqlPath() {
+        throw new Error('psql not found');
+    }
+    /**
+     * Get the path to the mysql client if available
+     * Default implementation throws; engines that can provide a bundled or
+     * configured mysql should override this method.
+     */
+    async getMysqlClientPath() {
+        throw new Error('mysql client not found');
+    }
+    /**
+     * Get the path to the mariadb client if available
+     * Default implementation throws; MariaDB engine overrides this method.
+     */
+    async getMariadbClientPath() {
+        throw new Error('mariadb client not found');
+    }
+    /**
+     * Get the path to the mysqladmin client if available
+     * Default implementation throws; engines that can provide a bundled or
+     * configured mysqladmin should override this method.
+     */
+    async getMysqladminPath() {
+        throw new Error('mysqladmin not found');
+    }
+    /**
+     * Get the path to the mongosh client if available
+     * Default implementation throws; engines that can provide a bundled or
+     * configured mongosh should override this method.
+     */
+    async getMongoshPath() {
+        throw new Error('mongosh not found');
+    }
+    /**
+     * Get the path to the redis-cli client if available
+     * Default implementation throws; engines that can provide a bundled or
+     * configured redis-cli should override this method.
+     */
+    async getRedisCliPath() {
+        throw new Error('redis-cli not found');
+    }
+    /**
+     * Get the path to the valkey-cli client if available
+     * Default implementation throws; engines that can provide a bundled or
+     * configured valkey-cli should override this method.
+     */
+    async getValkeyCliPath() {
+        throw new Error('valkey-cli not found');
+    }
+    /**
+     * Get the path to the clickhouse client if available
+     * Default implementation throws; engines that can provide a bundled or
+     * configured clickhouse should override this method.
+     */
+    async getClickHouseClientPath() {
+        throw new Error('clickhouse client not found');
+    }
+    /**
+     * Get the path to the cockroach binary if available
+     * Default implementation throws; CockroachDB engine overrides this method.
+     */
+    async getCockroachPath(_version) {
+        throw new Error('cockroach not found');
+    }
+    /**
+     * Get the path to the surreal binary if available
+     * Default implementation throws; SurrealDB engine overrides this method.
+     */
+    async getSurrealPath(_version) {
+        throw new Error('surreal not found');
+    }
+    /**
+     * Get the path to the typedb console binary if available
+     * Default implementation throws; TypeDB engine overrides this method.
+     */
+    async getTypeDBConsolePath(_version) {
+        throw new Error('typedb_console_bin not found');
+    }
+    /**
+     * Get the path to the influxdb3 binary if available
+     * Default implementation throws; InfluxDB engine overrides this method.
+     */
+    async getInfluxDBPath(_version) {
+        throw new Error('influxdb3 not found');
+    }
+    /**
+     * Get the path to the tigerbeetle binary if available
+     * Default implementation throws; TigerBeetle engine overrides this method.
+     */
+    async getTigerBeetlePath(_version) {
+        throw new Error('tigerbeetle not found');
+    }
+    /**
+     * Get the path to the sqlite3 client if available
+     * Default implementation returns null; SQLite engine overrides this method.
+     */
+    async getSqlite3Path(_version) {
+        return null;
+    }
+    /**
+     * Get the path to the duckdb client if available
+     * Default implementation returns null; DuckDB engine overrides this method.
+     */
+    async getDuckDBPath(_version) {
+        return null;
+    }
+    /**
+     * Fetch all available versions from remote source (grouped by major version)
+     * Returns a map of major version -> array of full versions (sorted latest first)
+     * Falls back to hardcoded versions if network fails
+     */
+    async fetchAvailableVersions() {
+        // Default implementation returns supported versions as single-item arrays
+        const versions = {};
+        for (const v of this.supportedVersions) {
+            versions[v] = [v];
+        }
+        return versions;
+    }
+    /**
+     * Terminate all active connections to a database.
+     * Required before dropping a database that may have active connections.
+     * Default implementation is a no-op - engines that need it should override.
+     * @param container - The container configuration
+     * @param database - The database name to terminate connections for
+     */
+    async terminateConnections(_container, _database) {
+        // Default: no-op. Override in engines that support connection termination.
+    }
+    /**
+     * Stop pgweb if running for this container.
+     * Called from stop() in engines that support pgweb (PostgreSQL, CockroachDB, FerretDB).
+     */
+    async stopPgweb(containerName) {
+        await stopPgweb(containerName, this.name);
+    }
+    /**
+     * List all user databases on the server, excluding system databases.
+     * Used to sync the registry with actual databases on the server.
+     *
+     * System databases excluded by default:
+     * - PostgreSQL: template0, template1, postgres
+     * - MySQL/MariaDB: information_schema, mysql, performance_schema, sys
+     * - CockroachDB: defaultdb, postgres, system
+     *
+     * @param container - The container configuration
+     * @returns Array of database names (excluding system databases)
+     * @throws Error if the engine doesn't support multiple databases or listing
+     */
+    async listDatabases(_container) {
+        throw new UnsupportedOperationError('listDatabases', this.displayName);
+    }
+    /**
+     * Create a database user with the given credentials.
+     * Returns credentials including connection string.
+     *
+     * @param container - The container configuration
+     * @param options - Username, password, and optional target database
+     * @returns UserCredentials with connection info
+     * @throws UnsupportedOperationError for engines that don't support users (SQLite, DuckDB, QuestDB)
+     */
+    async createUser(_container, _options) {
+        throw new UnsupportedOperationError('createUser', this.displayName);
+    }
+}
+//# sourceMappingURL=base-engine.js.map

package/dist/engines/base-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-engine.js","sourceRoot":"","sources":["../../engines/base-engine.ts"],"names":[],"mappings":"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"}