Skip to content

oracle.mdx

Latest commit

 

History

History
150 lines (123 loc) · 13.9 KB

oracle.mdx

File metadata and controls

150 lines (123 loc) · 13.9 KB
title Oracle Database
sidebar_position 1

Sequelize for Oracle Database

:::info Version Compatibility

See Releases to see which versions of Oracle Database are supported.

:::

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

npm i @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

import ConnectionOptions from './_connection-options.md';

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.
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:

  1. Install the oracledb package.

      npm i oracledb

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

  3. 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 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
});