@devxcrew/framework 0.1.10 → 0.1.12

package/dist/modules/database/database.provider.d.ts

@@ -0,0 +1,38 @@
+import type { Kysely } from "kysely";
+import { DatabaseExecution } from "./database.execution.js";
+import { ResumableTransfer } from "./database.transfer.js";
+import type { ConnectionTarget, DatabaseInfrastructureSchema, DatabaseProviderOptions } from "./common/database.types.js";
+export declare function createDatabaseProvider<Schema extends DatabaseInfrastructureSchema = DatabaseInfrastructureSchema>(environment?: NodeJS.ProcessEnv, options?: DatabaseProviderOptions<Schema>): {
+    database: Kysely<Schema>;
+    driver: "mariadb" | "sqlite";
+    masterData: DatabaseExecution<Schema>;
+    masterTransfers: ResumableTransfer<Schema>;
+    withConnection: <T>(target: ConnectionTarget, work: (database: Kysely<Schema>) => Promise<T>) => Promise<T>;
+    provisionConnection: (target: ConnectionTarget) => Promise<import("kysely/migration").MigrationResult[]>;
+    poolStats: () => {
+        capacity: number;
+        pools: number;
+        leased: number;
+    };
+    verify: () => Promise<void>;
+    connections: () => ({
+        state: string;
+        host: string;
+        port: number;
+        database: string;
+        name: string;
+        driver: "mariadb" | "sqlite";
+    } | {
+        state: string;
+        path: string;
+        name: string;
+        driver: "mariadb" | "sqlite";
+    })[];
+    execute: <T>(work: (connection: Kysely<Schema>) => Promise<T>) => Promise<T>;
+    transaction: <T>(work: (connection: Kysely<Schema>) => Promise<T>) => Promise<T>;
+    migrationStatus: () => Promise<readonly import("kysely/migration").MigrationInfo[]>;
+    migrate(): Promise<import("kysely/migration").MigrationResult[]>;
+    seed(): Promise<void>;
+    close: () => Promise<void>;
+};
+export type DatabaseProvider<Schema extends DatabaseInfrastructureSchema = DatabaseInfrastructureSchema> = ReturnType<typeof createDatabaseProvider<Schema>>;

package/dist/modules/database/database.provider.js

@@ -0,0 +1,39 @@
+import { DatabaseConnections } from "./database.connections.js";
+import { DatabaseExecution } from "./database.execution.js";
+import { ResumableTransfer } from "./database.transfer.js";
+import { createDatabaseMigrator, prepareMigrationStorage, } from "./database.migration.js";
+import { seedDatabase } from "./database.seed.js";
+export function createDatabaseProvider(environment = process.env, options = {}) {
+    const registry = new DatabaseConnections(environment);
+    // Drivers know infrastructure tables; the caller supplies its owner schema and migrations.
+    const database = registry.getMaster();
+    const migrator = createDatabaseMigrator(database, options.migrations);
+    return {
+        database,
+        driver: registry.driver,
+        masterData: new DatabaseExecution(database),
+        masterTransfers: new ResumableTransfer(database),
+        withConnection: (target, work) => registry.withConnection(target, (connection) => work(connection)),
+        provisionConnection: (target) => registry.provision(target),
+        poolStats: () => registry.poolStats(),
+        verify: () => registry.verify(),
+        connections: () => registry.list(),
+        execute: (work) => work(registry.getMaster()),
+        transaction: (work) => registry.getMaster()
+            .transaction()
+            .execute(work),
+        migrationStatus: () => migrator.getMigrations(),
+        async migrate() {
+            await prepareMigrationStorage(database, registry.driver);
+            const result = await migrator.migrateToLatest();
+            if (result.error)
+                throw result.error;
+            return result.results ?? [];
+        },
+        async seed() {
+            await seedDatabase(database, environment.APP_NAME ?? "Application");
+            await options.seed?.(database, environment);
+        },
+        close: () => registry.close(),
+    };
+}

package/dist/modules/database/database.repository.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/database/database.repository.js

@@ -0,0 +1 @@
+export {};

