kysely 0.28.16 → 0.28.18

package/dist/esm/dialect/mssql/mssql-adapter.d.ts

@@ -1,5 +1,6 @@
 import type { Kysely } from '../../kysely.js';
 import { DialectAdapterBase } from '../dialect-adapter-base.js';
+import type { MigrationLockOptions } from '../dialect-adapter.js';
 export declare class MssqlAdapter extends DialectAdapterBase {
     /**
      * Whether or not this dialect supports `if not exists` in creation of tables/schemas/views/etc.
@@ -70,7 +71,7 @@ export declare class MssqlAdapter extends DialectAdapterBase {
      * `db` is a single connection (session) that will be used to execute the
      * migrations.
      */
-    acquireMigrationLock(db: Kysely<any>): Promise<void>;
+    acquireMigrationLock(db: Kysely<any>, _opt: MigrationLockOptions): Promise<void>;
     /**
      * Releases the migration lock. See {@link acquireMigrationLock}.
      *
@@ -79,5 +80,5 @@ export declare class MssqlAdapter extends DialectAdapterBase {
      * is a single connection (session) that was used to execute the migrations
      * and the `acquireMigrationLock` call.
      */
-    releaseMigrationLock(): Promise<void>;
+    releaseMigrationLock(db: Kysely<any>, _opt: MigrationLockOptions): Promise<void>;
 }

package/dist/esm/dialect/mssql/mssql-adapter.js

@@ -2,6 +2,7 @@
 import { DEFAULT_MIGRATION_TABLE } from '../../migration/migrator.js';
 import { sql } from '../../raw-builder/sql.js';
 import { DialectAdapterBase } from '../dialect-adapter-base.js';
