snowflake-kysely-dialect 0.1.0

package/README.md

@@ -0,0 +1,90 @@
+# snowflake-kysely-dialect
+
+A [Kysely](https://kysely.dev) dialect for [Snowflake](https://www.snowflake.com).
+
+## Installation
+
+```bash
+npm install snowflake-kysely-dialect kysely snowflake-sdk
+# or
+yarn add snowflake-kysely-dialect kysely snowflake-sdk
+```
+
+## Usage
+
+```ts
+import { Kysely } from 'kysely'
+import { SnowflakeDialect } from 'snowflake-kysely-dialect'
+
+interface Database {
+  users: {
+    id: number
+    name: string
+    email: string
+  }
+}
+
+const db = new Kysely<Database>({
+  dialect: new SnowflakeDialect({
+    connection: {
+      account: 'your-account',
+      username: 'your-username',
+      password: 'your-password',
+      database: 'your-database',
+      schema: 'your-schema',
+      warehouse: 'your-warehouse',
+    },
+  }),
+})
+
+// Select
+const users = await db.selectFrom('users').selectAll().execute()
+
+// Insert
+await db.insertInto('users').values({ id: 1, name: 'Alice', email: 'alice@example.com' }).execute()
+
+// Update
+await db.updateTable('users').set({ name: 'Bob' }).where('id', '=', 1).execute()
+
+// Delete
+await db.deleteFrom('users').where('id', '=', 1).execute()
+```
+
+## Transactions
+
+Transactions are fully supported:
+
+```ts
+await db.transaction().execute(async (trx) => {
+  await trx.insertInto('users').values({ id: 2, name: 'Carol', email: 'carol@example.com' }).execute()
+  await trx.updateTable('users').set({ name: 'Dave' }).where('id', '=', 1).execute()
+})
+```
+
+## Streaming
+
+```ts
+const stream = await db.selectFrom('users').selectAll().stream()
+
+for await (const row of stream) {
+  console.log(row)
+}
+```
+
+## Introspection
+
+```ts
+const tables = await db.introspection.getTables()
+```
+
+## Notes
+
+- Uses `PostgresQueryCompiler` under the hood — Snowflake's SQL dialect (double-quoted identifiers, window functions, standard string functions) is closer to Postgres than MySQL.
+- Uses a connection pool backed by `snowflake-sdk`'s built-in pool. Pool size and timeouts are configurable via the `poolOptions` config key.
+- `RETURNING` is not supported by Snowflake and is disabled in the adapter.
+- Snowflake folds unquoted identifiers to uppercase. Use quoted identifiers (via `sql.id(...)`) when you need case-sensitive names.
+- `VARIANT` / `OBJECT` columns (JSON), `TIMESTAMP_NTZ` / `TIMESTAMP_LTZ` / `TIMESTAMP_TZ`, and `NUMBER` precision are the most common sources of type round-tripping surprises — test these explicitly in your application.
+
+## License
+
+MIT

package/dist/SnowflakeAdapter.d.ts

@@ -0,0 +1,9 @@
+import { DialectAdapterBase, type Kysely, type MigrationLockOptions } from 'kysely';
+export declare class SnowflakeAdapter extends DialectAdapterBase {
+    get supportsTransactionalDdl(): boolean;
+    get supportsReturning(): boolean;
+    get supportsCreateIfNotExists(): boolean;
+    get supportsOutput(): boolean;
+    acquireMigrationLock(_db: Kysely<any>, _opt: MigrationLockOptions): Promise<void>;
+    releaseMigrationLock(_db: Kysely<any>, _opt: MigrationLockOptions): Promise<void>;
+}

package/dist/SnowflakeAdapter.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SnowflakeAdapter = void 0;
+const kysely_1 = require("kysely");
+class SnowflakeAdapter extends kysely_1.DialectAdapterBase {
+    get supportsTransactionalDdl() {
+        return true;
+    }
+    get supportsReturning() {
+        return false;
+    }
+    get supportsCreateIfNotExists() {
+        return true;
+    }
+    get supportsOutput() {
+        return false;
+    }
+    async acquireMigrationLock(_db, _opt) { }
+    async releaseMigrationLock(_db, _opt) { }
+}
+exports.SnowflakeAdapter = SnowflakeAdapter;

package/dist/SnowflakeConnection.d.ts

@@ -0,0 +1,11 @@
+import { type CompiledQuery, type DatabaseConnection, type QueryResult } from 'kysely';
+import { type Connection } from 'snowflake-sdk';
+export declare class SnowflakeConnection implements DatabaseConnection {
+    #private;
+    constructor(conn: Connection);
+    beginTransaction(): Promise<void>;
+    commitTransaction(): Promise<void>;
+    rollbackTransaction(): Promise<void>;
+    executeQuery<O>(compiledQuery: CompiledQuery): Promise<QueryResult<O>>;
+    streamQuery<O>(compiledQuery: CompiledQuery, _chunkSize: number): AsyncIterableIterator<QueryResult<O>>;
+}

package/dist/SnowflakeConnection.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SnowflakeConnection = void 0;
+class SnowflakeConnection {
+    #conn;
+    constructor(conn) {
+        this.#conn = conn;
+    }
+    async #executeRaw(sqlText) {
+        await new Promise((resolve, reject) => {
+            this.#conn.execute({
+                sqlText,
+                complete: (err) => {
+                    if (err)
+                        reject(err);
+                    else
+                        resolve();
+                },
+            });
+        });
+    }
+    async beginTransaction() {
+        await this.#executeRaw('BEGIN');
+    }
+    async commitTransaction() {
+        await this.#executeRaw('COMMIT');
+    }
+    async rollbackTransaction() {
+        await this.#executeRaw('ROLLBACK');
+    }
+    #translatePlaceholders(sql) {
+        return sql.replace(/\$\d+/g, '?');
+    }
+    async executeQuery(compiledQuery) {
+        const sqlText = this.#translatePlaceholders(compiledQuery.sql);
+        const binds = compiledQuery.parameters;
+        return new Promise((resolve, reject) => {
+            this.#conn.execute({
+                sqlText,
+                binds,
+                complete(err, stmt, rows) {
+                    if (err)
+                        return reject(err);
+                    const numUpdated = stmt.getNumUpdatedRows();
+                    if (numUpdated != null && numUpdated >= 0) {
+                        const n = BigInt(numUpdated);
+                        resolve({
+                            rows: (rows ?? []),
+                            numAffectedRows: n,
+                            numChangedRows: n,
+                        });
+                    }
+                    else {
+                        resolve({ rows: (rows ?? []) });
+                    }
+                },
+            });
+        });
+    }
+    async *streamQuery(compiledQuery, _chunkSize) {
+        const sqlText = this.#translatePlaceholders(compiledQuery.sql);
+        const binds = compiledQuery.parameters;
+        const readable = await new Promise((resolve, reject) => {
+            this.#conn.execute({
+                sqlText,
+                binds,
+                streamResult: true,
+                complete: (err, stmt) => {
+                    if (err)
+                        return reject(err);
+                    resolve(stmt.streamRows());
+                },
+            });
+        });
+        for await (const row of readable) {
+            yield { rows: [row] };
+        }
+    }
+}
+exports.SnowflakeConnection = SnowflakeConnection;