package/dist/modules/database/database.routes.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/database/database.routes.js

@@ -0,0 +1 @@
+export {};

package/dist/modules/database/database.schema.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/database/database.schema.js

@@ -0,0 +1 @@
+export {};

package/dist/modules/database/database.seed.d.ts

@@ -0,0 +1,3 @@
+import type { Kysely } from "kysely";
+import type { DatabaseSchema } from "./common/index.js";
+export declare function seedDatabase(database: Kysely<DatabaseSchema>, applicationName: string): Promise<void>;

package/dist/modules/database/database.seed.js

@@ -0,0 +1,7 @@
+export async function seedDatabase(database, applicationName) {
+    await database
+        .insertInto("application_metadata")
+        .values({ key: "application_name", value: applicationName })
+        .onConflict((conflict) => conflict.column("key").doNothing())
+        .execute();
+}

package/dist/modules/database/database.service.d.ts

@@ -0,0 +1,7 @@
+import type { DatabaseInfrastructureSchema, DatabaseProviderOptions } from "./common/database.types.js";
+/** Read-only engine readiness. Owner readiness is composed by the application. */
+export declare function smokeDatabase<Schema extends DatabaseInfrastructureSchema = DatabaseInfrastructureSchema>(environment?: NodeJS.ProcessEnv, options?: DatabaseProviderOptions<Schema>): Promise<{
+    readonly driver: "mariadb" | "sqlite";
+    readonly migrations: number;
+    readonly status: "ready";
+}>;

package/dist/modules/database/database.service.js

@@ -0,0 +1,24 @@
+import { access } from "node:fs/promises";
+import { createDatabaseProvider } from "./database.provider.js";
+import { readDatabaseConfiguration } from "./common/index.js";
+/** Read-only engine readiness. Owner readiness is composed by the application. */
+export async function smokeDatabase(environment = process.env, options = {}) {
+    const configuration = readDatabaseConfiguration(environment);
+    if (configuration.driver === "sqlite")
+        await access(configuration.path);
+    const provider = createDatabaseProvider(environment, options);
+    try {
+        const migrations = await provider.migrationStatus();
+        if (migrations.some((migration) => !migration.executedAt))
+            throw new Error("Database has pending migrations; run the application's migration command.");
+        await provider.verify();
+        return {
+            driver: provider.driver,
+            migrations: migrations.length,
+            status: "ready",
+        };
+    }
+    finally {
+        await provider.close();
+    }
+}

package/dist/modules/database/database.transfer.d.ts

@@ -0,0 +1,17 @@
+import type { Kysely, Transaction } from "kysely";
+import { z } from "zod";
+import type { DatabaseSchema } from "./common/index.js";
+/** Explicit chunk commits; data and checkpoint always commit together. */
+export declare class ResumableTransfer<Schema extends DatabaseSchema = DatabaseSchema> {
+    private readonly database;
+    constructor(database: Kysely<Schema>);
+    run<Row>(input: {
+        jobId: string;
+        sourceSha256: string;
+        batchSize?: number;
+    }, schema: z.ZodType<Row>, source: (cursor: number) => AsyncIterable<unknown> | Iterable<unknown>, write: (transaction: Transaction<Schema>, rows: readonly Row[]) => Promise<void>, signal?: AbortSignal): Promise<{
+        cursor: number;
+        committed: number;
+        jobId: string;
+    }>;
+}

package/dist/modules/database/database.transfer.js

