Version: v7 - alpha

Sequelize for Oracle

Version Compatibility

See Releases to see which versions of Oracle are supported.

To use Sequelize with Oracle, you need to install the @sequelize/oracle dialect package:

npm
Yarn
pnpm
Bun

npm i @sequelize/oracle

yarn add @sequelize/oracle

pnpm add @sequelize/oracle

bun add @sequelize/oracle

Then use the OracleDialect class as the dialect option in the Sequelize constructor:

import { Sequelize } from '@sequelize/core';
import { OracleDialect } from '@sequelize/oracle';

const sequelize = new Sequelize({
  dialect: OracleDialect,
  database: 'mydb',
  username: 'myuser',
  password: 'mypass',
  host: 'localhost',
  port: 1521,
});

info

The underlying connector library used by Sequelize for Oracle is the node-oracledb package.
In Sequelize v7, the minimum supported node-oracledb version uses thin mode by default which doesn't require installing Oracle Client libraries.
For information on using Thick mode, refer to the Using Thick mode section.

Connection Options

Connection Options are used to configure a connection to the database.

The simplest way to use them is at the root of the configuration object. These options can also be used in the replication option to customize the connection for each replica, and can be modified by the beforeConnect hook on a connection-by-connection basis.

The following options are accepted by the OracleDialect:

Option	Description
`database`	Oracle "serviceName" to use for this connection
`username`	Oracle database user to authenticate as
`password`	The password of that Oracle database user
`port`	The port number to connect to. (Default: 1521)
`host`	The hostname of the database to connect to. (Default: localhost)
`connectString`	The connectString of the database instance to connect to.
`appContext`	An array of application context entries for the connection, where each entry is [namespace, name, value].
`accessToken`	The access token to connect to OCI IAM or Microsoft Azure token based authentication.
`accessTokenConfig`	The access token config object for OCI or Microsoft Azure token based authentication.
`walletPassword`	The password to decrypt the PEM-encoded private certificate, if it is encrypted.
`walletLocation`	The directory where the wallet can be found.
`edition`	Sets the name used for Edition-Based Redefinition by this connection.
`events`	Determines if the standalone connection is created using Oracle Call Interface events mode.
`externalAuth`	boolean property to allow external authentication.
`matchAny`	Used in conjunction with tag when getting a connection from a driver connection pool to indicate if the tag in a connection returned from a connection pool does not match the requested tag
`newPassword`	The new password to use for the database user.
`sslAllowWeakDNMatch`	boolean property to use either a weaker or more secure DN matching behavior when the sslServerDNMatch property is set.
`httpsProxy`	The name or IP address of a proxy host to use for tunneling secure connections.
`httpsProxyPort`	The port to be used to communicate with the proxy host. (Default: 0).
`debugJdwp`	This property allows using the Java Debug Wire Protocol (JDWP) to debug PL/SQL code called by node-oracledb.
`retryCount`	The number of times that a connection attempt should be retried before the attempt is terminated.
`retryDelay`	The number of seconds to wait before making a new connection attempt.
`connectTimeout`	The timeout duration in seconds for an application to establish an Oracle Net connection.
`transportConnectTimeout`	The maximum number of seconds to wait to establish a connection to the database host. (Default: 20.0)
`expireTime`	The number of minutes between the sending of keepalive probes.
`sdu`	The Oracle Net Session Data Unit (SDU) packet size in bytes.
`connectionIdPrefix`	The application specific prefix parameter that is added to the connection identifier.
`configDir`	The directory in which the Optional Oracle Net Configuration Files are found.
`sourceRoute`	Enables network routing through multiple protocol addresses. The value of this property can be ON or OFF.
`sslServerCertDN`	The distinguished name (DN) that should be matched with the certificate DN.
`sslServerDNMatch`	Determines whether the server certificate DN should be matched in addition to the regular certificate verification that is performed.
`poolAlias`	Specifies which previously created pool in the driver connection pool cache to use to obtain the connection from.
`privilege`	The privilege to use when establishing connection to the database.
`shardingKey`	Allows a connection to be established directly to a database shard.
`stmtCacheSize`	The number of statements to be cached in the statement cache of each connection.
`superShardingKey`	Allows a connection to be established directly to a database shard.
`tag`	Used when getting a connection from a connection pool.
`useSNI`	To enable a connection optimization feature which uses Server Name Indication (SNI) extension of the TLS protocol.
`networkCompression`	boolean to indicate if network data compression needs to be enabled or disabled for a database connection.
`networkCompressionThreshold`	The minimum data size, in bytes, for which compression should be performed on the Oracle Net Session Data Unit (SDU).
`driverName`	The name of the driver that is used by the client to connect to Oracle Database.
`machine`	The name of the host machine from where the connection originates.
`osUser`	The name of the operating system user that initiates the database connection.
`program`	The name of the program connecting to the database.
`terminal`	The name of the terminal from where the connection originates.
`walletContent`	The security credentials required to establish a mutual TLS (mTLS) connection to Oracle Database.

info

Please refer to the node-oracledb documentation for more information about what each of these options do.

Using Thick mode

To use Thick mode in a Sequelize v7 application, you must manually initialize the Oracle Client libraries in your application code before instantiating Sequelize:

Install the oracledb package.

npm
Yarn
pnpm
Bun

npm i oracledb

yarn add oracledb

pnpm add oracledb

bun add oracledb

Install any Oracle Client libraries like the Oracle Instant Client binaries in your operating system. Details to enable thick mode can be found here.

Call initOracleClient() at the very beginning of your application entry point as shown below:

const oracledb = require('oracledb');
const { Sequelize } = require('@sequelize/core');
const { OracleDialect } = require('@sequelize/oracle');

// 1. Manually initialize the Oracle Client (Required for Thick Mode)
try {
  // Thick mode requires Oracle Client or Oracle Instant Client libraries.
  // On Windows and macOS you can specify the directory containing the
  // libraries at runtime or before Node.js starts.  On other platforms (where
  // Oracle Client libraries are available) the system library search path must always
  // include the Oracle library path before Node.js starts.  If the search path
  // is not correct, you will get a DPI-1047 error.  See the node-oracledb
  // installation documentation.
  let clientOpts = {};
  // On Windows and macOS platforms, set the environment variable
  // NODE_ORACLEDB_CLIENT_LIB_DIR to the Oracle Client library path
  if (process.platform === 'win32' || process.platform === 'darwin') {
    clientOpts = { libDir: process.env.NODE_ORACLEDB_CLIENT_LIB_DIR };
  }
  oracledb.initOracleClient(clientOpts);
} catch (err) {
  // Handle initialization errors (e.g., binaries not found)
  console.error(err);
}

// 2. Initialize Sequelize
const sequelize = new Sequelize({
  dialect: OracleDialect,
  // ... connection options
});

Connection Options​

Using Thick mode​

Connection Options

Using Thick mode