loopback-connector-oracle
Oracleは、Oracle社によって開発されたリレーショナル・データベースです。loopback-connector-oracle
モジュールは、node-oracledb に基づくLoopBackフレームワークのための Oracle コネクタです。
For more information, see the LoopBack documentation.
前提条件
Node.js: Oracle コネクタは、Node.js バージョン 4.x または 6.x が必要です。
Windows: 32bit版のWindowsでは、32bit版のNode.jsを使用しなければなりません。64bit版のWindowsでは、64bit版のNode.jsを使用しなければなりません。詳細は、 Node-oracledb Installation on Windows を参照してください。
Oracle: Oracleコネクタは、Oracleクライアントライブラリ 11.2以上が必要です。また、Oracle データベースサーバ 9.2以上に接続できます。
インストール
アプリケーションの最上位ディレクトリで、以下のコマンドを実行してコネクタをインストールします。
$ npm install loopback-connector-oracle --save
以下で説明するようにデータソース生成ツールを使用してOracleデータソースを作成する場合、生成ツールは npm install を実行するので、これを行う必要はありません。
インストールに関する詳細な手引きは Installing the Oracle connector を参照してください。
node-oracledb モジュールと Oracleインスタントクライアントのインストールを単純にするためには、npm install を実行する時に、依存関係として loopback-oracle-installer を使用して node-oracledb
(oracledb) をインストール・構成します。
config.oracleUrl
プロパティを使って、ローカル環境に対応するnode-oracle(oracledb)バンドルをダウンロードするためのベースURLを定義します。
バンドルファイル名は、loopback-oracle-<platform>-<arch>-<version>.tar.gz
です。version
は package.json における version
と同じです。
"dependencies": {
"loopback-oracle-installer": "git+ssh://git@github.com:strongloop/loopback-oracle-installer.git",
...
},
"config": {
"oracleUrl": "http://7e9918db41dd01dbf98e-ec15952f71452bc0809d79c86f5751b6.r22.cf1.rackcdn.com"
},
...
oracleUrl
は、LOOPBACK_ORACLE_URL 環境変数をセットすることで上書き可能です。
例えば、MacOSX用の v1.5.0 の完全なURLは以下のとおりです。
http://7e9918db41dd01dbf98e-ec15952f71452bc0809d79c86f5751b6.r22.cf1.rackcdn.com/loopback-oracle-MacOSX-x64-1.5.0.tar.gz
Linux では、libaio
ライブラリが必要です。
Ubuntu/Debian では、以下のコマンドでインストールできます。
sudo apt-get install libaio1
Fedora/CentOS/RHEL では、以下のコマンドでインストールできます。
sudo yum install libaio
Oracle データソースを作成する
Oracle データソースをアプリケーションに追加するには、データソース生成ツールを使用します。
生成ツールは、Oracleデータベースに接続する上で必要なデータベースサーバのホスト名・ポート番号・その他の設定を尋ねます。
その際、上記のnpm install
コマンドも実行します。
アプリケーションの /server/datasources.json
への入力は以下のようになります。
"mydb": {
"name": "mydb",
"connector": "oracle",
"tns": "demo",
"host": "myserver",
"port": 3306,
"database": "mydb",
"password": "mypassword",
"user": "admin"
}
追加のプロパティが必要な場合は、datasources.json
を編集して追加します。
コネクタのプロパティ
コネクタプロパティは、Oracle データベースを参照するためのネーミングメソッド に依ります。 LoopBack は3種類のネーミングメソッドが使用できます。
- 簡易接続: ホスト名/ポート番号/データベース名
- ローカルネーミング(TNS): Oracleがサポートする全ての属性を指定できる、完全な接続文字列の別名
- ディレクトリネーミング(LDAP):Oracleがサポートする全ての属性を指定できる、完全な接続文字列を探すためのディレクトリ
簡易接続
簡易接続は、TCP/IPでデータベースにすぐ接続できる最もシンプルな形式です。 この場合、データソースには以下の設定があります。
プロパティ | 型 | 既定値 | 説明 |
---|---|---|---|
host または hostname | String | localhost | Oracleデータベースサーバのホスト名またはIPアドレス |
port | Number | 1521 | Oracleデータベースサーバのポート番号 |
username または user | String | Oracleデータベースサーバに接続するユーザ名 | |
password | String | Oracleデータベースサーバに接続するパスワード | |
database | String | XE | Oracleデータベースのリスナー名 |
例えば、以下のようになります。
{
"demoDB": {
"connector": "oracle",
"host": "oracle-demo.strongloop.com",
"port": 1521,
"database": "XE",
"username": "demo",
"password": "L00pBack"
}
}
ローカルまたはディレクトリネーミング
ローカルとディレクトリネーミングは、両方共以下の設定ファイルを /oracle/admin
のようなTNS adminディレクトリに配置する必要があります。
sqlnet.ora
このファイルでは使用できるネーミングメソッドを指定します。例えば以下ようなものです。
NAMES.DIRECTORY_PATH=(LDAP,TNSNAMES,EZCONNECT)
tnsnames.ora
このファイルでは、接続文字列の別名を設定します。例えば以下のようなものです。
demo1=(DESCRIPTION=(CONNECT_DATA=(SERVICE_NAME=))(ADDRESS=(PROTOCOL=TCP)(HOST=demo.strongloop.com)(PORT=1521)))
ldap.ora
このファイルでは、LDAPサーバを設定します。
DIRECTORY_SERVERS=(localhost:1389)
DEFAULT_ADMIN_CONTEXT="dc=strongloop,dc=com"
DIRECTORY_SERVER_TYPE=OID
TNS_ADMIN 環境変数の設定
Oracleコネクタが設定を見つけるためには、’TNS_ADMIN’環境変数が.ora
ファイルを含むディレクトリを指すようにセットしなければなりません。
export TNS_ADMIN=< .ora ファイルを含むディレクトリ>
これで、データソースを設定するためにTNSエイリアスとLDAPサービス名の両方を使用できます。
var ds = loopback.createDataSource({
"tns": "demo", // tns プロパティは tns名またはLDAPサービス名のどちらでもよい
"username": "demo",
"password": "L00pBack"
});
コネクションプーリングオプション
プロパティ名 | 説明 | 既定値 |
---|---|---|
minConn | 接続プールにある最小の接続数 | 1 |
maxConn | 接続プールにある最大の接続数 | 10 |
incrConn |
接続プールの接続を増やす際の増分値 |
1 |
timeout | 接続プールの接続がタイムアウトするまでの秒数 Oracle コネクタはアイドル時間がタイムアウト時間を過ぎると接続を終了します。 | 10 |
例えば、以下のようになります。
{
"demoDB": {
"connector": "oracle",
"minConn":1,
"maxConn":5,
"incrConn":1,
"timeout": 10,
...
}
}
接続のトラブルシューティング
以下のようなエラーが表示された場合、
Error: ORA-24408: could not generate unique server group name
Oracle 11g クライアントは、自身のホスト名が 127.0.0.1
を指すエントリが必要です。
解決策:
ホスト名を確認します。以下のコマンドを実行してください。(例えば、マシン名が「earth」だとします)
$ hostname
earth
/etc/hosts
を更新して、127.0.0.1
がホスト名「earth」を指すようにします。
...
127.0.0.1 localhost earth
...
修正を確認するために、example/app.js
にある例を実行します。
$ node examples/app.js
詳しくは、StackOverflow の質問 を参照してください。
モデルプロパティ
Oracle モデル定義は、以下のプロパティから構成されます。
name
: モデルの名前。既定ではテーブルのキャメルケース。options
: モデルレベルのオプションや、Oracleのスキーマ・テーブルとの紐付け。properties
: Oracleの列との紐付けなどのプロパティ定義。
{
"name":"Inventory",
"options":{
"idInjection":false,
"oracle":{
"schema":"STRONGLOOP",
"table":"INVENTORY"
}
},
"properties":{
"productId":{
"type":"String",
"required":true,
"length":20,
"id":1,
"oracle":{
"columnName":"PRODUCT_ID",
"dataType":"VARCHAR2",
"dataLength":20,
"nullable":"N"
}
},
"locationId":{
"type":"String",
"required":true,
"length":20,
"id":2,
"oracle":{
"columnName":"LOCATION_ID",
"dataType":"VARCHAR2",
"dataLength":20,
"nullable":"N"
}
},
"available":{
"type":"Number",
"required":false,
"length":22,
"oracle":{
"columnName":"AVAILABLE",
"dataType":"NUMBER",
"dataLength":22,
"nullable":"Y"
}
},
"total":{
"type":"Number",
"required":false,
"length":22,
"oracle":{
"columnName":"TOTAL",
"dataType":"NUMBER",
"dataLength":22,
"nullable":"Y"
}
}
}
}
型の対応関係
LoopBackのデータ型に関する詳細は LoopBack の型を参照してください。
JSON から Oracle の型
LoopBack の型 | Oracle の型 |
---|---|
String JSON Text default |
VARCHAR2
既定の長さは 1024 |
Number | NUMBER |
Date | DATE |
Timestamp | TIMESTAMP(3) |
Boolean | CHAR(1) |
Oracle の型から JSON
Oracle Type | LoopBack Type |
---|---|
CHAR(1) | Boolean |
CHAR(n) VARCHAR VARCHAR2, LONG VARCHAR NCHAR NVARCHAR2 |
String |
LONG, BLOB, CLOB, NCLOB | Node.js のBuffer オブジェクト |
NUMBER INTEGER DECIMAL DOUBLE FLOAT BIGINT SMALLINT REAL NUMERIC BINARY_FLOAT BINARY_DOUBLE UROWID ROWID |
Number |
DATE TIMESTAMP |
Date |
Discovery and auto-migration
Model discovery
The Oracle connector supports model discovery that enables you to create LoopBack models based on an existing database schema using the unified database discovery API. For more information on discovery, see Discovering models from relational databases.
For an example of model discover, see example/app.js
.
Auto-migratiion
The Oracle connector also supports auto-migration that enables you to create a database schema from LoopBack models using the LoopBack automigrate method.
For more information on auto-migration, see Creating a database schema from models for more information.
LoopBack Oracle connector creates the following schema objects for a given model:
- A table, for example, PRODUCT
- A sequence for the primary key, for example, PRODUCT_ID_SEQUENCE
- A trigger to generate the primary key from the sequnce, for example, PRODUCT_ID_TRIGGER
Destroying models may result in errors due to foreign key integrity. First delete any related models by calling delete on models with relationships.
Running tests
Own instance
If you have a local or remote Oracle instance and would like to use that to run the test suite, use the following command:
- Linux
ORACLE_HOST=<HOST> ORACLE_PORT=<PORT> ORACLE_USER=<USER> ORACLE_PASSWORD=<PASSWORD> ORACLE_DATABASE=<DATABASE> npm test
- Windows
SET ORACLE_HOST=<HOST> SET ORACLE_PORT=<PORT> SET ORACLE_USER=<USER> SET ORACLE_PASSWORD=<PASSWORD> SET ORACLE_DATABASE=<DATABASE> npm test
Docker
If you do not have a local Oracle instance, you can also run the test suite with very minimal requirements.
- Assuming you have Docker installed, run the following script which would spawn an Oracle instance on your local machine:
source setup.sh <HOST> <PORT>
where
<HOST>
,<PORT>
,<USER>
, andPASSWORD
are optional parameters. The default values arelocalhost
,1521
,admin
, and0raclep4ss
respectively. TheDATABASE
setting is alwaysXE
. - Run the test:
npm test