@@ -0,0 +1,79 @@
+import { z } from "zod";
+import { iterateTransfer, DatabaseValidationError, } from "./database.execution.js";
+/** Explicit chunk commits; data and checkpoint always commit together. */
+export class ResumableTransfer {
+    database;
+    constructor(database) {
+        this.database = database;
+    }
+    async run(input, schema, source, write, signal) {
+        const job = z
+            .strictObject({
+            jobId: z.string().min(1).max(255),
+            sourceSha256: z.string().regex(/^[a-f0-9]{64}$/),
+            batchSize: z.number().int().min(1).max(500).default(100),
+        })
+            .parse(input);
+        signal?.throwIfAborted();
+        const checkpoints = this.database;
+        await checkpoints
+            .insertInto("transfer_checkpoints")
+            .values({ job_id: job.jobId, source_sha256: job.sourceSha256, cursor: 0 })
+            .onConflict((conflict) => conflict.column("job_id").doNothing())
+            .execute();
+        const checkpoint = await checkpoints
+            .selectFrom("transfer_checkpoints")
+            .selectAll()
+            .where("job_id", "=", job.jobId)
+            .executeTakeFirstOrThrow();
+        if (checkpoint.source_sha256 !== job.sourceSha256)
+            throw new Error("Transfer source fingerprint changed.");
+        let cursor = Number(checkpoint.cursor);
+        let version = Number(checkpoint.version);
+        let committed = 0;
+        let batch = [];
+        const flush = async () => {
+            const rows = batch;
+            await this.database.transaction().execute(async (transaction) => {
+                signal?.throwIfAborted();
+                const checkpointTransaction = transaction;
+                const current = await checkpointTransaction
+                    .selectFrom("transfer_checkpoints")
+                    .selectAll()
+                    .where("job_id", "=", job.jobId)
+                    .executeTakeFirstOrThrow();
+                if (Number(current.cursor) !== cursor ||
+                    Number(current.version) !== version ||
+                    current.source_sha256 !== job.sourceSha256)
+                    throw new Error("Transfer checkpoint changed; resume from persisted state.");
+                await write(transaction, rows);
+                signal?.throwIfAborted();
+                const result = await checkpointTransaction
+                    .updateTable("transfer_checkpoints")
+                    .set({ cursor: cursor + rows.length, version: version + 1 })
+                    .where("job_id", "=", job.jobId)
+                    .where("version", "=", version)
+                    .where("cursor", "=", cursor)
+                    .executeTakeFirst();
+                if (result.numUpdatedRows !== 1n)
+                    throw new Error("Concurrent transfer checkpoint update.");
+            });
+            cursor += rows.length;
+            committed += rows.length;
+            version++;
+            batch = [];
+        };
+        for await (const row of iterateTransfer(source(cursor), signal ?? AbortSignal.timeout(300_000))) {
+            signal?.throwIfAborted();
+            const parsed = schema.safeParse(row);
+            if (!parsed.success)
+                throw new DatabaseValidationError(parsed.error);
+            batch.push(parsed.data);
+            if (batch.length === job.batchSize)
+                await flush();
+        }
+        if (batch.length)
+            await flush();
+        return { cursor, committed, jobId: job.jobId };
+    }
+}

package/dist/modules/database/database.types.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/database/database.types.js

@@ -0,0 +1 @@
+export {};

package/dist/modules/database/drivers/mariadb/index.d.ts

@@ -0,0 +1,5 @@
+export { mariaDbConfig } from "./mariadb.schema.js";
+export { createMariaDbDialect } from "./mariadb.connection.js";
+export { MariaDbCompatibilityPlugin } from "./mariadb.compatibility.js";
+export { createMariaDbBackup, verifyMariaDbBackup, rehearseMariaDbRestore, } from "./mariadb.backup.js";
+export { ensureMariaDbDatabase } from "./mariadb.connection.js";

package/dist/modules/database/drivers/mariadb/index.js

@@ -0,0 +1,5 @@
+export { mariaDbConfig } from "./mariadb.schema.js";
+export { createMariaDbDialect } from "./mariadb.connection.js";
+export { MariaDbCompatibilityPlugin } from "./mariadb.compatibility.js";
+export { createMariaDbBackup, verifyMariaDbBackup, rehearseMariaDbRestore, } from "./mariadb.backup.js";
+export { ensureMariaDbDatabase } from "./mariadb.connection.js";

package/dist/modules/database/drivers/mariadb/mariadb.backup.d.ts

@@ -0,0 +1,3 @@
+export declare function createMariaDbBackup(environment: NodeJS.ProcessEnv, destination: string): Promise<void>;
+export declare function verifyMariaDbBackup(path: string): Promise<void>;
+export declare function rehearseMariaDbRestore(environment: NodeJS.ProcessEnv, path: string): Promise<void>;

