Skip to main content

Oracle Database

@sqb/oracle is the SQB adapter for Oracle Database. It's built on top of oracledb, the official Oracle Node.js driver, which runs in pure-JavaScript "Thin" mode by default and can optionally link a native Oracle Client library for "Thick" mode.

Install​

npm install @sqb/oracle oracledb

@sqb/connect and @sqb/builder are peer dependencies pulled in transitively if you already depend on them directly; otherwise install them alongside.

Registering the adapter​

Importing @sqb/oracle registers it as a side effect — there's nothing else to wire up:

import '@sqb/oracle';
import { SqbClient } from '@sqb/connect';

const client = new SqbClient({
  dialect: 'oracle', // or driver: 'oracledb'
  host: 'localhost',
  database: 'ORCLPDB1',
  user: 'myuser',
  password: 'mypassword',
});

Under the hood, @sqb/oracle's entry point imports @sqb/oracle-dialect (which teaches @sqb/builder Oracle's SQL syntax) and registers an OraAdapter instance with AdapterRegistry. OraAdapter reports driver: 'oracledb' and dialect: 'oracle'.

Configuration​

user/password map directly onto oracledb's ConnectionAttributes. host is parsed as a connection URL (host[:port][/database], with an optional user:password@ prefix that is used only if user/password aren't already set) and combined with port/database into an oracledb connectString:

new SqbClient({
  dialect: 'oracle',
  host: 'dbhost:1521/ORCLPDB1',
});

is equivalent to:

new SqbClient({
  dialect: 'oracle',
  host: 'dbhost',
  port: 1521,
  database: 'ORCLPDB1',
});

driverOptions is spread onto the ConnectionAttributes object, so it can carry any option oracledb supports (e.g. poolMin, externalAuth) that isn't already covered by the standard fields:

new SqbClient({
  dialect: 'oracle',
  host: 'dbhost:1521/ORCLPDB1',
  driverOptions: {
    externalAuth: true,
  },
});

Thin vs. Thick mode​

By default (driverOptions.direct unset or false), the adapter attempts to locate and initialize a native Oracle Client library before the first connection, searching directories listed in the LD_LIBRARY_PATH/ORA_HOME environment variables for libclntsh.so (Linux), libclntsh.dylib (macOS), or oci.dll (Windows). If found, oracledb switches to Thick mode; otherwise it stays in Thin mode. Set driverOptions.direct: true to skip this lookup entirely and always use Thin mode:

new SqbClient({
  dialect: 'oracle',
  host: 'dbhost:1521/ORCLPDB1',
  driverOptions: { direct: true },
});

Feature notes​

  • Cursors: supported (features.cursor: true), backed by oracledb result sets — see Cursors & Streaming.
  • Schemas: supported (features.schema: true) — setSchema()/getSchema() are implemented via ALTER SESSION SET CURRENT_SCHEMA and sys_context('userenv', 'current_schema') — see Schemas.
  • RETURNING: emulated with a follow-up SELECT for inserts (matched by ROWID) and updates (by re-running the original WHERE clause), since the adapter doesn't use oracledb's native RETURNING INTO bind variables.

Migrator support​

warning

@sqb/migrator currently only implements its migration adapter for PostgreSQL — see Running migrations. Oracle migrations must be managed outside @sqb/migrator today.

See also​