-
-
Notifications
You must be signed in to change notification settings - Fork 171
feat: Add Oracle Database dialect specific documentation for V7 #827
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
+297
−129
Merged
Changes from all commits
Commits
Show all changes
24 commits
Select commit
Hold shift + click to select a range
fbd5474
Inital commit
7bf43b7
Merge branch 'main' into v7_docs_oracle
prajalg 88e02ce
initial commit : added table columns for oracle + modified oracle pag…
prajalg dd67784
Merge branch 'main' into v7_docs_oracle
prajalg ee1607b
incorporate review comments
prajalg bc171bd
some more changes in data-types.mdx
prajalg 9ff4c3e
TIME datatype not supported
prajalg 0963154
removed invalid connectOptions
prajalg a765a26
now added all connection options for oracle (that are in type desc) &…
prajalg 7b6c89b
updated the datatype links to point to oracledb 26ai
prajalg 360b624
added documentation for enabling thick mode in sequelize
prajalg d75d330
changed dialect name from 'oracle' to 'Oracle Database'
prajalg dafb7a2
incorporated review comments
prajalg 8d0f32d
some link changes
prajalg 2951a03
Merge branch 'main' into v7_docs_oracle
prajalg bb5d432
updated right outer join doc link
prajalg 73829d5
Merge branch 'main' into v7_docs_oracle
prajalg 66ab108
Merge branch 'main' into v7_docs_oracle
prajalg 1ac39b4
changed Oracle Database to Oracle at all places
prajalg 3578170
address review comments
prajalg 3fc8ed7
Merge branch 'main' into v7_docs_oracle
prajalg f1d638f
minor rewording
prajalg a1d7fdd
modified note change for DataTypes.TEXT
prajalg 5beab47
Merge branch 'main' into v7_docs_oracle
prajalg File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,151 @@ | ||
| --- | ||
| title: Oracle | ||
| sidebar_position: 1 | ||
| --- | ||
|
|
||
| # Sequelize for Oracle | ||
|
|
||
| :::info Version Compatibility | ||
|
|
||
| See [Releases](/releases#oracle-support-table) to see which versions of Oracle are supported. | ||
|
|
||
| ::: | ||
|
|
||
| To use Sequelize with Oracle, you need to install the `@sequelize/oracle` dialect package: | ||
|
|
||
| ```bash npm2yarn | ||
| npm i @sequelize/oracle | ||
| ``` | ||
|
|
||
| Then use the `OracleDialect` class as the dialect option in the Sequelize constructor: | ||
|
|
||
| ```ts | ||
| 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](https://www.npmjs.com/package/oracledb) package. | ||
| 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. | ||
| For information on using Thick mode, refer to the [Using Thick mode](#using-thick-mode) section. | ||
|
|
||
| ::: | ||
|
|
||
| ## Connection Options | ||
|
|
||
| import ConnectionOptions from './_connection-options.md'; | ||
|
|
||
| <ConnectionOptions /> | ||
|
|
||
| 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](https://node-oracledb.readthedocs.io/en/latest/api_manual/oracledb.html#id31) 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. | ||
| ```bash npm2yarn | ||
| npm i oracledb | ||
| ``` | ||
| 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. | ||
| 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). | ||
|
|
||
| 3. Call `initOracleClient()` at the very beginning of your application entry point as shown below: | ||
|
|
||
| ```ts | ||
| 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 | ||
| }); | ||
| ``` | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.