package/dist/modules/database/drivers/mariadb/mariadb.backup.js

@@ -0,0 +1,141 @@
+import { spawn } from "node:child_process";
+import { createReadStream } from "node:fs";
+import { access, mkdir, mkdtemp, writeFile, readFile, link, rm, stat, } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { createHash, randomBytes } from "node:crypto";
+import mysql from "mysql2/promise";
+import { mariaDbConfig } from "./mariadb.schema.js";
+function option(value) {
+    return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("\n", "\\n").replaceAll("\r", "\\r")}"`;
+}
+async function withCredentials(environment, action) {
+    const config = mariaDbConfig(environment);
+    const base = resolve(environment.DB_BACKUP_DIR ?? "storage/private/data/backup");
+    await mkdir(base, { recursive: true });
+    const directory = await mkdtemp(join(base, ".mariadb-"));
+    const path = join(directory, "client.cnf");
+    try {
+        await writeFile(path, `[client]\nhost=${option(config.host)}\nport=${config.port}\nuser=${option(config.user)}\npassword=${option(config.password)}\n`, { mode: 0o600, flag: "wx" });
+        return await action(path);
+    }
+    finally {
+        await rm(directory, { recursive: true, force: true });
+    }
+}
+async function run(command, args, input) {
+    await new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            stdio: [input ? "pipe" : "ignore", "ignore", "ignore"],
+            windowsHide: true,
+        });
+        child.once("error", () => reject(new Error("MariaDB client executable unavailable; configure DB_DUMP_BIN and DB_CLIENT_BIN.")));
+        child.once("exit", (code) => code === 0
+            ? resolve()
+            : reject(new Error(`MariaDB client command failed (${code}).`)));
+        if (input) {
+            const stream = createReadStream(input);
+            stream.once("error", reject);
+            child.stdin.once("error", reject);
+            stream.pipe(child.stdin);
+        }
+    });
+}
+export async function createMariaDbBackup(environment, destination) {
+    const config = mariaDbConfig(environment);
+    const target = resolve(destination);
+    await mkdir(dirname(target), { recursive: true });
+    try {
+        await access(target);
+        throw new Error("Backup destination already exists.");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const directory = await mkdtemp(join(dirname(target), ".mariadb-snapshot-"));
+    const snapshot = join(directory, "snapshot.sql");
+    try {
+        await withCredentials(environment, (path) => run(environment.DB_DUMP_BIN || "mariadb-dump", [
+            `--defaults-extra-file=${path}`,
+            "--single-transaction",
+            "--quick",
+            "--hex-blob",
+            "--routines",
+            "--triggers",
+            `--result-file=${snapshot}`,
+            config.database,
+        ]));
+        if (!(await stat(snapshot)).size)
+            throw new Error("MariaDB dump was empty.");
+        const metadata = {
+            database: config.database,
+            createdAt: new Date().toISOString(),
+            sha256: await checksum(snapshot),
+        };
+        await link(snapshot, target);
+        await writeFile(`${target}.json`, JSON.stringify(metadata, null, 2) + "\n", {
+            flag: "wx",
+            mode: 0o600,
+        });
+    }
+    finally {
+        await rm(directory, { recursive: true, force: true });
+    }
+}
+export async function verifyMariaDbBackup(path) {
+    const metadata = JSON.parse(await readFile(`${path}.json`, "utf8"));
+    if (!(await stat(path)).size || (await checksum(path)) !== metadata.sha256)
+        throw new Error("MariaDB backup checksum failed.");
+}
+export async function rehearseMariaDbRestore(environment, path) {
+    await verifyMariaDbBackup(path);
+    const config = mariaDbConfig(environment);
+    const { database: master, ...connection } = config;
+    const target = `${master.slice(0, 32)}_restore_${randomBytes(6).toString("hex")}`;
+    if (target.length > 64)
+        throw new Error("Master name too long for an isolated restore database.");
+    const db = await mysql.createConnection(connection);
+    let created = false;
+    let userCreated = false;
+    const user = `restore_${randomBytes(8).toString("hex")}`;
+    const password = randomBytes(32).toString("base64url");
+    try {
+        await db.query(`CREATE DATABASE ${mysql.escapeId(target)} CHARACTER SET utf8mb4 COLLATE utf8mb4_bin`);
+        created = true;
+        await db.query("CREATE USER ?@'%' IDENTIFIED BY ?", [user, password]);
+        userCreated = true;
+        await db.query(`GRANT ALL PRIVILEGES ON ${mysql.escapeId(target)}.* TO ?@'%'`, [user]);
+        await withCredentials({ ...environment, DB_USER: user, DB_PASSWORD: password }, (credential) => run(environment.DB_CLIENT_BIN || "mariadb", [`--defaults-extra-file=${credential}`, "--batch", target], path));
+        const [tables] = await db.query("SELECT TABLE_NAME FROM information_schema.TABLES WHERE TABLE_SCHEMA=?", [target]);
+        if (!tables.length)
+            throw new Error("Restored database has no tables.");
+        for (const row of tables) {
+            const table = String(row.TABLE_NAME);
+            const [checks] = await db.query(`CHECK TABLE ${mysql.escapeId(target)}.${mysql.escapeId(table)}`);
+            if (!checks.some((check) => check.Msg_type === "status" && check.Msg_text === "OK"))
+                throw new Error(`Restore table check failed: ${table}`);
+        }
+        console.info(`Isolated restore passed: ${tables.length} tables checked.`);
+    }
+    finally {
+        try {
+            if (created)
+                await db.query(`DROP DATABASE ${mysql.escapeId(target)}`);
+        }
+        finally {
+            try {
+                if (userCreated)
+                    await db.query("DROP USER ?@'%'", [user]);
+            }
+            finally {
+                await db.end();
+            }
+        }
+    }
+}
+async function checksum(path) {
+    const hash = createHash("sha256");
+    for await (const chunk of createReadStream(path))
+        hash.update(chunk);
+    return hash.digest("hex");
+}

package/dist/modules/database/drivers/mariadb/mariadb.compatibility.d.ts

@@ -0,0 +1,6 @@
+import { type KyselyPlugin, type PluginTransformQueryArgs, type PluginTransformResultArgs } from "kysely";
+export declare class MariaDbCompatibilityPlugin implements KyselyPlugin {
+    private readonly transformer;
+    transformQuery(args: PluginTransformQueryArgs): import("kysely").RootOperationNode;
+    transformResult(args: PluginTransformResultArgs): Promise<import("kysely").QueryResult<import("kysely").UnknownRow>>;
+}

package/dist/modules/database/drivers/mariadb/mariadb.compatibility.js

@@ -0,0 +1,88 @@
+import { OperationNodeTransformer, ColumnUpdateNode, ReferenceNode, DataTypeNode, } from "kysely";
+// Translate portable SQLite SQL at the database boundary.
+// Values stay bound parameters; no business behavior or private package imports live here.
+class MariaDbTransformer extends OperationNodeTransformer {
+    transformColumnDefinition(node) {
+        const transformed = super.transformColumnDefinition(node);
+        if (transformed.column.column.name === "timestamp") {
+            return { ...transformed, dataType: DataTypeNode.create("datetime(3)") };
+        }
+        if (DataTypeNode.is(transformed.dataType) &&
+            transformed.dataType.dataType === "text") {
+            const name = transformed.column.column.name;
+            const indexed = name === "id" ||
+                name === "key" ||
+                name === "email" ||
+                name === "name" ||
+                name === "token_hash" ||
+                name.endsWith("_id") ||
+                name.endsWith("_at");
+            return indexed
+                ? { ...transformed, dataType: DataTypeNode.create("varchar(255)") }
+                : transformed;
+        }
+        return transformed;
+    }
+    transformInsertQuery(node) {
+        let transformed = super.transformInsertQuery(node);
+        if (transformed.into?.table.identifier.name === "migrations" &&
+            transformed.values) {
+            transformed = {
+                ...transformed,
+                values: new MigrationTimestampTransformer().transformNode(transformed.values),
+            };
+        }
+        const conflict = transformed.onConflict;
+        if (!conflict)
+            return transformed;
+        if (conflict.indexWhere ||
+            conflict.updateWhere ||
+            conflict.constraint ||
+            conflict.indexExpression) {
+            throw new Error("Unsupported MariaDB conflict target.");
+        }
+        const column = conflict.columns?.[0];
+        if (!conflict.updates && !column)
+            throw new Error("Missing MariaDB conflict column.");
+        return {
+            ...transformed,
+            onConflict: undefined,
+            onDuplicateKey: {
+                kind: "OnDuplicateKeyNode",
+                updates: conflict.updates ?? [
+                    ColumnUpdateNode.create(column, ReferenceNode.create(column)),
+                ],
+            },
+        };
+    }
+    transformRaw(node) {
+        const transformed = super.transformRaw(node);
+        return {
+            ...transformed,
+            sqlFragments: transformed.sqlFragments.map((fragment) => fragment.replace(/json_group_array\(\s*([a-zA-Z_][a-zA-Z0-9_.]*)\s*\)/g, "coalesce(json_arrayagg($1),json_array())")),
+        };
+    }
+}
+function migrationTimestamp(value) {
+    return typeof value === "string" &&
+        /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value)
+        ? value.replace("T", " ").replace("Z", "")
+        : value;
+}
+class MigrationTimestampTransformer extends OperationNodeTransformer {
+    transformValue(node) {
+        return { ...node, value: migrationTimestamp(node.value) };
+    }
+    transformPrimitiveValueList(node) {
+        return { ...node, values: node.values.map(migrationTimestamp) };
+    }
+}
+export class MariaDbCompatibilityPlugin {
+    transformer = new MariaDbTransformer();
+    transformQuery(args) {
+        return this.transformer.transformNode(args.node);
+    }
+    async transformResult(args) {
+        return args.result;
+    }
+}