package/dist/SnowflakeDialect.d.ts

@@ -0,0 +1,15 @@
+import { type DatabaseIntrospector, type Dialect, type Driver, type Kysely, type QueryCompiler } from 'kysely';
+import type { ConnectionOptions, PoolOptions } from 'snowflake-sdk';
+import { SnowflakeAdapter } from './SnowflakeAdapter.js';
+export interface SnowflakeDialectConfig {
+    connection: ConnectionOptions;
+    poolOptions?: PoolOptions;
+}
+export declare class SnowflakeDialect implements Dialect {
+    #private;
+    constructor(config: SnowflakeDialectConfig);
+    createAdapter(): SnowflakeAdapter;
+    createDriver(): Driver;
+    createQueryCompiler(): QueryCompiler;
+    createIntrospector(db: Kysely<any>): DatabaseIntrospector;
+}

package/dist/SnowflakeDialect.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SnowflakeDialect = void 0;
+const kysely_1 = require("kysely");
+const SnowflakeAdapter_js_1 = require("./SnowflakeAdapter.js");
+const SnowflakeDriver_js_1 = require("./SnowflakeDriver.js");
+const SnowflakeIntrospector_js_1 = require("./SnowflakeIntrospector.js");
+class SnowflakeDialect {
+    #config;
+    constructor(config) {
+        this.#config = config;
+    }
+    createAdapter() {
+        return new SnowflakeAdapter_js_1.SnowflakeAdapter();
+    }
+    createDriver() {
+        return new SnowflakeDriver_js_1.SnowflakeDriver(this.#config);
+    }
+    createQueryCompiler() {
+        return new kysely_1.PostgresQueryCompiler();
+    }
+    createIntrospector(db) {
+        return new SnowflakeIntrospector_js_1.SnowflakeIntrospector(db);
+    }
+}
+exports.SnowflakeDialect = SnowflakeDialect;

package/dist/SnowflakeDriver.d.ts

@@ -0,0 +1,14 @@
+import { type DatabaseConnection, type Driver } from 'kysely';
+import { SnowflakeConnection } from './SnowflakeConnection.js';
+import { type SnowflakeDialectConfig } from './SnowflakeDialect.js';
+export declare class SnowflakeDriver implements Driver {
+    #private;
+    constructor(config: SnowflakeDialectConfig);
+    init(): Promise<void>;
+    acquireConnection(): Promise<DatabaseConnection>;
+    beginTransaction(conn: SnowflakeConnection): Promise<void>;
+    commitTransaction(conn: SnowflakeConnection): Promise<void>;
+    rollbackTransaction(conn: SnowflakeConnection): Promise<void>;
+    releaseConnection(conn: SnowflakeConnection): Promise<void>;
+    destroy(): Promise<void>;
+}

package/dist/SnowflakeDriver.js

@@ -0,0 +1,61 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SnowflakeDriver = void 0;
+const snowflake_sdk_1 = __importDefault(require("snowflake-sdk"));
+const SnowflakeConnection_js_1 = require("./SnowflakeConnection.js");
+const DEFAULT_POOL_OPTIONS = {
+    max: 10,
+    min: 2,
+    acquireTimeoutMillis: 60_000,
+    idleTimeoutMillis: 600_000,
+    evictionRunIntervalMillis: 300_000,
+};
+class SnowflakeDriver {
+    #config;
+    #pool = null;
+    #pendingReleases = new Map();
+    constructor(config) {
+        this.#config = config;
+    }
+    async init() {
+        this.#pool = snowflake_sdk_1.default.createPool(this.#config.connection, { ...DEFAULT_POOL_OPTIONS, ...this.#config.poolOptions });
+    }
+    async acquireConnection() {
+        return new Promise((resolveAcquire, rejectAcquire) => {
+            this.#pool.use(async (sdkConn) => {
+                const conn = new SnowflakeConnection_js_1.SnowflakeConnection(sdkConn);
+                return new Promise((resolveRelease) => {
+                    this.#pendingReleases.set(conn, resolveRelease);
+                    resolveAcquire(conn);
+                });
+            }).catch(rejectAcquire);
+        });
+    }
+    async beginTransaction(conn) {
+        return conn.beginTransaction();
+    }
+    async commitTransaction(conn) {
+        return conn.commitTransaction();
+    }
+    async rollbackTransaction(conn) {
+        return conn.rollbackTransaction();
+    }
+    async releaseConnection(conn) {
+        const release = this.#pendingReleases.get(conn);
+        if (release) {
+            this.#pendingReleases.delete(conn);
+            release();
+        }
+    }
+    async destroy() {
+        if (this.#pool) {
+            await this.#pool.drain();
+            this.#pool.clear();
+            this.#pool = null;
+        }
+    }
+}
+exports.SnowflakeDriver = SnowflakeDriver;

