kysely 0.17.3 → 0.19.0

package/README.md

@@ -1,3 +1,5 @@
+[![Stand With Ukraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner2-direct.svg)](https://stand-with-ukraine.pp.ua)
+
 [![Discord](https://img.shields.io/discord/890118421587578920)](https://discord.gg/C9aJ49mCra)
 [![Tests](https://github.com/koskimas/kysely/actions/workflows/test.yml/badge.svg)](https://github.com/koskimas/kysely)
 
@@ -68,6 +70,7 @@ All you need to do is define an interface for each table in the database and pas
 interfaces to the `Kysely` constructor:
 
 ```ts
+import { Pool } from 'pg'
 import {
   Kysely,
   PostgresDialect,
@@ -123,9 +126,11 @@ interface Database {
 const db = new Kysely<Database>({
   // Use MysqlDialect for MySQL and SqliteDialect for SQLite.
   dialect: new PostgresDialect({
-    host: 'localhost',
-    database: 'kysely_test',
-  }),
+    pool: new Pool({
+      host: 'localhost',
+      database: 'kysely_test'
+    })
+  })
 })
 
 async function demo() {
@@ -317,6 +322,9 @@ need to depend on a typescript compiler, which most production environments don'
 have. You will probably want to add a simple migration script to your projects like this:
 
 ```ts
+import * as path from 'path'
+import { Pool } from 'pg'
+import { promises: fs } from 'fs'
 import {
   Kysely,
   Migrator,
@@ -327,17 +335,20 @@ import {
 async function migrateToLatest() {
   const db = new Kysely<Database>({
     dialect: new PostgresDialect({
-      host: 'localhost',
-      database: 'kysely_test',
+      pool: new Pool({
+        host: 'localhost',
+        database: 'kysely_test',
+      })
     }),
   })
 
   const migrator = new Migrator({
     db,
-    provider: new FileMigrationProvider(
-      // Path to the folder that contains all your migrations.
-      'some/path/to/migrations'
-    )
+    provider: new FileMigrationProvider({
+      fs,
+      path,
+      migrationFolder: 'some/path/to/migrations',
+    })
   })
 
   const { error, results } = await migrator.migrateToLatest()
@@ -374,9 +385,7 @@ Kysely doesn't include drivers for deno, but you can still use Kysely as a query
 or implement your own driver:
 
 ```ts
-// We use jsdeliver to get Kysely from npm. We also need to
-// import the `dist/esm/index-nodeless.js` file instead of the
-// root which has node dependencies.
+// We use jsdeliver to get Kysely from npm.
 import {
   DummyDriver,
   Generated,
@@ -384,7 +393,7 @@ import {
   PostgresAdapter,
   PostgresIntrospector,
   PostgresQueryCompiler,
-} from 'https://cdn.jsdelivr.net/npm/kysely/dist/esm/index-nodeless.js'
+} from 'https://cdn.jsdelivr.net/npm/kysely/dist/esm/index.js'
 
 interface Person {
   id: Generated<number>
@@ -423,9 +432,7 @@ console.log(sql.sql)
 
 # Browser
 
-Kysely also runs in the browser as long as you import the `dist/esm/index-nodeless.js`
-module instead of the root that has node dependencies. You can also import the
-`dist/cjs/index-nodeless.js` file if you are using commonjs modules instead of ESM.
+Kysely also runs in the browser:
 
 ```ts
 import {
@@ -435,7 +442,7 @@ import {
   SqliteAdapter,
   SqliteIntrospector,
   SqliteQueryCompiler,
-} from 'kysely/dist/esm/index-nodeless.js'
+} from 'kysely'
 
 interface Person {
   id: Generated<number>

package/dist/cjs/dialect/database-introspector.d.ts

@@ -3,8 +3,18 @@ import { ColumnDataType } from '../operation-node/data-type-node.js';
  * An interface for getting the database metadata (names of the tables and columns etc.)
  */
 export interface DatabaseIntrospector {
+    /**
+     * Get schema metadata.
+     */
+    getSchemas(): Promise<SchemaMetadata[]>;
+    /**
+     * Get table metadata.
+     */
+    getTables(options?: DatabaseMetadataOptions): Promise<TableMetadata[]>;
     /**
      * Get the database metadata such as table and column names.
+     *
+     * @deprecated Use getTables() instead.
      */
     getMetadata(options?: DatabaseMetadataOptions): Promise<DatabaseMetadata>;
 }
@@ -15,6 +25,9 @@ export interface DatabaseMetadataOptions {
      */
     withInternalKyselyTables: boolean;
 }
+export interface SchemaMetadata {
+    readonly name: string;
+}
 export interface DatabaseMetadata {
     /**
      * The tables found in the database.

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

@@ -2,223 +2,40 @@ import { DatabaseConnection } from '../../driver/database-connection.js';
 /**
  * Config for the MySQL dialect.
  *
- * This interface is equal to `mysql2` library's pool config.
- *
  * https://github.com/sidorares/node-mysql2#using-connection-pools
  */
 export interface MysqlDialectConfig {
     /**
-     * The MySQL user to authenticate as
-     */
-    user?: string;
-    /**
-     * The password of that MySQL user
-     */
-    password?: string;
-    /**
-     * Name of the database to use for this connection
-     */
-    database?: string;
-    /**
-     * The charset for the connection. This is called 'collation' in the SQL-level of MySQL (like utf8_general_ci).
-     * If a SQL-level charset is specified (like utf8mb4) then the default collation for that charset is used.
-     * (Default: 'UTF8_GENERAL_CI')
-     */
-    charset?: string;
-    /**
-     * The hostname of the database you are connecting to. (Default: localhost)
-     */
-    host?: string;
-    /**
-     * The port number to connect to. (Default: 3306)
-     */
-    port?: number;
-    /**
-     * The source IP address to use for TCP connection
-     */
-    localAddress?: string;
-    /**
-     * The path to a unix domain socket to connect to. When used host and port are ignored
-     */
-    socketPath?: string;
-    /**
-     * The timezone used to store local dates. (Default: 'local')
-     */
-    timezone?: string | 'local';
-    /**
-     * The milliseconds before a timeout occurs during the initial connection to the MySQL server. (Default: 10 seconds)
-     */
-    connectTimeout?: number;
-    /**
-     * Stringify objects instead of converting to values. (Default: 'false')
-     */
-    stringifyObjects?: boolean;
-    /**
-     * Allow connecting to MySQL instances that ask for the old (insecure) authentication method. (Default: false)
-     */
-    insecureAuth?: boolean;
-    /**
-     * Determines if column values should be converted to native JavaScript types. It is not recommended (and may go away / change in the future)
-     * to disable type casting, but you can currently do so on either the connection or query level. (Default: true)
-     *
-     * You can also specify a function (field: any, next: () => void) => {} to do the type casting yourself.
-     *
-     * WARNING: YOU MUST INVOKE the parser using one of these three field functions in your custom typeCast callback. They can only be called once.
-     *
-     * field.string()
-     * field.buffer()
-     * field.geometry()
-     *
-     * are aliases for
-     *
-     * parser.parseLengthCodedString()
-     * parser.parseLengthCodedBuffer()
-     * parser.parseGeometryValue()
-     *
-     * You can find which field function you need to use by looking at: RowDataPacket.prototype._typeCast
-     */
-    typeCast?: boolean | ((field: any, next: () => void) => any);
-    /**
-     * A custom query format function
-     */
-    queryFormat?: (query: string, values: any) => void;
-    /**
-     * When dealing with big numbers (BIGINT and DECIMAL columns) in the database, you should enable this option
-     * (Default: false)
-     */
-    supportBigNumbers?: boolean;
-    /**
-     * Enabling both supportBigNumbers and bigNumberStrings forces big numbers (BIGINT and DECIMAL columns) to be
-     * always returned as JavaScript String objects (Default: false). Enabling supportBigNumbers but leaving
-     * bigNumberStrings disabled will return big numbers as String objects only when they cannot be accurately
-     * represented with [JavaScript Number objects] (http://ecma262-5.com/ELS5_HTML.htm#Section_8.5)
-     * (which happens when they exceed the [-2^53, +2^53] range), otherwise they will be returned as Number objects.
-     * This option is ignored if supportBigNumbers is disabled.
-     */
-    bigNumberStrings?: boolean;
-    /**
-     * Force date types (TIMESTAMP, DATETIME, DATE) to be returned as strings rather then inflated into JavaScript Date
-     * objects. Can be true/false or an array of type names to keep as strings.
+     * A mysql2 Pool instance or a function that returns one.
      *
-     * (Default: false)
-     */
-    dateStrings?: boolean | Array<'TIMESTAMP' | 'DATETIME' | 'DATE'>;
-    /**
-     * This will print all incoming and outgoing packets on stdout.
-     * You can also restrict debugging to packet types by passing an array of types (strings) to debug;
+     * If a function is provided, it's called once when the first query is executed.
      *
-     * (Default: false)
+     * https://github.com/sidorares/node-mysql2#using-connection-pools
      */
-    debug?: any;
-    /**
-     * Generates stack traces on Error to include call site of library entrance ('long stack traces'). Slight
-     * performance penalty for most calls. (Default: true)
-     */
-    trace?: boolean;
-    /**
-     * Allow multiple MySQL statements per query. Be careful with this, it exposes you to SQL injection attacks. (Default: false)
-     */
-    multipleStatements?: boolean;
-    /**
-     * List of connection flags to use other than the default ones. It is also possible to blacklist default ones
-     */
-    flags?: Array<string>;
-    /**
-     * object with ssl parameters or a string containing name of ssl profile
-     */
-    ssl?: string | MysqlSslOptions;
-    /**
-     * Return each row as an array, not as an object.
-     * This is useful when you have duplicate column names.
-     * This can also be set in the `QueryOption` object to be applied per-query.
-     */
-    rowsAsArray?: boolean;
-    /**
-     * The milliseconds before a timeout occurs during the connection acquisition. This is slightly different from connectTimeout,
-     * because acquiring a pool connection does not always involve making a connection. (Default: 10 seconds)
-     */
-    acquireTimeout?: number;
-    /**
-     * Determines the pool's action when no connections are available and the limit has been reached. If true, the pool will queue
-     * the connection request and call it when one becomes available. If false, the pool will immediately call back with an error.
-     * (Default: true)
-     */
-    waitForConnections?: boolean;
-    /**
-     * The maximum number of connections to create at once. (Default: 10)
-     */
-    connectionLimit?: number;
-    /**
-     * The maximum number of connection requests the pool will queue before returning an error from getConnection. If set to 0, there
-     * is no limit to the number of queued connection requests. (Default: 0)
-     */
-    queueLimit?: number;
-    /**
-     * Enable keep-alive on the socket.  It's disabled by default, but the
-     * user can enable it and supply an initial delay.
-     */
-    enableKeepAlive?: true;
-    /**
-     * If keep-alive is enabled users can supply an initial delay.
-     */
-    keepAliveInitialDelay?: number;
-    charsetNumber?: number;
-    compress?: boolean;
-    authSwitchHandler?: (data: any, callback: () => void) => any;
-    connectAttributes?: {
-        [param: string]: any;
-    };
-    decimalNumbers?: boolean;
-    isServer?: boolean;
-    maxPreparedStatements?: number;
-    namedPlaceholders?: boolean;
-    nestTables?: boolean | string;
-    passwordSha1?: string;
-    pool?: any;
-    stream?: any;
-    uri?: string;
-    Promise?: any;
-    authPlugins?: {
-        [key: string]: any;
-    };
+    pool: MysqlPool | (() => Promise<MysqlPool>);
     /**
      * Called once for each created connection.
-     *
-     * This is a Kysely specific feature and does not come from the `mysql2` module.
      */
     onCreateConnection?: (connection: DatabaseConnection) => Promise<void>;
 }
-export interface MysqlSslOptions {
-    /**
-     * A string or buffer holding the PFX or PKCS12 encoded private key, certificate and CA certificates
-     */
-    pfx?: string;
-    /**
-     * A string holding the PEM encoded private key
-     */
-    key?: string;
-    /**
-     * A string of passphrase for the private key or pfx
-     */
-    passphrase?: string;
-    /**
-     * A string holding the PEM encoded certificate
-     */
-    cert?: string;
-    /**
-     * Either a string or list of strings of PEM encoded CA certificates to trust.
-     */
-    ca?: string | string[];
-    /**
-     * Either a string or list of strings of PEM encoded CRLs (Certificate Revocation List)
-     */
-    crl?: string | string[];
-    /**
-     * A string describing the ciphers to use or exclude
-     */
-    ciphers?: string;
-    /**
-     * You can also connect to a MySQL server without properly providing the appropriate CA to trust. You should not do this.
-     */
-    rejectUnauthorized?: boolean;
+/**
+ * This interface is the subset of mysql2 driver's `Pool` class that
+ * kysely needs.
+ *
+ * We don't use the type from `mysql2` here to not have a dependency to it.
+ *
+ * https://github.com/sidorares/node-mysql2#using-connection-pools
+ */
+export interface MysqlPool {
+    getConnection(callback: (error: unknown, connection: MysqlPoolConnection) => void): void;
+    end(callback: (error: unknown) => void): void;
+}
+export interface MysqlPoolConnection {
+    query(sql: string, parameters: ReadonlyArray<unknown>, callback: (error: unknown, result: MysqlQueryResult) => void): void;
+    release(): void;
+}
+export interface MysqlOkPacket {
+    affectedRows: number;
+    insertId: number;
 }
+export declare type MysqlQueryResult = MysqlOkPacket | Record<string, unknown>[];

package/dist/cjs/dialect/mysql/mysql-dialect.d.ts

@@ -8,9 +8,32 @@ import { MysqlDialectConfig } from './mysql-dialect-config.js';
 /**
  * MySQL dialect that uses the [mysql2](https://github.com/sidorares/node-mysql2#readme) library.
  *
- * The {@link MysqlDialectConfig | configuration} passed to the constructor
- * is given as-is to the mysql2 library's [createPool](https://github.com/sidorares/node-mysql2#using-connection-pools)
- * method.
+ * The constructor takes an instance of {@link MysqlDialectConfig}.
+ *
+ * ```ts
+ * import { createPool } from 'mysql2'
+ *
+ * new MysqlDialect({
+ *   pool: createPool({
+ *     database: 'some_db',
+ *     host: 'localhost',
+ *   })
+ * })
+ * ```
+ *
+ * If you want the pool to only be created once it's first used, `pool`
+ * can be a function:
+ *
+ * ```ts
+ * import { createPool } from 'mysql2'
+ *
+ * new MysqlDialect({
+ *   pool: async () => createPool({
+ *     database: 'some_db',
+ *     host: 'localhost',
+ *   })
+ * })
+ * ```
  */
 export declare class MysqlDialect implements Dialect {
     #private;

package/dist/cjs/dialect/mysql/mysql-dialect.js

@@ -5,18 +5,40 @@ const mysql_driver_js_1 = require("./mysql-driver.js");
 const mysql_query_compiler_js_1 = require("./mysql-query-compiler.js");
 const mysql_introspector_js_1 = require("./mysql-introspector.js");
 const mysql_adapter_js_1 = require("./mysql-adapter.js");
-const object_utils_js_1 = require("../../util/object-utils.js");
 /**
  * MySQL dialect that uses the [mysql2](https://github.com/sidorares/node-mysql2#readme) library.
  *
- * The {@link MysqlDialectConfig | configuration} passed to the constructor
- * is given as-is to the mysql2 library's [createPool](https://github.com/sidorares/node-mysql2#using-connection-pools)
- * method.
+ * The constructor takes an instance of {@link MysqlDialectConfig}.
+ *
+ * ```ts
+ * import { createPool } from 'mysql2'
+ *
+ * new MysqlDialect({
+ *   pool: createPool({
+ *     database: 'some_db',
+ *     host: 'localhost',
+ *   })
+ * })
+ * ```
+ *
+ * If you want the pool to only be created once it's first used, `pool`
+ * can be a function:
+ *
+ * ```ts
+ * import { createPool } from 'mysql2'
+ *
+ * new MysqlDialect({
+ *   pool: async () => createPool({
+ *     database: 'some_db',
+ *     host: 'localhost',
+ *   })
+ * })
+ * ```
  */
 class MysqlDialect {
     #config;
     constructor(config) {
-        this.#config = (0, object_utils_js_1.freeze)({ ...config });
+        this.#config = config;
     }
     createDriver() {
         return new mysql_driver_js_1.MysqlDriver(this.#config);

package/dist/cjs/dialect/mysql/mysql-driver.d.ts

@@ -1,9 +1,11 @@
-import { DatabaseConnection } from '../../driver/database-connection.js';
+import { DatabaseConnection, QueryResult } from '../../driver/database-connection.js';
 import { Driver, TransactionSettings } from '../../driver/driver.js';
-import { MysqlDialectConfig } from './mysql-dialect-config.js';
+import { CompiledQuery } from '../../query-compiler/compiled-query.js';
+import { MysqlDialectConfig, MysqlPoolConnection } from './mysql-dialect-config.js';
+declare const PRIVATE_RELEASE_METHOD: unique symbol;
 export declare class MysqlDriver implements Driver {
     #private;
-    constructor(config: MysqlDialectConfig);
+    constructor(configOrPool: MysqlDialectConfig);
     /**
      * Initializes the driver.
      *
@@ -35,9 +37,16 @@ export declare class MysqlDriver implements Driver {
     /**
      * Releases a connection back to the pool.
      */
-    releaseConnection(connection: DatabaseConnection): Promise<void>;
+    releaseConnection(connection: MysqlConnection): Promise<void>;
     /**
      * Destroys the driver and releases all resources.
      */
     destroy(): Promise<void>;
 }
+declare class MysqlConnection implements DatabaseConnection {
+    #private;
+    constructor(rawConnection: MysqlPoolConnection);
+    executeQuery<O>(compiledQuery: CompiledQuery): Promise<QueryResult<O>>;
+    [PRIVATE_RELEASE_METHOD](): void;
+}
+export {};

package/dist/cjs/dialect/mysql/mysql-driver.js

@@ -3,24 +3,19 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MysqlDriver = void 0;
 const compiled_query_js_1 = require("../../query-compiler/compiled-query.js");
 const object_utils_js_1 = require("../../util/object-utils.js");
+const stack_trace_utils_js_1 = require("../../util/stack-trace-utils.js");
 const PRIVATE_RELEASE_METHOD = Symbol();
 class MysqlDriver {
     #config;
     #connections = new WeakMap();
     #pool;
-    constructor(config) {
-        this.#config = (0, object_utils_js_1.freeze)({ ...config });
+    constructor(configOrPool) {
+        this.#config = (0, object_utils_js_1.freeze)({ ...configOrPool });
     }
     async init() {
-        // Import the `mysql2` module here instead at the top of the file
-        // so that this file can be loaded by node without `mysql2` driver
-        // installed. As you can see, there IS an import from `mysql2` at the
-        // top level too, but that's only for types. It doesn't get compiled
-        // into javascript. You can check the built javascript code.
-        const poolFactory = await importMysqlPoolFactory();
-        // Use the `mysql2` module's own pool. All drivers should use the
-        // pool provided by the database library if possible.
-        this.#pool = poolFactory(this.#config);
+        this.#pool = (0, object_utils_js_1.isFunction)(this.#config.pool)
+            ? await this.#config.pool()
+            : this.#config.pool;
     }
     async acquireConnection() {
         const rawConnection = await this.#acquireConnection();
@@ -31,7 +26,7 @@ class MysqlDriver {
             // The driver must take care of calling `onCreateConnection` when a new
             // connection is created. The `mysql2` module doesn't provide an async hook
             // for the connection creation. We need to call the method explicitly.
-            if (this.#config.onCreateConnection) {
+            if (this.#config?.onCreateConnection) {
                 await this.#config.onCreateConnection(connection);
             }
         }
@@ -63,8 +58,7 @@ class MysqlDriver {
         await connection.executeQuery(compiled_query_js_1.CompiledQuery.raw('rollback'));
     }
     async releaseConnection(connection) {
-        const mysqlConnection = connection;
-        mysqlConnection[PRIVATE_RELEASE_METHOD]();
+        connection[PRIVATE_RELEASE_METHOD]();
     }
     async destroy() {
         return new Promise((resolve, reject) => {
@@ -80,22 +74,8 @@ class MysqlDriver {
     }
 }
 exports.MysqlDriver = MysqlDriver;
-async function importMysqlPoolFactory() {
-    try {
-        // The imported module name must be a string literal to make
-        // some bundlers work. So don't move this code behind a helper
-        // for example.
-        const mysqlModule = await Promise.resolve().then(() => require('mysql2'));
-        if ((0, object_utils_js_1.isFunction)(mysqlModule.createPool)) {
-            return mysqlModule.createPool;
-        }
-        else {
-            return mysqlModule.default.createPool;
-        }
-    }
-    catch (error) {
-        throw new Error('MySQL client not installed. Please run `npm install mysql2`');
-    }
+function isOkPacket(obj) {
+    return (0, object_utils_js_1.isObject)(obj) && 'insertId' in obj && 'affectedRows' in obj;
 }
 class MysqlConnection {
     #rawConnection;
@@ -103,29 +83,34 @@ class MysqlConnection {
         this.#rawConnection = rawConnection;
     }
     async executeQuery(compiledQuery) {
-        const result = await this.#executeQuery(compiledQuery);
-        if (isOkPacket(result)) {
-            const { insertId, affectedRows } = result;
+        try {
+            const result = await this.#executeQuery(compiledQuery);
+            if (isOkPacket(result)) {
+                const { insertId, affectedRows } = result;
+                return {
+                    insertId: insertId !== undefined &&
+                        insertId !== null &&
+                        insertId.toString() !== '0'
+                        ? BigInt(insertId)
+                        : undefined,
+                    numUpdatedOrDeletedRows: affectedRows !== undefined && insertId !== null
+                        ? BigInt(affectedRows)
+                        : undefined,
+                    rows: [],
+                };
+            }
+            else if (Array.isArray(result)) {
+                return {
+                    rows: result,
+                };
+            }
             return {
-                insertId: insertId !== undefined &&
-                    insertId !== null &&
-                    insertId.toString() !== '0'
-                    ? BigInt(insertId)
-                    : undefined,
-                numUpdatedOrDeletedRows: affectedRows !== undefined && insertId !== null
-                    ? BigInt(affectedRows)
-                    : undefined,
                 rows: [],
             };
         }
-        else if (Array.isArray(result)) {
-            return {
-                rows: result,
-            };
+        catch (err) {
+            throw (0, stack_trace_utils_js_1.extendStackTrace)(err, new Error());
         }
-        return {
-            rows: [],
-        };
     }
     #executeQuery(compiledQuery) {
         return new Promise((resolve, reject) => {
@@ -143,6 +128,3 @@ class MysqlConnection {
         this.#rawConnection.release();
     }
 }
-function isOkPacket(obj) {
-    return (0, object_utils_js_1.isObject)(obj) && 'insertId' in obj && 'affectedRows' in obj;
-}

package/dist/cjs/dialect/mysql/mysql-introspector.d.ts

@@ -1,10 +1,20 @@
-import { DatabaseIntrospector, DatabaseMetadata, DatabaseMetadataOptions } from '../database-introspector.js';
+import { DatabaseIntrospector, DatabaseMetadata, DatabaseMetadataOptions, SchemaMetadata, TableMetadata } from '../database-introspector.js';
 import { Kysely } from '../../kysely.js';
 export declare class MysqlIntrospector implements DatabaseIntrospector {
     #private;
     constructor(db: Kysely<any>);
+    /**
+     * Get schema metadata.
+     */
+    getSchemas(): Promise<SchemaMetadata[]>;
+    /**
+     * Get table metadata.
+     */
+    getTables(options?: DatabaseMetadataOptions): Promise<TableMetadata[]>;
     /**
      * Get the database metadata such as table and column names.
+     *
+     * @deprecated Use getTables() instead.
      */
     getMetadata(options?: DatabaseMetadataOptions): Promise<DatabaseMetadata>;
 }