@apache-arrow/adbc-driver-manager 0.23.0

package/dist/error.js

@@ -0,0 +1,43 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+/**
+ * Structured error class for ADBC operations.
+ */
+export class AdbcError extends Error {
+    code;
+    vendorCode;
+    sqlState;
+    constructor(message, code, vendorCode, sqlState) {
+        super(message);
+        this.name = 'AdbcError';
+        this.code = code;
+        this.vendorCode = vendorCode;
+        this.sqlState = sqlState;
+    }
+    /**
+     * Promotes a raw error thrown by the native binding into a structured AdbcError.
+     *
+     * Non-ADBC errors (e.g. a standard JS TypeError) are returned unmodified.
+     */
+    static fromError(err) {
+        if (err instanceof Error && err.name === 'AdbcError') {
+            const e = err;
+            return new AdbcError(e.message, e.code ?? 'UNKNOWN', e.vendorCode, e.sqlState);
+        }
+        return err;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+import { NativeAdbcConnection, NativeAdbcStatement } from '../binding.js';
+import type { AdbcDatabase as AdbcDatabaseInterface, AdbcConnection as AdbcConnectionInterface, AdbcStatement as AdbcStatementInterface, ConnectOptions, GetObjectsOptions, IngestOptions } from './types.js';
+import { LoadFlags, ObjectDepth, InfoCode, IngestMode } from './types.js';
+import { RecordBatchReader, Table, Schema } from 'apache-arrow';
+import { AdbcError } from './error.js';
+declare const asyncDisposeSymbol: any;
+export type { ConnectOptions, GetObjectsOptions, IngestOptions };
+export { AdbcError, LoadFlags, ObjectDepth, InfoCode, IngestMode };
+/**
+ * Represents an ADBC Database.
+ */
+export declare class AdbcDatabase implements AdbcDatabaseInterface {
+    [asyncDisposeSymbol]: () => Promise<void>;
+    private _inner;
+    constructor(options: ConnectOptions);
+    connect(): Promise<AdbcConnection>;
+    close(): Promise<void>;
+}
+/**
+ * Represents a single connection to a database.
+ */
+export declare class AdbcConnection implements AdbcConnectionInterface {
+    [asyncDisposeSymbol]: () => Promise<void>;
+    private _inner;
+    constructor(inner: NativeAdbcConnection);
+    createStatement(): Promise<AdbcStatement>;
+    setOption(key: string, value: string): void;
+    setAutoCommit(enabled: boolean): void;
+    setReadOnly(enabled: boolean): void;
+    getObjects(options?: GetObjectsOptions): Promise<Table>;
+    getTableSchema(options: {
+        catalog?: string;
+        dbSchema?: string;
+        tableName: string;
+    }): Promise<Schema>;
+    getTableTypes(): Promise<Table>;
+    getInfo(infoCodes?: InfoCode[]): Promise<Table>;
+    query(sql: string, params?: Table): Promise<Table>;
+    queryStream(sql: string, params?: Table): Promise<RecordBatchReader>;
+    private setIngestOptions;
+    ingest(tableName: string, data: Table, options?: IngestOptions): Promise<number>;
+    ingestStream(tableName: string, reader: RecordBatchReader, options?: IngestOptions): Promise<number>;
+    execute(sql: string, params?: Table): Promise<number>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * Represents a query statement.
+ */
+export declare class AdbcStatement implements AdbcStatementInterface {
+    [asyncDisposeSymbol]: () => Promise<void>;
+    private _inner;
+    constructor(inner: NativeAdbcStatement);
+    setSqlQuery(query: string): Promise<void>;
+    setOption(key: string, value: string): void;
+    /**
+     * Execute the query and return a RecordBatchReader.
+     *
+     * Per the ADBC spec, behavior is undefined if the statement is reused after
+     * calling executeQuery(). Create a new statement for each query.
+     */
+    executeQuery(): Promise<RecordBatchReader>;
+    executeUpdate(): Promise<number>;
+    bind(data: Table): Promise<void>;
+    bindStream(reader: RecordBatchReader): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/index.js

@@ -0,0 +1,386 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+import { NativeAdbcDatabase } from '../binding.js';
+import { LoadFlags, ObjectDepth, InfoCode, IngestMode } from './types.js';
+import { RecordBatchReader, Table, tableToIPC } from 'apache-arrow';
+import { AdbcError } from './error.js';
+// Safely define Symbol.asyncDispose for compatibility with Node.js environments older than v21.
+const asyncDisposeSymbol = Symbol.asyncDispose ?? Symbol('Symbol.asyncDispose');
+async function readerToTable(reader) {
+    const batches = [];
+    for await (const batch of reader) {
+        batches.push(batch);
+    }
+    return new Table(batches);
+}
+/**
+ * Converts the native result iterator into an Apache Arrow `RecordBatchReader`.
+ *
+ * The native iterator yields Arrow IPC stream bytes (schema + record batches) as a
+ * Node.js `Buffer`. Since `Buffer` is a subclass of `Uint8Array`, we can wrap the
+ * iterator directly as `AsyncIterable<Uint8Array>` and pass it to
+ * `RecordBatchReader.from()`, which accepts an async iterable of IPC bytes and
+ * returns a standard Arrow `RecordBatchReader`.
+ */
+async function iteratorToReader(iterator) {
+    const asyncIterable = {
+        [Symbol.asyncIterator]: async function* () {
+            try {
+                while (true) {
+                    const chunk = await iterator.next().catch((e) => {
+                        throw AdbcError.fromError(e);
+                    });
+                    if (!chunk) {
+                        break;
+                    }
+                    yield chunk;
+                }
+            }
+            finally {
+                try {
+                    iterator.close();
+                }
+                catch { }
+            }
+        },
+    };
+    return RecordBatchReader.from(asyncIterable);
+}
+export { AdbcError, LoadFlags, ObjectDepth, InfoCode, IngestMode };
+/**
+ * Represents an ADBC Database.
+ */
+export class AdbcDatabase {
+    _inner;
+    constructor(options) {
+        try {
+            this._inner = new NativeAdbcDatabase(options);
+        }
+        catch (e) {
+            throw AdbcError.fromError(e);
+        }
+    }
+    async connect() {
+        try {
+            const connInner = await this._inner.connect(null);
+            return new AdbcConnection(connInner);
+        }
+        catch (e) {
+            throw AdbcError.fromError(e);
+        }
+    }
+    async close() {
+        try {
+            await this._inner.close();
+        }
+        catch (e) {
+            throw AdbcError.fromError(e);
+        }
+    }
+    async [asyncDisposeSymbol]() {
+        return this.close();
+    }
+}
+/**
+ * Represents a single connection to a database.
+ */
+export class AdbcConnection {
+    _inner;
+    constructor(inner) {
+        this._inner = inner;
+    }
+    async createStatement() {
+        try {
+            const stmtInner = await this._inner.createStatement();
+            return new AdbcStatement(stmtInner);
+        }
+        catch (e) {
+            throw AdbcError.fromError(e);
+        }
+    }
+    setOption(key, value) {
+        try {
+            this._inner.setOption(key, value);
+        }
+        catch (e) {
+            throw AdbcError.fromError(e);
+        }
+    }
+    setAutoCommit(enabled) {
+        this.setOption('adbc.connection.autocommit', enabled ? 'true' : 'false');
+    }
+    setReadOnly(enabled) {
+        this.setOption('adbc.connection.read_only', enabled ? 'true' : 'false');
+    }
+    async getObjects(options) {
+        try {
+            const opts = {
+                depth: options?.depth ?? 0,
+                catalog: options?.catalog,
+                dbSchema: options?.dbSchema,
+                tableName: options?.tableName,
+                tableType: options?.tableType,
+                columnName: options?.columnName,
+            };
+            const iterator = await this._inner.getObjects(opts);
+            return readerToTable(await iteratorToReader(iterator));
+        }
+        catch (e) {
+            throw AdbcError.fromError(e);
+        }
+    }
+    async getTableSchema(options) {
+        try {
+            const buffer = await this._inner.getTableSchema(options);
+            const reader = RecordBatchReader.from(buffer);
+            if (!reader.schema) {
+                await reader.next();
+            }
+            return reader.schema;
+        }
+        catch (e) {
+            throw AdbcError.fromError(e);
+        }
+    }
+    async getTableTypes() {
+        try {
+            const iterator = await this._inner.getTableTypes();
+            return readerToTable(await iteratorToReader(iterator));
+        }
+        catch (e) {
+            throw AdbcError.fromError(e);
+        }
+    }
+    async getInfo(infoCodes) {
+        try {
+            const iterator = await this._inner.getInfo(infoCodes);
+            return readerToTable(await iteratorToReader(iterator));
+        }
+        catch (e) {
+            throw AdbcError.fromError(e);
+        }
+    }
+    async query(sql, params) {
+        return readerToTable(await this.queryStream(sql, params));
+    }
+    async queryStream(sql, params) {
+        const stmt = await this.createStatement();
+        try {
+            await stmt.setSqlQuery(sql);
+            if (params !== undefined) {
+                await stmt.bind(params);
+            }
+            return await stmt.executeQuery();
+        }
+        finally {
+            await stmt.close();
+        }
+    }
+    setIngestOptions(stmt, tableName, options) {
+        stmt.setOption('adbc.ingest.target_table', tableName);
+        stmt.setOption('adbc.ingest.mode', options?.mode ?? IngestMode.Create);
+        if (options?.catalog !== undefined) {
+            stmt.setOption('adbc.ingest.target_catalog', options.catalog);
+        }
+        if (options?.dbSchema !== undefined) {
+            stmt.setOption('adbc.ingest.target_db_schema', options.dbSchema);
+        }
+        if (options?.temporary === true) {
+            stmt.setOption('adbc.ingest.temporary', 'true');
+        }
+    }
+    async ingest(tableName, data, options) {
+        const stmt = await this.createStatement();
+        try {
+            this.setIngestOptions(stmt, tableName, options);
+            await stmt.bind(data);
+            return await stmt.executeUpdate();
+        }
+        finally {
+            await stmt.close();
+        }
+    }
+    async ingestStream(tableName, reader, options) {
+        const nativeStmt = (await this._inner.createStatement());
+        try {
+            this.setIngestOptions(nativeStmt, tableName, options);
+            await reader.open();
+            const schemaTable = new Table(reader.schema, []);
+            const schemaBytes = tableToIPC(schemaTable, 'stream');
+            const promise = nativeStmt.startBindStreamExecute(Buffer.from(schemaBytes));
+            let pushError;
+            try {
+                for await (const batch of reader) {
+                    const batchBytes = tableToIPC(new Table([batch]), 'stream');
+                    nativeStmt.pushBatch(Buffer.from(batchBytes));
+                }
+            }
+            catch (e) {
+                pushError = e;
+            }
+            finally {
+                nativeStmt.endStream();
+            }
+            const result = (await promise);
+            if (pushError)
+                throw pushError;
+            return result;
+        }
+        catch (e) {
+            throw AdbcError.fromError(e);
+        }
+        finally {
+            nativeStmt.close();
+        }
+    }
+    async execute(sql, params) {
+        const stmt = await this.createStatement();
+        try {
+            await stmt.setSqlQuery(sql);
+            if (params !== undefined) {
+                await stmt.bind(params);
+            }
+            return await stmt.executeUpdate();
+        }
+        finally {
+            await stmt.close();
+        }
+    }
+    async commit() {
+        try {
+            await this._inner.commit();
+        }
+        catch (e) {
+            throw AdbcError.fromError(e);
+        }
+    }
+    async rollback() {
+        try {
+            await this._inner.rollback();
+        }
+        catch (e) {
+            throw AdbcError.fromError(e);
+        }
+    }
+    async close() {
+        try {
+            await this._inner.close();
+        }
+        catch (e) {
+            throw AdbcError.fromError(e);
+        }
+    }
+    async [asyncDisposeSymbol]() {
+        return this.close();
+    }
+}
+/**
+ * Represents a query statement.
+ */
+export class AdbcStatement {
+    _inner;
+    constructor(inner) {
+        this._inner = inner;
+    }
+    async setSqlQuery(query) {
+        try {
+            this._inner.setSqlQuery(query);
+        }
+        catch (e) {
+            throw AdbcError.fromError(e);
+        }
+    }
+    setOption(key, value) {
+        try {
+            this._inner.setOption(key, value);
+        }
+        catch (e) {
+            throw AdbcError.fromError(e);
+        }
+    }
+    /**
+     * Execute the query and return a RecordBatchReader.
+     *
+     * Per the ADBC spec, behavior is undefined if the statement is reused after
+     * calling executeQuery(). Create a new statement for each query.
+     */
+    async executeQuery() {
+        try {
+            const iterator = await this._inner.executeQuery();
+            return iteratorToReader(iterator);
+        }
+        catch (e) {
+            throw AdbcError.fromError(e);
+        }
+    }
+    async executeUpdate() {
+        try {
+            const rows = await this._inner.executeUpdate();
+            return rows;
+        }
+        catch (e) {
+            throw AdbcError.fromError(e);
+        }
+    }
+    async bind(data) {
+        try {
+            const ipcBytes = tableToIPC(data, 'stream');
+            await this._inner.bind(Buffer.from(ipcBytes));
+        }
+        catch (e) {
+            throw AdbcError.fromError(e);
+        }
+    }
+    async bindStream(reader) {
+        try {
+            await reader.open();
+            const schemaTable = new Table(reader.schema, []);
+            const schemaBytes = tableToIPC(schemaTable, 'stream');
+            const bindPromise = this._inner.startBindStream(Buffer.from(schemaBytes));
+            let pushError;
+            try {
+                for await (const batch of reader) {
+                    const batchBytes = tableToIPC(new Table([batch]), 'stream');
+                    this._inner.pushBatch(Buffer.from(batchBytes));
+                }
+            }
+            catch (e) {
+                pushError = e;
+            }
+            finally {
+                this._inner.endStream();
+            }
+            await bindPromise;
+            if (pushError)
+                throw pushError;
+        }
+        catch (e) {
+            throw AdbcError.fromError(e);
+        }
+    }
+    async close() {
+        try {
+            await this._inner.close();
+        }
+        catch (e) {
+            throw AdbcError.fromError(e);
+        }
+    }
+    async [asyncDisposeSymbol]() {
+        return this.close();
+    }
+}