package/dist/modules/database/drivers/mariadb/mariadb.connection.d.ts

@@ -0,0 +1,3 @@
+import { MysqlDialect } from "kysely";
+export declare function createMariaDbDialect(environment: NodeJS.ProcessEnv): MysqlDialect;
+export declare function ensureMariaDbDatabase(environment: NodeJS.ProcessEnv, name: string): Promise<void>;

package/dist/modules/database/drivers/mariadb/mariadb.connection.js

@@ -0,0 +1,22 @@
+import mysql from "mysql2/promise";
+import { createConnection, createPool } from "mysql2";
+import { MysqlDialect } from "kysely";
+import { mariaDbConfig } from "./mariadb.schema.js";
+export function createMariaDbDialect(environment) {
+    const config = mariaDbConfig(environment);
+    return new MysqlDialect({
+        pool: async () => createPool(config),
+        controlConnection: createConnection,
+    });
+}
+export async function ensureMariaDbDatabase(environment, name) {
+    const config = mariaDbConfig({ ...environment, DB_MASTER_NAME: name });
+    const { database, ...options } = config;
+    const connection = await mysql.createConnection(options);
+    try {
+        await connection.query(`CREATE DATABASE IF NOT EXISTS ${mysql.escapeId(database)} CHARACTER SET utf8mb4 COLLATE utf8mb4_bin`);
+    }
+    finally {
+        await connection.end();
+    }
+}

