zeroshade commented on code in PR #4046: URL: https://github.com/apache/arrow-adbc/pull/4046#discussion_r2892757878
########## javascript/lib/index.ts: ########## @@ -0,0 +1,321 @@ +// 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, NativeAdbcConnection, NativeAdbcStatement } from '../binding.js' + +import type { + AdbcDatabase as AdbcDatabaseInterface, + AdbcConnection as AdbcConnectionInterface, + AdbcStatement as AdbcStatementInterface, + ConnectOptions, + GetObjectsOptions, +} from './types.js' + +import { RecordBatchReader, RecordBatch, Table, tableToIPC, Schema } from 'apache-arrow' +import { AdbcError } from './error.js' + +// Safely define Symbol.asyncDispose for compatibility with Node.js environments older than v21. +const asyncDisposeSymbol = (Symbol as any).asyncDispose ?? Symbol('Symbol.asyncDispose') + +type NativeIterator = { next(): Promise<Buffer | null | undefined>; close(): void } + +async function iteratorToReader(iterator: NativeIterator): Promise<RecordBatchReader> { Review Comment: what is this used for / how does this get from a uint8array to being a recordbatch reader? I'm likely just missing something, but we should probably add comments / document what this is *actually* doing, yes? ########## javascript/lib/types.ts: ########## @@ -0,0 +1,264 @@ +// 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 { RecordBatch, RecordBatchReader, Table, Schema } from 'apache-arrow' + +/** + * Options for connecting to a driver/database. + * + * These options configure how the ADBC driver is loaded and how the initial connection is established. + */ +export interface ConnectOptions { + /** + * Path to the driver library or short name of the driver. + * Short names (e.g. "sqlite") work when the corresponding ADBC driver is installed on the system. + * Full paths to a .so/.dylib/.dll or a manifest .toml file are also accepted. + */ + driver: string Review Comment: the driver manager also accepts a URI here (such as `postgresql://.......` or `sqlite:file::memory:`, or even `profile://path/to/profile` ########## javascript/lib/types.ts: ########## @@ -0,0 +1,264 @@ +// 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 { RecordBatch, RecordBatchReader, Table, Schema } from 'apache-arrow' + +/** + * Options for connecting to a driver/database. + * + * These options configure how the ADBC driver is loaded and how the initial connection is established. + */ +export interface ConnectOptions { + /** + * Path to the driver library or short name of the driver. + * Short names (e.g. "sqlite") work when the corresponding ADBC driver is installed on the system. + * Full paths to a .so/.dylib/.dll or a manifest .toml file are also accepted. + */ + driver: string + /** + * Name of the entrypoint function (optional). + * If not provided, ADBC will attempt to guess the entrypoint symbol name based on the driver name. + */ + entrypoint?: string + /** + * Paths to search for the driver (optional). + * Useful if the driver is not in the standard library paths. + */ + searchPaths?: string[] + /** + * Load flags (optional). + * Bitmask controlling how the driver is loaded (e.g., search system paths, search user paths). + */ + loadFlags?: number Review Comment: should we also export constants for these flags and document the default behavior? ########## javascript/lib/types.ts: ########## @@ -0,0 +1,264 @@ +// 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 { RecordBatch, RecordBatchReader, Table, Schema } from 'apache-arrow' + +/** + * Options for connecting to a driver/database. + * + * These options configure how the ADBC driver is loaded and how the initial connection is established. + */ +export interface ConnectOptions { + /** + * Path to the driver library or short name of the driver. + * Short names (e.g. "sqlite") work when the corresponding ADBC driver is installed on the system. + * Full paths to a .so/.dylib/.dll or a manifest .toml file are also accepted. + */ + driver: string + /** + * Name of the entrypoint function (optional). + * If not provided, ADBC will attempt to guess the entrypoint symbol name based on the driver name. + */ + entrypoint?: string + /** + * Paths to search for the driver (optional). + * Useful if the driver is not in the standard library paths. + */ + searchPaths?: string[] + /** + * Load flags (optional). + * Bitmask controlling how the driver is loaded (e.g., search system paths, search user paths). + */ + loadFlags?: number + /** + * Database-specific options. + * Key-value pairs passed to the driver during database initialization (e.g., "uri", "username"). + */ + databaseOptions?: Record<string, string> +} + +/** Options for getObjects metadata call. */ +export interface GetObjectsOptions { + /** + * The level of depth to retrieve. + * 0: All (Catalogs, Schemas, Tables, and Columns) + * 1: Catalogs only + * 2: Catalogs and Schemas + * 3: Catalogs, Schemas, and Tables + * 4: Catalogs, Schemas, Tables, and Columns (same as 0) + */ + depth?: number + /** Filter by catalog name pattern. */ + catalog?: string + /** Filter by database schema name pattern. */ + dbSchema?: string + /** Filter by table name pattern. */ + tableName?: string + /** Filter by table type (e.g., ["table", "view"]). */ + tableType?: string[] + /** Filter by column name pattern. */ + columnName?: string +} + +/** + * Represents an ADBC Database. + * + * An AdbcDatabase represents a handle to a database. This may be a single file (SQLite), + * a connection configuration (PostgreSQL), or an in-memory database. + * It holds state that is shared across multiple connections. + */ +export interface AdbcDatabase { + /** + * Open a new connection to the database. + * + * @returns A Promise resolving to a new AdbcConnection. + */ + connect(): Promise<AdbcConnection> + + /** + * Release the database resources. + * After closing, the database object should not be used. + */ + close(): Promise<void> +} + +/** + * Represents a single connection to a database. + * + * An AdbcConnection maintains the state of a connection to the database, such as + * current transaction state and session options. + */ +export interface AdbcConnection { + /** + * Create a new statement for executing queries. + * + * @returns A Promise resolving to a new AdbcStatement. + */ + createStatement(): Promise<AdbcStatement> + + /** + * Set an option on the connection. + * + * @param key The option name (e.g., "adbc.connection.autocommit"). + * @param value The option value. + */ + setOption(key: string, value: string): void + + /** + * Toggle autocommit behavior. + * + * @param enabled Whether autocommit should be enabled. + */ + setAutoCommit(enabled: boolean): void + + /** + * Toggle read-only mode. + * + * @param enabled Whether the connection should be read-only. + */ + setReadOnly(enabled: boolean): void + + /** + * Get a hierarchical view of database objects (catalogs, schemas, tables, columns). + * + * @param options Filtering options for the metadata query. + * @returns A RecordBatchReader containing the metadata. + */ + getObjects(options?: GetObjectsOptions): Promise<RecordBatchReader> + + /** + * Get the Arrow schema for a specific table. + * + * @param options An object containing catalog, dbSchema, and tableName. + * @param options.catalog The catalog name (or undefined). + * @param options.dbSchema The schema name (or undefined). + * @param options.tableName The table name. + * @returns A Promise resolving to the Arrow Schema of the table. + */ + getTableSchema(options: { catalog?: string; dbSchema?: string; tableName: string }): Promise<Schema> + + /** + * Get a list of table types supported by the database. + * + * @returns A RecordBatchReader containing a single string column of table types. + */ + getTableTypes(): Promise<RecordBatchReader> + + /** + * Get metadata about the driver and database. + * + * @param infoCodes Optional list of integer info codes to retrieve. + * @returns A RecordBatchReader containing the requested metadata info. + */ + getInfo(infoCodes?: number[]): Promise<RecordBatchReader> Review Comment: same here, we probably want an enum/typed value here so we can have constants ########## javascript/lib/types.ts: ########## @@ -0,0 +1,264 @@ +// 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 { RecordBatch, RecordBatchReader, Table, Schema } from 'apache-arrow' + +/** + * Options for connecting to a driver/database. + * + * These options configure how the ADBC driver is loaded and how the initial connection is established. + */ +export interface ConnectOptions { + /** + * Path to the driver library or short name of the driver. + * Short names (e.g. "sqlite") work when the corresponding ADBC driver is installed on the system. + * Full paths to a .so/.dylib/.dll or a manifest .toml file are also accepted. + */ + driver: string + /** + * Name of the entrypoint function (optional). + * If not provided, ADBC will attempt to guess the entrypoint symbol name based on the driver name. + */ + entrypoint?: string + /** + * Paths to search for the driver (optional). + * Useful if the driver is not in the standard library paths. + */ + searchPaths?: string[] + /** + * Load flags (optional). + * Bitmask controlling how the driver is loaded (e.g., search system paths, search user paths). + */ + loadFlags?: number + /** + * Database-specific options. + * Key-value pairs passed to the driver during database initialization (e.g., "uri", "username"). + */ + databaseOptions?: Record<string, string> +} + +/** Options for getObjects metadata call. */ +export interface GetObjectsOptions { + /** + * The level of depth to retrieve. + * 0: All (Catalogs, Schemas, Tables, and Columns) + * 1: Catalogs only + * 2: Catalogs and Schemas + * 3: Catalogs, Schemas, and Tables + * 4: Catalogs, Schemas, Tables, and Columns (same as 0) + */ + depth?: number Review Comment: Can this be a typed enum so that we can provide constants for users to use here? ########## javascript/lib/types.ts: ########## @@ -0,0 +1,264 @@ +// 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 { RecordBatch, RecordBatchReader, Table, Schema } from 'apache-arrow' + +/** + * Options for connecting to a driver/database. + * + * These options configure how the ADBC driver is loaded and how the initial connection is established. + */ +export interface ConnectOptions { + /** + * Path to the driver library or short name of the driver. + * Short names (e.g. "sqlite") work when the corresponding ADBC driver is installed on the system. + * Full paths to a .so/.dylib/.dll or a manifest .toml file are also accepted. + */ + driver: string + /** + * Name of the entrypoint function (optional). + * If not provided, ADBC will attempt to guess the entrypoint symbol name based on the driver name. + */ + entrypoint?: string + /** + * Paths to search for the driver (optional). + * Useful if the driver is not in the standard library paths. + */ Review Comment: also for searching for profiles too -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