+const LOCK_PRINCIPAL = 'dbo';
 export class MssqlAdapter extends DialectAdapterBase {
     get supportsCreateIfNotExists() {
         return false;
@@ -12,14 +13,19 @@ export class MssqlAdapter extends DialectAdapterBase {
     get supportsOutput() {
         return true;
     }
-    async acquireMigrationLock(db) {
-        // Acquire a transaction-level exclusive lock on the migrations table.
+    async acquireMigrationLock(db, _opt) {
+        // Acquire a session-level exclusive lock on the migrations table. A
+        // session-level lock (as opposed to the default transaction-level lock)
+        // stays held after the migration transaction commits and until we release
+        // it explicitly in `releaseMigrationLock` OR the session ends. This way we
+        // know the lock is either released by us after successful or failed
+        // migrations OR it's released by SQL Server if the connection dies.
         // https://learn.microsoft.com/en-us/sql/relational-databases/system-stored-procedures/sp-getapplock-transact-sql?view=sql-server-ver16
-        await sql `exec sp_getapplock @DbPrincipal = ${sql.lit('dbo')}, @Resource = ${sql.lit(DEFAULT_MIGRATION_TABLE)}, @LockMode = ${sql.lit('Exclusive')}`.execute(db);
+        await sql `exec sp_getapplock @DbPrincipal = ${sql.lit(LOCK_PRINCIPAL)}, @Resource = ${sql.lit(DEFAULT_MIGRATION_TABLE)}, @LockMode = ${sql.lit('Exclusive')}, @LockOwner = ${sql.lit('Session')}`.execute(db);
     }
-    async releaseMigrationLock() {
-        // Nothing to do here. `sp_getapplock` is automatically released at the
-        // end of the transaction and since `supportsTransactionalDdl` true, we know
-        // the `db` instance passed to acquireMigrationLock is actually a transaction.
+    async releaseMigrationLock(db, _opt) {
+        // Release the session-level lock acquired in `acquireMigrationLock`.
+        // https://learn.microsoft.com/en-us/sql/relational-databases/system-stored-procedures/sp-releaseapplock-transact-sql?view=sql-server-ver16
+        await sql `exec sp_releaseapplock @DbPrincipal = ${sql.lit(LOCK_PRINCIPAL)}, @Resource = ${sql.lit(DEFAULT_MIGRATION_TABLE)}, @LockOwner = ${sql.lit('Session')}`.execute(db);
     }
 }

package/dist/esm/dialect/mysql/mysql-dialect-config.d.ts

@@ -10,6 +10,16 @@ export interface MysqlDialectConfig {
      *
      * If a function is provided, it's called once when the first query is executed.
      *
+     * Once the driver has initialized, {@link Kysely.destroy} calls
+     * `pool.end(callback)`, whether the pool is supplied directly or returned by a
+     * function. If initialization hasn't started, `db.destroy()` does nothing,
+     * even if the supplied pool has been used outside Kysely.
+     *
+     * If Kysely is not the sole consumer of the pool, or the pool's lifecycle is
+     * managed elsewhere, skip `db.destroy()`. Let the application call
+     * `pool.end(callback)` once all consumers, including Kysely, have finished. No
+     * separate cleanup of the `Kysely` instance is needed.
+     *
      * https://github.com/sidorares/node-mysql2#using-connection-pools
      */
     pool: MysqlPool | (() => Promise<MysqlPool>);

package/dist/esm/dialect/mysql/mysql-query-compiler.d.ts

@@ -17,5 +17,11 @@ export declare class MysqlQueryCompiler extends DefaultQueryCompiler {
      * @see https://dev.mysql.com/doc/refman/9.6/en/string-literals.html
      */
     protected sanitizeStringLiteral(value: string): string;
+    /**
+     * Member values appear inside `"..."` in the JSON path, which itself sits
+     * inside a SQL string literal. They must therefore be escaped twice — once
+     * for the JSON path grammar, then again for MySQL's string literal parser.
+     */
+    protected sanitizeJSONPathMemberValue(value: string): string;
     protected visitCreateIndex(node: CreateIndexNode): void;
 }

package/dist/esm/dialect/mysql/mysql-query-compiler.js

@@ -1,7 +1,8 @@
 /// <reference types="./mysql-query-compiler.d.ts" />
 import { DefaultQueryCompiler } from '../../query-compiler/default-query-compiler.js';
-const LITERAL_ESCAPE_REGEX = /\\|'/g;
+const LITERAL_ESCAPE_REGEX = /[\\']/g;
 const ID_WRAP_REGEX = /`/g;
+const JSON_PATH_MEMBER_ESCAPE_REGEX = /[\\'"]/g;
 export class MysqlQueryCompiler extends DefaultQueryCompiler {
     getCurrentParameterPlaceholder() {
         return '?';
@@ -37,6 +38,14 @@ export class MysqlQueryCompiler extends DefaultQueryCompiler {
     sanitizeStringLiteral(value) {
         return value.replace(LITERAL_ESCAPE_REGEX, (char) => char === '\\' ? '\\\\' : "''");
     }
+    /**
+     * Member values appear inside `"..."` in the JSON path, which itself sits
+     * inside a SQL string literal. They must therefore be escaped twice — once
+     * for the JSON path grammar, then again for MySQL's string literal parser.
+     */
+    sanitizeJSONPathMemberValue(value) {
+        return value.replace(JSON_PATH_MEMBER_ESCAPE_REGEX, (char) => char === '\\' ? '\\\\\\\\' : char === "'" ? "''" : '\\\\"');
+    }
     visitCreateIndex(node) {
         this.append('create ');
         if (node.unique) {

package/dist/esm/dialect/postgres/postgres-adapter.d.ts

@@ -76,5 +76,5 @@ export declare class PostgresAdapter extends DialectAdapterBase {
      * is a single connection (session) that was used to execute the migrations
      * and the `acquireMigrationLock` call.
      */
-    releaseMigrationLock(_db: Kysely<any>, _opt: MigrationLockOptions): Promise<void>;
+    releaseMigrationLock(db: Kysely<any>, _opt: MigrationLockOptions): Promise<void>;
 }

package/dist/esm/dialect/postgres/postgres-adapter.js

@@ -1,8 +1,8 @@
 /// <reference types="./postgres-adapter.d.ts" />
 import { sql } from '../../raw-builder/sql.js';
 import { DialectAdapterBase } from '../dialect-adapter-base.js';
-// Random id for our transaction lock.
 const LOCK_ID = BigInt('3853314791062309107');
+const LOCK_TIMEOUT_MILLISECONDS = 60 * 60 * 1_000;
 export class PostgresAdapter extends DialectAdapterBase {
     get supportsTransactionalDdl() {
         return true;
@@ -11,12 +11,18 @@ export class PostgresAdapter extends DialectAdapterBase {
         return true;
     }
     async acquireMigrationLock(db, _opt) {
-        // Acquire a transaction level advisory lock.
-        await sql `select pg_advisory_xact_lock(${sql.lit(LOCK_ID)})`.execute(db);
+        // in 1 RTT, acquire a session-level advisory lock with a timeout.
+        //
+        // if ever this runs inside a transaction, niche edge case we support - the
+        // user is responsible to set a different timeout value or disable (`0` value).
+        await sql `
+    with set_timeout as (
+      select set_config('lock_timeout', '${sql.lit(LOCK_TIMEOUT_MILLISECONDS)}', true) as config_val
+    )
+    select pg_advisory_lock(${sql.lit(LOCK_ID)})
+    from set_timeout`.execute(db);
     }
-    async releaseMigrationLock(_db, _opt) {
-        // Nothing to do here. `pg_advisory_xact_lock` is automatically released at the
-        // end of the transaction and since `supportsTransactionalDdl` true, we know
-        // the `db` instance passed to acquireMigrationLock is actually a transaction.
+    async releaseMigrationLock(db, _opt) {
+        await sql `select pg_advisory_unlock(${sql.lit(LOCK_ID)})`.execute(db);
     }
 }

package/dist/esm/dialect/postgres/postgres-dialect-config.d.ts

@@ -8,6 +8,16 @@ export interface PostgresDialectConfig {
      *
      * If a function is provided, it's called once when the first query is executed.
      *
+     * Once the driver has initialized, {@link Kysely.destroy} calls `pool.end()`,
+     * whether the pool is supplied directly or returned by a function. If
+     * initialization hasn't started, `db.destroy()` does nothing, even if the
+     * supplied pool has been used outside Kysely.
+     *
+     * If Kysely is not the sole consumer of the pool, or the pool's lifecycle is
+     * managed elsewhere, skip `db.destroy()`. Let the application call `pool.end()`
+     * once all consumers, including Kysely, have finished. No separate cleanup of
+     * the `Kysely` instance is needed.
+     *
      * https://node-postgres.com/apis/pool
      */
     pool: PostgresPool | (() => Promise<PostgresPool>);

package/dist/esm/dialect/postgres/postgres-driver.js

@@ -19,6 +19,11 @@ export class PostgresDriver {
     }
     async acquireConnection() {
         const client = await this.#pool.connect();
+        // `destroy` was called while the connection was being acquired.
+        if (!this.#pool) {
+            client.release();
+            throw new Error('driver has already been destroyed');
+        }
         let connection = this.#connections.get(client);
         if (!connection) {
             connection = new PostgresConnection(client, {

package/dist/esm/dialect/postgres/postgres-introspector.js

@@ -71,20 +71,26 @@ export class PostgresIntrospector {
         };
     }
     #parseTableMetadata(columns) {
-        const tableDictionary = new Map();
-        for (let i = 0, len = columns.length; i < len; i++) {
-            const column = columns[i];
-            const { schema, table } = column;
-            const tableKey = `schema:${schema};table:${table}`;
-            if (!tableDictionary.has(tableKey)) {
-                tableDictionary.set(tableKey, freeze({
+        const tables = [];
+        const schemas = new Map();
+        for (const column of columns) {
+            let schema = schemas.get(column.schema);
+            if (!schema) {
+                schema = new Map();
+                schemas.set(column.schema, schema);
+            }
+            let table = schema.get(column.table);
+            if (!table) {
+                table = freeze({
                     columns: [],
                     isView: column.table_type === 'v',
-                    name: table,
-                    schema,
-                }));
+                    name: column.table,
+                    schema: column.schema,
+                });
+                schema.set(column.table, table);
+                tables.push(table);
             }
-            tableDictionary.get(tableKey).columns.push(freeze({
+            table.columns.push(freeze({
                 comment: column.column_description ?? undefined,
                 dataType: column.type,
                 dataTypeSchema: column.type_schema,
@@ -94,6 +100,6 @@ export class PostgresIntrospector {
                 name: column.column,
             }));
         }
-        return Array.from(tableDictionary.values());
+        return tables;
     }
 }

package/dist/esm/dialect/sqlite/sqlite-dialect-config.d.ts

@@ -8,6 +8,16 @@ export interface SqliteDialectConfig {
      *
      * If a function is provided, it's called once when the first query is executed.
      *
+     * Once the driver has initialized, {@link Kysely.destroy} calls
+     * `database.close()`, whether the database is supplied directly or returned by
+     * a function. If initialization hasn't started, `db.destroy()` does nothing,
+     * even if the supplied database has been used outside Kysely.
+     *
+     * If Kysely is not the sole consumer of the database, or the database's
+     * lifecycle is managed elsewhere, skip `db.destroy()`. Let the application
+     * call `database.close()` once all consumers, including Kysely, have finished.
+     * No separate cleanup of the `Kysely` instance is needed.
+     *
      * https://github.com/JoshuaWise/better-sqlite3/blob/master/docs/api.md#new-databasepath-options
      */
     database: SqliteDatabase | (() => Promise<SqliteDatabase>);

package/dist/esm/dialect/sqlite/sqlite-query-compiler.d.ts

@@ -10,5 +10,6 @@ export declare class SqliteQueryCompiler extends DefaultQueryCompiler {
     protected getRightIdentifierWrapper(): string;
     protected getAutoIncrement(): string;
     protected sanitizeIdentifier(identifier: string): string;
+    protected sanitizeJSONPathMemberValue(value: string): string;
     protected visitDefaultInsertValue(_: DefaultInsertValueNode): void;
 }

package/dist/esm/dialect/sqlite/sqlite-query-compiler.js

@@ -1,6 +1,7 @@
 /// <reference types="./sqlite-query-compiler.d.ts" />
 import { DefaultQueryCompiler } from '../../query-compiler/default-query-compiler.js';
 const ID_WRAP_REGEX = /"/g;
+const JSON_PATH_MEMBER_ESCAPE_REGEX = /[\\'"]/g;
 export class SqliteQueryCompiler extends DefaultQueryCompiler {
     visitOrAction(node) {
         this.append('or ');
@@ -27,6 +28,9 @@ export class SqliteQueryCompiler extends DefaultQueryCompiler {
     sanitizeIdentifier(identifier) {
         return identifier.replace(ID_WRAP_REGEX, '""');
     }
+    sanitizeJSONPathMemberValue(value) {
+        return value.replace(JSON_PATH_MEMBER_ESCAPE_REGEX, (char) => char === '\\' ? '\\\\' : char === "'" ? "''" : '\\"');
+    }
     visitDefaultInsertValue(_) {
         // sqlite doesn't support the `default` keyword in inserts.
         this.append('null');

package/dist/esm/helpers/mssql.d.ts

@@ -202,7 +202,9 @@ export declare function jsonObjectFrom<O>(expr: Expression<O>): RawBuilder<Simpl
  *
  * ```sql
  * select "id", json_query(
- *   '{"first":"'+"first_name"+',"last":"'+"last_name"+',"full":"'+concat("first_name", ' ', "last_name")+'"}'
+ *   '{"'+string_escape(N'first', 'json')+'":"'+string_escape("first_name", 'json')+
+ *   '","'+string_escape(N'last', 'json')+'":"'+string_escape("last_name", 'json')+
+ *   '","'+string_escape(N'full', 'json')+'":"'+string_escape(concat("first_name", ' ', "last_name"), 'json')+'"}'
  * ) as "name"
  * from "person"
  * ```

package/dist/esm/helpers/mssql.js

@@ -205,11 +205,13 @@ export function jsonObjectFrom(expr) {
  *
  * ```sql
  * select "id", json_query(
- *   '{"first":"'+"first_name"+',"last":"'+"last_name"+',"full":"'+concat("first_name", ' ', "last_name")+'"}'
+ *   '{"'+string_escape(N'first', 'json')+'":"'+string_escape("first_name", 'json')+
+ *   '","'+string_escape(N'last', 'json')+'":"'+string_escape("last_name", 'json')+
+ *   '","'+string_escape(N'full', 'json')+'":"'+string_escape(concat("first_name", ' ', "last_name"), 'json')+'"}'
  * ) as "name"
  * from "person"
  * ```
  */
 export function jsonBuildObject(obj) {
-    return sql `json_query('{${sql.join(Object.keys(obj).map((k) => sql `"${sql.raw(k)}":"'+${obj[k]}+'"`), sql `,`)}}')`;
+    return sql `json_query('{${sql.join(Object.keys(obj).map((k) => sql `"'+string_escape(N${sql.lit(k)}, 'json')+'":"'+string_escape(${obj[k]}, 'json')+'"`), sql `,`)}}')`;
 }

package/dist/esm/kysely.d.ts

@@ -29,7 +29,8 @@ declare global {
  * The main Kysely class.
  *
  * You should create one instance of `Kysely` per database using the {@link Kysely}
- * constructor. Each `Kysely` instance maintains its own connection pool.
+ * constructor. The dialect manages database connections and may use a shared
+ * pool or database instance.
  *
  * ### Examples
  *
@@ -384,7 +385,16 @@ export declare class Kysely<DB> extends QueryCreator<DB> implements QueryExecuto
     /**
      * Releases all resources and disconnects from the database.
      *
-     * You need to call this when you are done using the `Kysely` instance.
+     * Call this when you are done using the `Kysely` instance and Kysely is
+     * responsible for closing its connections, pool, or database instance.
+     *
+     * If the pool or database instance is shared with other consumers or its
+     * lifecycle is managed elsewhere, skip this call. Let the application close it
+     * once all consumers, including Kysely, have finished. No separate cleanup of
+     * the `Kysely` instance is needed.
+     *
+     * The driver is initialized lazily. If initialization hasn't started, this
+     * method does nothing.
      */
     destroy(): Promise<void>;
     /**
@@ -511,7 +521,16 @@ export declare class Transaction<DB> extends Kysely<DB> {
     /**
      * Releases all resources and disconnects from the database.
      *
-     * You need to call this when you are done using the `Kysely` instance.
+     * Call this when you are done using the `Kysely` instance and Kysely is
+     * responsible for closing its connections, pool, or database instance.
+     *
+     * If the pool or database instance is shared with other consumers or its
+     * lifecycle is managed elsewhere, skip this call. Let the application close it
+     * once all consumers, including Kysely, have finished. No separate cleanup of
+     * the `Kysely` instance is needed.
+     *
+     * The driver is initialized lazily. If initialization hasn't started, this
+     * method does nothing.
      */
     destroy(): Promise<void>;
     /**
@@ -646,6 +665,10 @@ export declare class ControlledTransaction<DB, S extends string[] = []> extends
     /**
      * Commits the transaction.
      *
+     * Waits for ongoing queries to finish. Streams must be exhausted or closed
+     * before awaiting this command. When consuming a stream with `for await`,
+     * exit the loop before committing.
+     *
      * See {@link rollback}.
      *
      * ### Examples
@@ -671,6 +694,13 @@ export declare class ControlledTransaction<DB, S extends string[] = []> extends
     /**
      * Rolls back the transaction.
      *
+     * The connection is released even if the rollback fails, so the transaction
+     * cannot be used afterwards in either case.
+     *
+     * Waits for ongoing queries to finish. Streams must be exhausted or closed
+     * before awaiting this command. When consuming a stream with `for await`,
+     * exit the loop before rolling back.
+     *
      * See {@link commit} and {@link rollbackToSavepoint}.
      *
      * ### Examples
@@ -696,6 +726,10 @@ export declare class ControlledTransaction<DB, S extends string[] = []> extends
     /**
      * Creates a savepoint with a given name.
      *
+     * Waits for ongoing queries to finish. Streams must be exhausted or closed
+     * before awaiting this command. When consuming a stream with `for await`,
+     * exit the loop before creating a savepoint.
+     *
      * See {@link rollbackToSavepoint} and {@link releaseSavepoint}.
      *
      * For a type-safe experience, you should use the returned instance from now on.
@@ -726,6 +760,10 @@ export declare class ControlledTransaction<DB, S extends string[] = []> extends
     /**
      * Rolls back to a savepoint with a given name.
      *
+     * Waits for ongoing queries to finish. Streams must be exhausted or closed
+     * before awaiting this command. When consuming a stream with `for await`,
+     * exit the loop before rolling back to a savepoint.
+     *
      * See {@link savepoint} and {@link releaseSavepoint}.
      *
      * You must use the same instance returned by {@link savepoint}, or
@@ -757,6 +795,10 @@ export declare class ControlledTransaction<DB, S extends string[] = []> extends
     /**
      * Releases a savepoint with a given name.
      *
+     * Waits for ongoing queries to finish. Streams must be exhausted or closed
+     * before awaiting this command. When consuming a stream with `for await`,
+     * exit the loop before releasing a savepoint.
+     *
      * See {@link savepoint} and {@link rollbackToSavepoint}.
      *
      * You must use the same instance returned by {@link savepoint}, or
@@ -834,8 +876,13 @@ export declare class ControlledTransaction<DB, S extends string[] = []> extends
      */
     withTables<T extends Record<string, Record<string, any>>>(): ControlledTransaction<DrainOuterGeneric<DB & T>, S>;
 }
+interface ControlledTransctionState {
+    isCommitted: boolean;
+    isRolledBack: boolean;
+}
 interface ControlledTransactionProps extends KyselyProps {
     readonly connection: ControlledConnection;
+    readonly state?: ControlledTransctionState;
 }
 export declare class Command<T> {
     #private;