package/dist/modules/database/drivers/mariadb/mariadb.schema.d.ts

@@ -0,0 +1,14 @@
+export declare function mariaDbConfig(environment: NodeJS.ProcessEnv): {
+    host: string;
+    port: number;
+    user: string;
+    password: string;
+    database: string;
+    connectionLimit: number;
+    connectTimeout: number;
+    charset: string;
+    supportBigNumbers: boolean;
+    bigNumberStrings: boolean;
+    multipleStatements: boolean;
+    timezone: string;
+};

package/dist/modules/database/drivers/mariadb/mariadb.schema.js

@@ -0,0 +1,29 @@
+import { z } from "zod";
+const connectionSchema = z.object({
+    DB_HOST: z.string().trim().min(1),
+    DB_PORT: z.coerce.number().int().min(1).max(65535),
+    DB_USER: z.string().trim().min(1),
+    DB_PASSWORD: z.string().min(1),
+    DB_MASTER_NAME: z.string().regex(/^[a-zA-Z][a-zA-Z0-9_]{0,63}$/),
+});
+export function mariaDbConfig(environment) {
+    const result = connectionSchema.safeParse(environment);
+    if (!result.success) {
+        throw new Error(`Invalid MariaDB configuration: ${result.error.issues.map((i) => i.path.join(".")).join(", ")}`);
+    }
+    const value = result.data;
+    return {
+        host: value.DB_HOST,
+        port: value.DB_PORT,
+        user: value.DB_USER,
+        password: value.DB_PASSWORD,
+        database: value.DB_MASTER_NAME,
+        connectionLimit: 10,
+        connectTimeout: 10000,
+        charset: "utf8mb4_bin",
+        supportBigNumbers: true,
+        bigNumberStrings: true,
+        multipleStatements: false,
+        timezone: "Z",
+    };
+}

