|
| 1 | +--- |
| 2 | +title: Oracle |
| 3 | +sidebar_position: 1 |
| 4 | +--- |
| 5 | + |
| 6 | +# Sequelize for Oracle |
| 7 | + |
| 8 | +:::info Version Compatibility |
| 9 | + |
| 10 | +See [Releases](/releases#oracle-support-table) to see which versions of Oracle are supported. |
| 11 | + |
| 12 | +::: |
| 13 | + |
| 14 | +To use Sequelize with Oracle, you need to install the `@sequelize/oracle` dialect package: |
| 15 | + |
| 16 | +```bash npm2yarn |
| 17 | +npm i @sequelize/oracle |
| 18 | +``` |
| 19 | + |
| 20 | +Then use the `OracleDialect` class as the dialect option in the Sequelize constructor: |
| 21 | + |
| 22 | +```ts |
| 23 | +import { Sequelize } from '@sequelize/core'; |
| 24 | +import { OracleDialect } from '@sequelize/oracle'; |
| 25 | + |
| 26 | +const sequelize = new Sequelize({ |
| 27 | + dialect: OracleDialect, |
| 28 | + database: 'mydb', |
| 29 | + username: 'myuser', |
| 30 | + password: 'mypass', |
| 31 | + host: 'localhost', |
| 32 | + port: 1521, |
| 33 | +}); |
| 34 | +``` |
| 35 | + |
| 36 | +:::info |
| 37 | + |
| 38 | +The underlying connector library used by Sequelize for Oracle is the [node-oracledb](https://www.npmjs.com/package/oracledb) package. |
| 39 | +In Sequelize v7, the minimum supported node-oracledb version uses thin mode by default which **doesn't require** installing [Oracle Client](https://www.oracle.com/database/technologies/instant-client/downloads.html) libraries. |
| 40 | +For information on using Thick mode, refer to the [Using Thick mode](#using-thick-mode) section. |
| 41 | + |
| 42 | +::: |
| 43 | + |
| 44 | +## Connection Options |
| 45 | + |
| 46 | +import ConnectionOptions from './_connection-options.md'; |
| 47 | + |
| 48 | +<ConnectionOptions /> |
| 49 | + |
| 50 | +The following options are accepted by the OracleDialect: |
| 51 | + |
| 52 | +| Option | Description | |
| 53 | +| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 54 | +| `database` | Oracle "serviceName" to use for this connection | |
| 55 | +| `username` | Oracle database user to authenticate as | |
| 56 | +| `password` | The password of that Oracle database user | |
| 57 | +| `port` | The port number to connect to. (Default: 1521) | |
| 58 | +| `host` | The hostname of the database to connect to. (Default: localhost) | |
| 59 | +| `connectString` | The connectString of the database instance to connect to. | |
| 60 | +| `appContext` | An array of application context entries for the connection, where each entry is [namespace, name, value]. | |
| 61 | +| `accessToken` | The access token to connect to OCI IAM or Microsoft Azure token based authentication. | |
| 62 | +| `accessTokenConfig` | The access token config object for OCI or Microsoft Azure token based authentication. | |
| 63 | +| `walletPassword` | The password to decrypt the PEM-encoded private certificate, if it is encrypted. | |
| 64 | +| `walletLocation` | The directory where the wallet can be found. | |
| 65 | +| `edition` | Sets the name used for Edition-Based Redefinition by this connection. | |
| 66 | +| `events` | Determines if the standalone connection is created using Oracle Call Interface events mode. | |
| 67 | +| `externalAuth` | boolean property to allow external authentication. | |
| 68 | +| `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 | |
| 69 | +| `newPassword` | The new password to use for the database user. | |
| 70 | +| `sslAllowWeakDNMatch` | boolean property to use either a weaker or more secure DN matching behavior when the sslServerDNMatch property is set. | |
| 71 | +| `httpsProxy` | The name or IP address of a proxy host to use for tunneling secure connections. | |
| 72 | +| `httpsProxyPort` | The port to be used to communicate with the proxy host. (Default: 0). | |
| 73 | +| `debugJdwp` | This property allows using the Java Debug Wire Protocol (JDWP) to debug PL/SQL code called by node-oracledb. | |
| 74 | +| `retryCount` | The number of times that a connection attempt should be retried before the attempt is terminated. | |
| 75 | +| `retryDelay` | The number of seconds to wait before making a new connection attempt. | |
| 76 | +| `connectTimeout` | The timeout duration in seconds for an application to establish an Oracle Net connection. | |
| 77 | +| `transportConnectTimeout` | The maximum number of seconds to wait to establish a connection to the database host. (Default: 20.0) | |
| 78 | +| `expireTime` | The number of minutes between the sending of keepalive probes. | |
| 79 | +| `sdu` | The Oracle Net Session Data Unit (SDU) packet size in bytes. | |
| 80 | +| `connectionIdPrefix` | The application specific prefix parameter that is added to the connection identifier. | |
| 81 | +| `configDir` | The directory in which the Optional Oracle Net Configuration Files are found. | |
| 82 | +| `sourceRoute` | Enables network routing through multiple protocol addresses. The value of this property can be ON or OFF. | |
| 83 | +| `sslServerCertDN` | The distinguished name (DN) that should be matched with the certificate DN. | |
| 84 | +| `sslServerDNMatch` | Determines whether the server certificate DN should be matched in addition to the regular certificate verification that is performed. | |
| 85 | +| `poolAlias` | Specifies which previously created pool in the driver connection pool cache to use to obtain the connection from. | |
| 86 | +| `privilege` | The privilege to use when establishing connection to the database. | |
| 87 | +| `shardingKey` | Allows a connection to be established directly to a database shard. | |
| 88 | +| `stmtCacheSize` | The number of statements to be cached in the statement cache of each connection. | |
| 89 | +| `superShardingKey` | Allows a connection to be established directly to a database shard. | |
| 90 | +| `tag` | Used when getting a connection from a connection pool. | |
| 91 | +| `useSNI` | To enable a connection optimization feature which uses Server Name Indication (SNI) extension of the TLS protocol. | |
| 92 | +| `networkCompression` | boolean to indicate if network data compression needs to be enabled or disabled for a database connection. | |
| 93 | +| `networkCompressionThreshold` | The minimum data size, in bytes, for which compression should be performed on the Oracle Net Session Data Unit (SDU). | |
| 94 | +| `driverName` | The name of the driver that is used by the client to connect to Oracle Database. | |
| 95 | +| `machine` | The name of the host machine from where the connection originates. | |
| 96 | +| `osUser` | The name of the operating system user that initiates the database connection. | |
| 97 | +| `program` | The name of the program connecting to the database. | |
| 98 | +| `terminal` | The name of the terminal from where the connection originates. | |
| 99 | +| `walletContent` | The security credentials required to establish a mutual TLS (mTLS) connection to Oracle Database. | |
| 100 | + |
| 101 | +:::info |
| 102 | + |
| 103 | +Please refer to the [node-oracledb documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/oracledb.html#id31) for more information about what each of these options do. |
| 104 | + |
| 105 | +::: |
| 106 | + |
| 107 | +## Using Thick mode |
| 108 | + |
| 109 | +To use Thick mode in a Sequelize v7 application, you must manually initialize the Oracle Client libraries in your application code before instantiating Sequelize: |
| 110 | + |
| 111 | +1. Install the `oracledb` package. |
| 112 | + ```bash npm2yarn |
| 113 | + npm i oracledb |
| 114 | + ``` |
| 115 | +2. Install any Oracle Client libraries like the [Oracle Instant Client](https://www.oracle.com/database/technologies/instant-client/downloads.html) binaries in your operating system. |
| 116 | + Details to enable thick mode can be found [here](https://node-oracledb.readthedocs.io/en/latest/user_guide/appendix_a.html#oracle-client-library-loading). |
| 117 | + |
| 118 | +3. Call `initOracleClient()` at the very beginning of your application entry point as shown below: |
| 119 | + |
| 120 | + ```ts |
| 121 | + const oracledb = require('oracledb'); |
| 122 | + const { Sequelize } = require('@sequelize/core'); |
| 123 | + const { OracleDialect } = require('@sequelize/oracle'); |
| 124 | + |
| 125 | + // 1. Manually initialize the Oracle Client (Required for Thick Mode) |
| 126 | + try { |
| 127 | + // Thick mode requires Oracle Client or Oracle Instant Client libraries. |
| 128 | + // On Windows and macOS you can specify the directory containing the |
| 129 | + // libraries at runtime or before Node.js starts. On other platforms (where |
| 130 | + // Oracle Client libraries are available) the system library search path must always |
| 131 | + // include the Oracle library path before Node.js starts. If the search path |
| 132 | + // is not correct, you will get a DPI-1047 error. See the node-oracledb |
| 133 | + // installation documentation. |
| 134 | + let clientOpts = {}; |
| 135 | + // On Windows and macOS platforms, set the environment variable |
| 136 | + // NODE_ORACLEDB_CLIENT_LIB_DIR to the Oracle Client library path |
| 137 | + if (process.platform === 'win32' || process.platform === 'darwin') { |
| 138 | + clientOpts = { libDir: process.env.NODE_ORACLEDB_CLIENT_LIB_DIR }; |
| 139 | + } |
| 140 | + oracledb.initOracleClient(clientOpts); |
| 141 | + } catch (err) { |
| 142 | + // Handle initialization errors (e.g., binaries not found) |
| 143 | + console.error(err); |
| 144 | + } |
| 145 | + |
| 146 | + // 2. Initialize Sequelize |
| 147 | + const sequelize = new Sequelize({ |
| 148 | + dialect: OracleDialect, |
| 149 | + // ... connection options |
| 150 | + }); |
| 151 | + ``` |
0 commit comments