package/dist/SnowflakeIntrospector.d.ts

@@ -0,0 +1,8 @@
+import { type DatabaseIntrospector, type DatabaseMetadata, type DatabaseMetadataOptions, type Kysely, type SchemaMetadata, type TableMetadata } from 'kysely';
+export declare class SnowflakeIntrospector implements DatabaseIntrospector {
+    #private;
+    constructor(db: Kysely<any>);
+    getSchemas(): Promise<SchemaMetadata[]>;
+    getTables(options?: DatabaseMetadataOptions): Promise<TableMetadata[]>;
+    getMetadata(options?: DatabaseMetadataOptions): Promise<DatabaseMetadata>;
+}

package/dist/SnowflakeIntrospector.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SnowflakeIntrospector = void 0;
+const kysely_1 = require("kysely");
+class SnowflakeIntrospector {
+    #db;
+    constructor(db) {
+        this.#db = db;
+    }
+    async getSchemas() {
+        // Use uppercase table reference — PostgresQueryCompiler double-quotes identifiers,
+        // so lowercase "information_schema" would miss Snowflake's INFORMATION_SCHEMA.
+        const rows = await this.#db
+            .selectFrom('INFORMATION_SCHEMA.SCHEMATA')
+            .select('SCHEMA_NAME')
+            .$castTo()
+            .execute();
+        return rows.map((it) => ({ name: it.SCHEMA_NAME }));
+    }
+    async getTables(options = { withInternalKyselyTables: false }) {
+        let query = this.#db
+            .selectFrom('INFORMATION_SCHEMA.COLUMNS as columns')
+            .innerJoin('INFORMATION_SCHEMA.TABLES as tables', (b) => b
+            .onRef('columns.TABLE_CATALOG', '=', 'tables.TABLE_CATALOG')
+            .onRef('columns.TABLE_SCHEMA', '=', 'tables.TABLE_SCHEMA')
+            .onRef('columns.TABLE_NAME', '=', 'tables.TABLE_NAME'))
+            .select([
+            'columns.COLUMN_NAME',
+            'columns.COLUMN_DEFAULT',
+            'columns.TABLE_NAME',
+            'columns.TABLE_SCHEMA',
+            'tables.TABLE_TYPE',
+            'columns.IS_NULLABLE',
+            'columns.DATA_TYPE',
+            'columns.IS_IDENTITY',
+        ])
+            // Exclude the virtual INFORMATION_SCHEMA schema from results
+            .where('columns.TABLE_SCHEMA', '!=', 'INFORMATION_SCHEMA')
+            .orderBy('columns.TABLE_NAME')
+            .orderBy('columns.ORDINAL_POSITION')
+            .$castTo();
+        if (!options.withInternalKyselyTables) {
+            query = query
+                .where('columns.TABLE_NAME', '!=', kysely_1.DEFAULT_MIGRATION_TABLE)
+                .where('columns.TABLE_NAME', '!=', kysely_1.DEFAULT_MIGRATION_LOCK_TABLE);
+        }
+        const rawColumns = await query.execute();
+        return this.#parseTableMetadata(rawColumns);
+    }
+    async getMetadata(options) {
+        return {
+            tables: await this.getTables(options),
+        };
+    }
+    #parseTableMetadata(columns) {
+        return columns.reduce((tables, it) => {
+            let table = tables.find((tbl) => tbl.name === it.TABLE_NAME && tbl.schema === it.TABLE_SCHEMA);
+            if (!table) {
+                table = Object.freeze({
+                    name: it.TABLE_NAME,
+                    isView: it.TABLE_TYPE === 'VIEW',
+                    schema: it.TABLE_SCHEMA,
+                    columns: [],
+                });
+                tables.push(table);
+            }
+            table.columns.push(Object.freeze({
+                name: it.COLUMN_NAME,
+                dataType: it.DATA_TYPE,
+                isNullable: it.IS_NULLABLE === 'YES',
+                // Snowflake uses IDENTITY columns (sequences), not auto_increment
+                isAutoIncrementing: it.IS_IDENTITY === 'YES',
+                hasDefaultValue: it.COLUMN_DEFAULT !== null,
+            }));
+            return tables;
+        }, []);
+    }
+}
+exports.SnowflakeIntrospector = SnowflakeIntrospector;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './SnowflakeAdapter.js';
+export * from './SnowflakeConnection.js';
+export * from './SnowflakeDialect.js';
+export * from './SnowflakeDriver.js';
+export * from './SnowflakeIntrospector.js';

package/dist/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./SnowflakeAdapter.js"), exports);
+__exportStar(require("./SnowflakeConnection.js"), exports);
+__exportStar(require("./SnowflakeDialect.js"), exports);
+__exportStar(require("./SnowflakeDriver.js"), exports);
+__exportStar(require("./SnowflakeIntrospector.js"), exports);

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "snowflake-kysely-dialect",
+  "version": "0.1.0",
+  "description": "Snowflake dialect for Kysely",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "tsc",
+    "test": "vitest"
+  },
+  "keywords": [
+    "kysely",
+    "snowflake"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "kysely": "*",
+    "snowflake-sdk": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "kysely": "^0.28.0",
+    "snowflake-sdk": "^2.4.0",
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.1"
+  }
+}