package/dist/modules/database/drivers/sqlite/index.d.ts

@@ -0,0 +1,3 @@
+export { NodeSqliteDatabase, createSqliteDialect, } from "./sqlite.connection.js";
+export { sqliteConfig } from "./sqlite.schema.js";
+export { createDatabaseBackup, verifyDatabaseBackup } from "./sqlite.backup.js";

package/dist/modules/database/drivers/sqlite/index.js

@@ -0,0 +1,3 @@
+export { NodeSqliteDatabase, createSqliteDialect, } from "./sqlite.connection.js";
+export { sqliteConfig } from "./sqlite.schema.js";
+export { createDatabaseBackup, verifyDatabaseBackup } from "./sqlite.backup.js";

package/dist/modules/database/drivers/sqlite/sqlite.backup.d.ts

@@ -0,0 +1,2 @@
+export declare function createDatabaseBackup(sourcePath: string, destinationPath: string): Promise<void>;
+export declare function verifyDatabaseBackup(path: string): void;

package/dist/modules/database/drivers/sqlite/sqlite.backup.js

@@ -0,0 +1,45 @@
+import { mkdir, mkdtemp, link, rm, access } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { DatabaseSync, backup } from "node:sqlite";
+export async function createDatabaseBackup(sourcePath, destinationPath) {
+    if (!sourcePath.trim() ||
+        !destinationPath.trim() ||
+        sourcePath === ":memory:") {
+        throw new Error("Backup requires a source file and a new destination file.");
+    }
+    const source = resolve(sourcePath);
+    const destination = resolve(destinationPath);
+    if (source === destination)
+        throw new Error("Backup destination must differ from its source.");
+    await access(source);
+    await mkdir(dirname(destination), { recursive: true });
+    const directory = await mkdtemp(join(dirname(destination), ".sqlite-backup-"));
+    const snapshot = join(directory, "snapshot.sqlite");
+    let database;
+    try {
+        database = new DatabaseSync(source, { readOnly: true });
+        await backup(database, snapshot);
+        verifyDatabaseBackup(snapshot);
+        // Exclusive linking preserves an existing destination and exposes only a complete snapshot.
+        await link(snapshot, destination);
+    }
+    finally {
+        database?.close();
+        await rm(directory, { recursive: true, force: true });
+    }
+}
+export function verifyDatabaseBackup(path) {
+    const database = new DatabaseSync(resolve(path), { readOnly: true });
+    try {
+        const checks = database.prepare("PRAGMA integrity_check").all();
+        if (checks.length !== 1 || checks[0].integrity_check !== "ok") {
+            throw new Error("SQLite backup integrity check failed.");
+        }
+        if (database.prepare("PRAGMA foreign_key_check").all().length) {
+            throw new Error("SQLite backup contains foreign key violations.");
+        }
+    }
+    finally {
+        database.close();
+    }
+}