From eadc788356bc1f6b748b0929c698f7e07f03ff8e Mon Sep 17 00:00:00 2001 From: Korinne Adler Date: Wed, 23 Sep 2026 15:32:31 -0500 Subject: [PATCH] doc: Clean up README - Fix (most) markdown lint warnings. There are still warnings about duplicate headings and using emphasis instead of headings. - Add badge for Node version support - Remove horizontal rules - Remove empty Drivers section. - Remove Requirements section. This is duplicated with Installation. - Simplify Installation section. Most users don't need the devel packages due to prebuilt binaries. - Remove Future Improvements section. This is assumed unless the package states they are stable/maintenance only. - Remove license text from README since it's already in the LICENSE file. Update LICENSE file to match README and add update copyright for 2026. --- LICENSE | 2 + README.md | 488 +++++++++++++++++++++++------------------------------- 2 files changed, 209 insertions(+), 281 deletions(-) diff --git a/LICENSE b/LICENSE index 3851aab2..c2be904b 100644 --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,6 @@ +Copyright (c) 2021, 2026 node-odbc contributors Copyright (c) 2019, 2021 IBM +Copyright (c) 2013 Dan VerWeire Copyright (c) 2010 Lee Smith Permission is hereby granted, free of charge, to any person diff --git a/README.md b/README.md index 093185f9..c858fd91 100644 --- a/README.md +++ b/README.md @@ -1,67 +1,16 @@ # odbc +[![Node version badge](https://img.shields.io/node/v/odbc)](#nodejs-version-support) An asynchronous interface for Node.js to unixODBC and its supported drivers. ---- - -## Requirements - - -* unixODBC binaries and development libraries for module compilation - * on Ubuntu/Debian `sudo apt-get install unixodbc unixodbc-dev` - * on RedHat/CentOS `sudo yum install unixODBC unixODBC-devel` - * on OSX - * using macports.org `sudo port unixODBC` - * using brew `brew install unixODBC` - * on FreeBSD from ports `cd /usr/ports/databases/unixODBC; make install` - * on IBM i `yum install unixODBC unixODBC-devel` (requires [yum](http://ibm.biz/ibmi-rpms)) -* ODBC drivers for target database -* properly configured odbc.ini and odbcinst.ini. - ---- - -## Node.js Version Support - -This package is a native addon written in C++ using -[node-addon-api](https://github.com/nodejs/node-addon-api). Like -`node-addon-api`, `node-odbc` only supports the active LTS Node.js versions. - -Currently supported versions include: - -* Node.js 24 -* Node.js 22 -* Node.js 20 - ---- - ## Installation -Three main steps must be done before `node-odbc` can interact with your database: - -* **Install unixODBC and unixODBC-devel:** Compilation of `node-odbc` on your system requires these packages to provide the correct headers. - * **Ubuntu/Debian**: `sudo apt-get install unixodbc unixodbc-dev` - * **RedHat/CentOS**: `sudo yum install unixODBC unixODBC-devel` - * **OSX**: - * **macports.org:** `sudo port unixODBC` - * **using brew:** `brew install unixODBC` - * **FreeBSD** from ports: `cd /usr/ports/databases/unixODBC; make install` - * **IBM i:** `yum install unixODBC unixODBC-devel` (requires [yum](http://ibm.biz/ibmi-rpms)) - -* **Install ODBC drivers for target database:** Most database management system providers offer ODBC drivers for their product. See the website of your DBMS for more information. - -* **odbc.ini and odbcinst.ini**: These files define your DSNs (data source names) and ODBC drivers, respectively. They must be set up for ODBC functions to correctly interact with your database. - -When all these steps have been completed, install `node-odbc` into your Node.js project by using: - ```bash npm install odbc ``` ---- -🚨🚨🚨 - -**NOTE:** starting with version 12, npm will no longer run install scripts by default. When installing, you will see a message like this: +🚨🚨🚨 **NOTE:** starting with version 12, npm will no longer run install scripts by default. When installing, you will see a message like this: ```sh npm warn install-scripts odbc@2.5.0 (install: node-pre-gyp install --fallback-to-build) @@ -74,11 +23,43 @@ You will need to approve the install script in order to use the odbc package. Af npm approve-scripts odbc npm rebuild odbc ``` -Once it has been approved and your package.json is updated, future installs will just work. + +Once it has been approved and your package.json is updated, future installs will just work. For more information refer to the [npm blog post](https://github.blog/changelog/2026-06-09-upcoming-breaking-changes-for-npm-v12/). ---- +## Additional Requirements + +Before you can use `node-odbc`, there are additional steps: + +* **Install unixODBC** + * **Ubuntu/Debian**: `sudo apt install unixodbc` + * **RedHat/CentOS**: `sudo dnf install unixODBC` + * **macOS**: + * **macports.org:** `sudo port unixODBC` + * **Homebrew:** `brew install unixODBC` + * **FreeBSD Ports** `cd /usr/ports/databases/unixODBC; make install` + * **IBM i:** `yum install unixODBC` (requires [yum](http://ibm.biz/ibmi-rpms)) + +* **Install ODBC drivers** You will of course need an ODBC driver for your DBMS. + +If there are no pre-built binaries or you want to build from source, you will also need to install the unixODBC development files: + +* **Ubuntu/Debian**: `sudo apt install unixodbc-dev` +* **RedHat/CentOS**: `sudo dnf install unixODBC-devel` +* **IBM i:** `yum install unixODBC-devel` + +## Node.js Version Support + +This package is a native addon written in C++ using +[node-addon-api](https://github.com/nodejs/node-addon-api). Like +`node-addon-api`, `node-odbc` only supports the active LTS Node.js versions. + +Currently supported versions include: + +* Node.js 24 +* Node.js 22 +* Node.js 20 ## Debugging @@ -89,21 +70,18 @@ Instead, tracing should be enabled through your driver manager, and that informa * **unixODBC (Linux, MacOS, IBM i):** In your `odbcinst.ini` file, add the following entry: - ``` + + ```ini [ODBC] Trace=yes TraceFile=/tmp/odbc.log ``` + Debug information will be appended to the trace file. * **ODBC Data Source Administrator (Windows):** Open up ODBC Data Source Administrator and select the "Tracing" tab. Enter the location where you want the log file to go in **"Log File Path"**, then click **"Start Tracing Now"**. ---- - -## Drivers - ---- ## Important Changes in 2.0 @@ -119,38 +97,36 @@ Instead, tracing should be enabled through your driver manager, and that informa * **Timestamp and Datetime Changes:** SQL_DATETIME and SQL_TIMESTAMP no longer are automatically converted to UTC from how they were stored in the table. Previously, the assumption was that whatever was stored in the table was in "local time", and then converted to UTC. There is no guarantee that the time stored is in "local time", and many DBMSs store times without timezone data. Now, the driver will determine how to format the timestamps and datetimes that are returned, as it is retrieved simply as a String with no additional manipulation by this package. ---- - ## API -* [Connection](#Connection) - * [constructor: odbc.connect()](#constructor-odbcconnectconnectionstring) - * [.query()](#querysql-parameters-callback) - * [.callProcedure()](#callprocedurecatalog-schema-name-parameters-callback) - * [.createStatement()](#createstatementcallback) - * [.tables()](#tablescatalog-schema-table-type-callback) - * [.columns()](#columnscatalog-schema-table-column-callback) - * [.setIsolationLevel()](#setIsolationLevellevel-callback) - * [.beginTransaction()](#begintransactioncallback) - * [.commit()](#commitcallback) - * [.rollback()](#rollbackcallback) - * [.cancel()](#cancelcallback) - * [.close()](#closecallback) -* [Pool](#Pool) - * [constructor: odbc.pool()](#constructor-odbcpoolconnectionstring) - * [.connect()](#connectcallback) - * [.query()](#querysql-parameters-callback-1) - * [.close()](#closecallback-1) -* [Statement](#Statement) - * [.prepare()](#preparesql-callback) - * [.bind()](#bindparameters-callback) - * [.execute()](#executecallback) - * [.cancel()](#cancelcallback-1) - * [.close()](#closecallback-2) -* [Cursor](#Cursor) - * [.fetch()](#fetchcallback) - * [.noData](#nodata) - * [.close()](#closecallback-3) +* [Connection](#connection) + * [constructor: odbc.connect()](#constructor-odbcconnectconnectionstring) + * [.query()](#querysql-parameters-callback) + * [.callProcedure()](#callprocedurecatalog-schema-name-parameters-callback) + * [.createStatement()](#createstatementcallback) + * [.tables()](#tablescatalog-schema-table-type-callback) + * [.columns()](#columnscatalog-schema-table-column-callback) + * [.setIsolationLevel()](#setisolationlevellevel-callback) + * [.beginTransaction()](#begintransactioncallback) + * [.commit()](#commitcallback) + * [.rollback()](#rollbackcallback) + * [.cancel()](#cancelcallback) + * [.close()](#closecallback) +* [Pool](#pool) + * [constructor: odbc.pool()](#constructor-odbcpoolconnectionstring) + * [.connect()](#connectcallback) + * [.query()](#querysql-parameters-callback) + * [.close()](#closecallback-1) +* [Statement](#statement) + * [.prepare()](#preparesql-callback) + * [.bind()](#bindparameters-callback) + * [.execute()](#executeoptions-callback) + * [.cancel()](#cancelcallback-1) + * [.close()](#closecallback-2) +* [Cursor](#cursor) + * [.fetch()](#fetchcallback) + * [.noData](#nodata) + * [.close()](#closecallback-3) ### **Callbacks _or_ Promises** @@ -163,6 +139,7 @@ _All examples are shown using IBM i Db2 DSNs and queries. Because ODBC is DBMS-a All functions that return a result set do so in an array, where each row in the result set is an entry in the array. The format of data within the row can either be an array or an object, depending on the configuration option passed to the connection. The result array also contains several properties: + * `count`: the number of rows affected by the statement or procedure. Returns the result from ODBC function SQLRowCount. * `columns`: a list of columns in the result set. This is returned in an array. Each column in the array has the following properties: * `name`: The name of the column @@ -171,7 +148,7 @@ The result array also contains several properties: * `parameters`: The parameters passed to the statement or procedure. For input/output and output parameters, this value will reflect the value updated from a procedure. * `return`: The return value from some procedures. For many DBMS, this will always be undefined. -``` +```json [ { CUSNUM: 938472, LSTNAM: 'Henning ', INIT: 'G K', @@ -215,9 +192,6 @@ In this example, two rows are returned, with eleven columns each. The format of With this result structure, users can iterate over the result set like any old array (in this case, `results.length` would return 2) while also accessing important information from the SQL call and result set. ---- ---- - ## **Connection** A Connection is your means of connecting to the database through ODBC. @@ -226,16 +200,17 @@ A Connection is your means of connecting to the database through ODBC. In order to get a connection, you must use the `.connect` function exported from the module. This asynchronously creates a Connection and gives it back to you. Like all asynchronous functions, this can be done either with callback functions or Promises. -#### Parameters: +#### Parameters + * **connectionString**: The connection string to connect to the database, usually by naming a DSN. Can also be a configuration object with the following properties: - * `connectionString` **REQUIRED**: The connection string to connect to the database - * `connectionTimeout`: The number of seconds to wait for a request on the connection to complete before returning to the application - * `loginTimeout`: The number of seconds to wait for a login request to complete before returning to the application + * `connectionString` **REQUIRED**: The connection string to connect to the database + * `connectionTimeout`: The number of seconds to wait for a request on the connection to complete before returning to the application + * `loginTimeout`: The number of seconds to wait for a login request to complete before returning to the application * **callback?**: The function called when `.connect` has finished connecting. If no callback function is given, `.connect` will return a native JavaScript `Promise`. Callback signature is: - * error: The error that occured in execution, or `null` if no error - * connection: The Connection object if a successful connection was made + * error: The error that occured in execution, or `null` if no error + * connection: The Connection object if a successful connection was made -#### Examples: +#### Examples **Promises** @@ -270,23 +245,22 @@ odbc.connect(connectionString, (error, connection) => { Once a Connection has been created with `odbc.connect`, you can use the following functions on the connection: ---- - ### `.query(sql, parameters?, options?, callback?)` Run a query on the database. Can be passed an SQL string with parameter markers `?` and an array of parameters to bind to those markers. Returns a [result array](#result-array). -#### Parameters: +#### Parameters + * **sql**: The SQL string to execute * **parameters?**: An array of parameters to be bound the parameter markers (`?`) * **options?**: An object containing query options that affect query behavior. Valid properties include: - * `cursor`: A boolean value indicating whether or not to return a cursor instead of results immediately. Can also be a string naming the cursor, which will assume that a cursor will be returned. - * `fetchSize`: Used with a cursor, sets the number of rows that are returned on a call to `fetch` on the Cursor. - * `timeout`: The amount of time (in seconds) that the query will attempt to execute before returning to the application. - * `initialBufferSize`: Sets the initial buffer size (in bytes) for storing data from SQL_LONG* data fields. Useful for avoiding resizes if buffer size is known before the call. + * `cursor`: A boolean value indicating whether or not to return a cursor instead of results immediately. Can also be a string naming the cursor, which will assume that a cursor will be returned. + * `fetchSize`: Used with a cursor, sets the number of rows that are returned on a call to `fetch` on the Cursor. + * `timeout`: The amount of time (in seconds) that the query will attempt to execute before returning to the application. + * `initialBufferSize`: Sets the initial buffer size (in bytes) for storing data from SQL_LONG* data fields. Useful for avoiding resizes if buffer size is known before the call. * **callback?**: The function called when `.query` has finished execution. If no callback function is given, `.query` will return a native JavaScript `Promise`. Callback signature is: - * error: The error that occured in execution, or `null` if no error - * result: The result object from execution + * error: The error that occured in execution, or `null` if no error + * result: The result object from execution ```JavaScript const odbc = require('odbc'); @@ -298,22 +272,21 @@ const connection = odbc.connect(connectionString, (error, connection) => { }); ``` ---- - ### `.callProcedure(catalog, schema, name, parameters?, callback?)` Calls a database procedure, returning the results in a [result array](#result-array). -#### Parameters: +#### Parameters + * **catalog**: The name of the catalog where the procedure exists, or null to use the default catalog * **schema**: The name of the schema where the procedure exists, or null to use a default schema * **name**: The name of the procedure in the database * **parameters?**: An array of parameters to pass to the procedure. For input and input/output parameters, the JavaScript value passed in is expected to be of a type translatable to the SQL type the procedure expects. For output parameters, any JavaScript value can be passed in, and will be overwritten by the function. The number of parameters passed in must match the number of parameters expected by the procedure. * **callback?**: The function called when `.callProcedure` has finished execution. If no callback function is given, `.callProcedure` will return a native JavaScript `Promise`. Callback signature is: - * error: The error that occured in execution, or `null` if no error - * result: The result object from execution + * error: The error that occured in execution, or `null` if no error + * result: The result object from execution -#### Examples: +#### Examples **Promises** @@ -345,18 +318,17 @@ odbc.connect(`${process.env.CONNECTION_STRING}`, (error, connection) => { }); ``` ---- - ### `.createStatement(callback?)` -Returns a [Statement](#Statement) object from the connection. +Returns a [Statement](#statement) object from the connection. + +#### Parameters -#### Parameters: * **callback?**: The function called when `.createStatement` has finished execution. If no callback function is given, `.createStatement` will return a native JavaScript `Promise`. Callback signature is: - * error: The error that occured in execution, or `null` if no error - * statement: The newly created Statement object + * error: The error that occured in execution, or `null` if no error + * statement: The newly created Statement object -#### Examples: +#### Examples **Promises** @@ -387,22 +359,21 @@ odbc.connect(`${process.env.CONNECTION_STRING}`, (error, connection) => { }); ``` ---- - ### `.tables(catalog, schema, table, type, callback?)` Returns information about the table specified in the parameters by calling the ODBC function [SQLTables](https://docs.microsoft.com/en-us/sql/odbc/reference/syntax/sqltables-function?view=sql-server-2017). Values passed to parameters will narrow the result set, while `null` will include all results of that level. -#### Parameters: +#### Parameters + * **catalog**: The name of the catalog, or null if not specified * **schema**: The name of the schema, or null if not specified * **table**: The name of the table, or null if not specified * **type**: The type of table that you want information about, or null if not specified * **callback?**: The function called when `.tables` has finished execution. If no callback function is given, `.tables` will return a native JavaScript `Promise`. Callback signature is: - * error: The error that occured in execution, or `null` if no error - * result: The result object from execution + * error: The error that occured in execution, or `null` if no error + * result: The result object from execution -#### Examples: +#### Examples **Promises** @@ -434,22 +405,21 @@ odbc.connect(`${process.env.CONNECTION_STRING}`, (error, connection) => { }); ``` ---- - ### `.columns(catalog, schema, table, column, callback?)` Returns information about the columns specified in the parameters by calling the ODBC function [SQLColumns](https://docs.microsoft.com/en-us/sql/odbc/reference/syntax/sqlcolumns-function?view=sql-server-2017). Values passed to parameters will narrow the result set, while `null` will include all results of that level. -#### Parameters: +#### Parameters + * **catalog**: The name of the catalog, or null if not specified * **schema**: The name of the schema, or null if not specified * **table**: The name of the table, or null if not specified * **column**: The name of the column that you want information about, or null if not specified * **callback?**: The function called when `.columns` has finished execution. If no callback function is given, `.columns` will return a native JavaScript `Promise`. Callback signature is: - * error: The error that occured in execution, or `null` if no error - * result: The result object from execution + * error: The error that occured in execution, or `null` if no error + * result: The result object from execution -#### Examples: +#### Examples **Promises** @@ -481,22 +451,21 @@ odbc.connect(`${process.env.CONNECTION_STRING}`, (error, connection) => { }); ``` ---- - ### `.setIsolationLevel(level, callback?)` Sets the transaction isolation level for the connection, which determines what degree of uncommitted changes can be seen. More information about ODBC isolation levels can be found on [the official ODBC documentation](https://docs.microsoft.com/en-us/sql/odbc/reference/develop-app/transaction-isolation?view=sql-server-2017). -#### Parameters: +#### Parameters + * **level**: The isolation level to set on the connection. [There are four isolation levels specified by ODBC](https://docs.microsoft.com/en-us/sql/odbc/reference/develop-app/transaction-isolation-levels?view=sql-server-2017), which can be accessed through the base exported package: - * `odbc.SQL_TXN_READ_UNCOMMITTED` - * `odbc.SQL_TXN_READ_COMMITTED` - * `odbc.SQL_TXN_REPEATABLE_READ` - * `odbc.SQL_TXN_SERIALIZABLE` + * `odbc.SQL_TXN_READ_UNCOMMITTED` + * `odbc.SQL_TXN_READ_COMMITTED` + * `odbc.SQL_TXN_REPEATABLE_READ` + * `odbc.SQL_TXN_SERIALIZABLE` * **callback?**: The function called when `.setIsolationLevel` has finished execution. If no callback function is given, `.setIsolationLevel` will return a native JavaScript `Promise`. Callback signature is: - * error: The error that occured in execution, or `null` if no error + * error: The error that occured in execution, or `null` if no error -#### Examples: +#### Examples **Promises** @@ -526,17 +495,16 @@ odbc.connect(`${process.env.CONNECTION_STRING}`, (error, connection) => { }); ``` ---- - ### `.beginTransaction(callback?)` Begins a transaction on the connection. The transaction can be committed by calling `.commit` or rolled back by calling `.rollback`. **If a connection is closed with an open transaction, it will be rolled back.** Connection isolation level will affect the data that other transactions can view mid transaction. -#### Parameters: +#### Parameters + * **callback?**: The function called when `.beginTransaction` has finished execution. If no callback function is given, `.beginTransaction` will return a native JavaScript `Promise`. Callback signature is: - * error: The error that occured in execution, or `null` if no error + * error: The error that occured in execution, or `null` if no error -#### Examples: +#### Examples **Promises** @@ -566,17 +534,16 @@ odbc.connect(`${process.env.CONNECTION_STRING}`, (error, connection) => { }); ``` ---- - ### `.commit(callback?)` Commits an open transaction. If called on a connection that doesn't have an open transaction, will no-op. -#### Parameters: +#### Parameters + * **callback?**: The function called when `.commit` has finished execution. If no callback function is given, `.commit` will return a native JavaScript `Promise`. Callback signature is: - * error: The error that occured in execution, or `null` if no error + * error: The error that occured in execution, or `null` if no error -#### Examples: +#### Examples **Promises** @@ -613,18 +580,16 @@ odbc.connect(`${process.env.CONNECTION_STRING}`, (error, connection) => { }); ``` ---- - - ### `.rollback(callback?)` Rolls back an open transaction. If called on a connection that doesn't have an open transaction, will no-op. -#### Parameters: +#### Parameters + * **callback?**: The function called when `.rollback` has finished execution. If no callback function is given, `.rollback` will return a native JavaScript `Promise`. Callback signature is: - * error: The error that occured in execution, or `null` if no error + * error: The error that occured in execution, or `null` if no error -#### Examples: +#### Examples **Promises** @@ -661,19 +626,18 @@ odbc.connect(`${process.env.CONNECTION_STRING}`, (error, connection) => { }); ``` ---- - ### `.cancel(callback?)` Cancels all operations currently running on the connection (queries and procedure calls) by calling `SQLCancel` on their statement handles. The cancelled operations return with SQLSTATE HY008 ("Operation canceled"), so their promises reject (or their callbacks are called with an error). If no operations are running, `.cancel` is a no-op. **Note:** `SQLCancel` only _requests_ cancellation — when the operation actually aborts depends on the driver and on the database engine reaching a cancellation checkpoint. Row-producing operations (scans, fetches) usually abort promptly, but some operations never check for cancellation and only fail with HY008 once they finish on their own. Known examples: Impala's `sleep()` function completes its full wait before honoring the cancel, and calls to stored procedures on Db2 for IBM i are not cancelable at all. -#### Parameters: +#### Parameters + * **callback?**: The function called when `.cancel` has finished execution. If no callback function is given, `.cancel` will return a native JavaScript `Promise`. Callback signature is: - * error: The error that occured in execution, or `null` if no error + * error: The error that occured in execution, or `null` if no error -#### Examples: +#### Examples **Promises** @@ -721,17 +685,16 @@ odbc.connect(`${process.env.CONNECTION_STRING}`, (error, connection) => { }); ``` ---- - ### `.close(callback?)` Closes an open connection. Any transactions on the connection that have not been ended will be rolledback. -#### Parameters: +#### Parameters + * **callback?**: The function called when `.close` has finished closing the connection. If no callback function is given, `.close` will return a native JavaScript `Promise`. Callback signature is: - * error: The error that occured in execution, or `null` if no error + * error: The error that occured in execution, or `null` if no error -#### Examples: +#### Examples **Promises** @@ -762,10 +725,6 @@ odbc.connect(`${process.env.CONNECTION_STRING}`, (error, connection) => { }); ``` ---- ---- - - ### **Pool** ### `constructor: odbc.pool(connectionString)` @@ -774,21 +733,22 @@ In order to get a Pool, you must use the `.pool` function exported from the modu Note that `odbc.pool` will return from callback or Promise as soon as it has created 1 connection. It will continue to spin up Connections and add them to the Pool in the background, but by returning early it will allow you to use the Pool as soon as possible. -#### Parameters: +#### Parameters + * **connectionString**: The connection string to connect to the database for all connections in the pool, usually by naming a DSN. Can also be a configuration object with the following properties: - * `connectionString` **REQUIRED**: The connection string to connect to the database - * `connectionTimeout`: The number of seconds to wait for a request on the connection to complete before returning to the application - * `loginTimeout`: The number of seconds to wait for a login request to complete before returning to the application - * `initialSize`: The initial number of Connections created in the Pool - * `incrementSize`: How many additional Connections to create when all of the Pool's connections are taken - * `maxSize`: The maximum number of open Connections the Pool will create - * `reuseConnections`: Whether or not to reuse an existing Connection instead of creating a new one - * `shrink`: Whether or not the number of Connections should shrink to `initialSize` as they free up + * `connectionString` **REQUIRED**: The connection string to connect to the database + * `connectionTimeout`: The number of seconds to wait for a request on the connection to complete before returning to the application + * `loginTimeout`: The number of seconds to wait for a login request to complete before returning to the application + * `initialSize`: The initial number of Connections created in the Pool + * `incrementSize`: How many additional Connections to create when all of the Pool's connections are taken + * `maxSize`: The maximum number of open Connections the Pool will create + * `reuseConnections`: Whether or not to reuse an existing Connection instead of creating a new one + * `shrink`: Whether or not the number of Connections should shrink to `initialSize` as they free up * **callback?**: The function called when `.connect` has finished connecting. If no callback function is given, `.connect` will return a native JavaScript `Promise`. Callback signature is: - * error: The error that occured in execution, or `null` if no error - * connection: The Connection object if a successful connection was made + * error: The error that occured in execution, or `null` if no error + * connection: The Connection object if a successful connection was made -#### Examples: +#### Examples **Promises** @@ -817,12 +777,13 @@ const pool = odbc.pool('DSN=MyDSN', (error, pool) => { Returns a [Connection](#connection) object for you to use from the Pool. Doesn't actually open a connection, because they are already open in the pool when `.init` is called. -#### Parameters: +#### Parameters + * **callback?**: The function called when `.connect` has finished execution. If no callback function is given, `.connect` will return a native JavaScript `Promise`. Callback signature is: - * error: The error that occured in execution, or `null` if no error - * connection: The [Connection](#connection) retrieved from the Pool. + * error: The error that occured in execution, or `null` if no error + * connection: The [Connection](#connection) retrieved from the Pool. -#### Examples: +#### Examples **Promises** @@ -852,25 +813,24 @@ odbc.pool(`${process.env.CONNECTION_STRING}`, (error1, pool) => { }); ``` ---- - ### `.query(sql, parameters?, callback?)` Utility function to execute a query on any open connection in the pool. Will get a connection, fire off the query, return the results, and return the connection the the pool. -#### Parameters: +#### Parameters + * **sql**: An SQL string that will be executed. Can optionally be given parameter markers (`?`) and also given an array of values to bind to the parameters. * **parameters?**: An array of values to bind to the parameter markers, if there are any. The number of values in this array must match the number of parameter markers in the sql statement. * **options?**: An object containing query options that affect query behavior. Valid properties include: - * `cursor`: A boolean value indicating whether or not to return a cursor instead of results immediately. Can also be a string naming the cursor, which will assume that a cursor will be returned. - * `fetchSize`: Used with a cursor, sets the number of rows that are returned on a call to `fetch` on the Cursor. - * `timeout`: The amount of time (in seconds) that the query will attempt to execute before returning to the application. - * `initialBufferSize`: Sets the initial buffer size (in bytes) for storing data from SQL_LONG* data fields. Useful for avoiding resizes if buffer size is known before the call. + * `cursor`: A boolean value indicating whether or not to return a cursor instead of results immediately. Can also be a string naming the cursor, which will assume that a cursor will be returned. + * `fetchSize`: Used with a cursor, sets the number of rows that are returned on a call to `fetch` on the Cursor. + * `timeout`: The amount of time (in seconds) that the query will attempt to execute before returning to the application. + * `initialBufferSize`: Sets the initial buffer size (in bytes) for storing data from SQL_LONG* data fields. Useful for avoiding resizes if buffer size is known before the call. * **callback?**: The function called when `.query` has finished execution. If no callback function is given, `.query` will return a native JavaScript `Promise`. Callback signature is: - * error: The error that occured in execution, or `null` if no error - * result: The [result array](#result-array) returned from the executed statement + * error: The error that occured in execution, or `null` if no error + * result: The [result array](#result-array) returned from the executed statement -#### Examples: +#### Examples **Promises** @@ -900,17 +860,16 @@ odbc.pool(`${process.env.CONNECTION_STRING}`, (error1, pool) => { }); ``` ---- - ### `.close(callback?)` Closes the entire pool of currently unused connections. Will not close connections that are checked-out, but will discard the connections when they are closed with Connection's `.close` function. After calling close, must create a new Pool sprin up new Connections. -#### Parameters: +#### Parameters + * **callback?**: The function called when `.close` has finished execution. If no callback function is given, `.close` will return a native JavaScript `Promise`. Callback signature is: - * error: The error that occured in execution, or `null` if no error + * error: The error that occured in execution, or `null` if no error -#### Examples: +#### Examples **Promises** @@ -942,27 +901,23 @@ odbc.pool(`${process.env.CONNECTION_STRING}`, (error1, pool) => { }); ``` ---- ---- - ## **Statement** A Statement object is created from a Connection, and cannot be created _ad hoc_ with a constructor. Statements allow you to prepare a commonly used statement, then bind parameters to it multiple times, executing in between. ---- - ### `.prepare(sql, callback?)` Prepares an SQL statement, with or without parameters (?) to bind to. -#### Parameters: +#### Parameters + * **sql**: An SQL string that is prepared and can be executed with the .`execute` function. * **callback?**: The function called when `.prepare` has finished execution. If no callback function is given, `.prepare` will return a native JavaScript `Promise`. Callback signature is: - * error: The error that occured in execution, or `null` if no error + * error: The error that occured in execution, or `null` if no error -#### Examples: +#### Examples **Promises** @@ -996,18 +951,17 @@ odbc.connect(`${process.env.CONNECTION_STRING}`, (error, connection) => { }); ``` ---- - ### `.bind(parameters, callback?)` Binds an array of values to the parameters on the prepared SQL statement. Cannot be called before `.prepare`. -#### Parameters: +#### Parameters + * **sql**: An array of values to bind to the sql statement previously prepared. All parameters will be input parameters. The number of values passed in the array must match the number of parameters to bind to in the prepared statement. * **callback?**: The function called when `.bind` has finished execution. If no callback function is given, `.bind` will return a native JavaScript `Promise`. Callback signature is: - * error: The error that occured in execution, or `null` if no error + * error: The error that occured in execution, or `null` if no error -#### Examples: +#### Examples **Promises** @@ -1047,23 +1001,22 @@ odbc.connect(`${process.env.CONNECTION_STRING}`, (error, connection) => { }); ``` ---- - ### `.execute(options?, callback?)` Executes the prepared and optionally bound SQL statement. -#### Parameters: +#### Parameters + * **options?**: An object containing options that affect execution behavior. Valid properties include: - * `cursor`: A boolean value indicating whether or not to return a cursor instead of results immediately. Can also be a string naming the cursor, which will assume that a cursor will be returned. Closing the `Statement` will also close the `Cursor`, but closing the `Cursor` will keep the `Statement` valid. - * `fetchSize`: Used with a cursor, sets the number of rows that are returned on a call to `fetch` on the Cursor. - * `timeout`: The amount of time (in seconds) that the query will attempt to execute before returning to the application. - * `initialBufferSize`: Sets the initial buffer size (in bytes) for storing data from SQL_LONG* data fields. Useful for avoiding resizes if buffer size is known before the call. + * `cursor`: A boolean value indicating whether or not to return a cursor instead of results immediately. Can also be a string naming the cursor, which will assume that a cursor will be returned. Closing the `Statement` will also close the `Cursor`, but closing the `Cursor` will keep the `Statement` valid. + * `fetchSize`: Used with a cursor, sets the number of rows that are returned on a call to `fetch` on the Cursor. + * `timeout`: The amount of time (in seconds) that the query will attempt to execute before returning to the application. + * `initialBufferSize`: Sets the initial buffer size (in bytes) for storing data from SQL_LONG* data fields. Useful for avoiding resizes if buffer size is known before the call. * **callback?**: The function called when `.execute` has finished execution. If no callback function is given, `.execute` will return a native JavaScript `Promise`. Callback signature is: - * error: The error that occured in execution, or `null` if no error - * result: The [result array](#result-array) returned from the executed statement + * error: The error that occured in execution, or `null` if no error + * result: The [result array](#result-array) returned from the executed statement -#### Examples: +#### Examples **Promises** @@ -1108,19 +1061,18 @@ odbc.connect(`${process.env.CONNECTION_STRING}`, (error, connection) => { }); ``` ---- - ### `.cancel(callback?)` Cancels any operation currently running on the Statement (e.g. a long `.execute()`) by calling `SQLCancel` on its handle. The cancelled operation returns with SQLSTATE HY008 ("Operation canceled"). **Note:** the cancellation-checkpoint caveat described in [connection.cancel()](#cancelcallback) applies here as well. -#### Parameters: +#### Parameters + * **callback?**: The function called when `.cancel` has finished execution. If no callback function is given, `.cancel` will return a native JavaScript `Promise`. Callback signature is: - * error: The error that occured in execution, or `null` if no error + * error: The error that occured in execution, or `null` if no error -#### Examples: +#### Examples **Promises** @@ -1176,17 +1128,16 @@ odbc.connect(`${process.env.CONNECTION_STRING}`, (error, connection) => { }); ``` ---- - ### `.close(callback?)` Closes the Statement, freeing the statement handle. Running functions on the statement after closing will result in an error. -#### Parameters: +#### Parameters + * **callback?**: The function called when `.close` has finished execution. If no callback function is given, `.close` will return a native JavaScript `Promise`. Callback signature is: - * error: The error that occured in execution, or `null` if no error + * error: The error that occured in execution, or `null` if no error -#### Examples: +#### Examples **Promises** @@ -1235,27 +1186,23 @@ odbc.connect(`${process.env.CONNECTION_STRING}`, (error, connection) => { }); ``` ---- ---- - ## **Cursor** A Cursor object is created from a Connection when running a query, and cannot be created _ad hoc_ with a constructor. Cursors allow you to fetch piecemeal instead of retrieving all rows at once. The fetch size is set on the query options, and then a Cursor is returned from the query instead of a result set. `.fetch` is then called to retrieve the result set by the fetch size. ---- - ### `.fetch(callback?)` Asynchronously returns the next chunk of rows from the result set and returns them as a Result object. -#### Parameters: +#### Parameters + * **callback?**: The function called when `.fetch` has finished retrieving the result rows. If no callback function is given, `.fetch` will return a native JavaScript `Promise` that resolve the result rows. Callback signature is: - * error: The error that occured in execution, or `null` if no error - * results: The [result array](#result-array) returned from the executed statement with at most `fetchSize`-number of rows. + * error: The error that occured in execution, or `null` if no error + * results: The [result array](#result-array) returned from the executed statement with at most `fetchSize`-number of rows. -#### Examples: +#### Examples **Promises** @@ -1294,16 +1241,15 @@ odbc.connect(`${process.env.CONNECTION_STRING}`, (error, connection) => { }); ``` ---- - ### `.noData` Returns whether the cursor has reached the end of the result set. Fetch must be called at least once before noData can return `true`. Used for determining if there are no more results to retrieve from the cursor. -#### Parameters: +#### Parameters + None -#### Examples: +#### Examples **Promises** @@ -1350,17 +1296,16 @@ odbc.connect(`${process.env.CONNECTION_STRING}`, (error, connection) => { }); ``` ---- - ### `.close(callback?)` Closes the statement that the cursor was generated from, and by extension the cursor itself. Needs to be called when the cursor is no longer needed. -#### Parameters: +#### Parameters + * **callback?**: The function called when `.close` has finished execution. If no callback function is given, `.close` will return a native JavaScript `Promise`. Callback signature is: - * error: The error that occured while closing the statement, or `null` if no error + * error: The error that occured while closing the statement, or `null` if no error -#### Examples: +#### Examples **Promises** @@ -1399,19 +1344,11 @@ odbc.connect(`${process.env.CONNECTION_STRING}`, (error, connection) => { }); ``` ---- ---- - - -## Future improvements +## Contributors -Development of `node-odbc` is an ongoing endeavor, and there are many planned improvements for the package. If you would like to see something, simply add it to the Issues and we will respond! - -## contributors - -* Mark Irish (mirish@ibm.com) -* Dan VerWeire (dverweire@gmail.com) -* Lee Smith (notwink@gmail.com) +* Mark Irish () +* Dan VerWeire () +* Lee Smith () * Bruno Bigras * Christian Ensel * Yorick @@ -1419,15 +1356,4 @@ Development of `node-odbc` is an ongoing endeavor, and there are many planned im * Oleg Efimov * paulhendrix -license -------- - -* Copyright (c) 2019, 2021 IBM -* Copyright (c) 2013 Dan VerWeire -* Copyright (c) 2010 Lee Smith - -Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies ofthe Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +For more, see [insights](https://github.com/IBM/node-odbc/graphs/contributors) \ No newline at end of file