loopback-connector-oracle

Oracleは、Oracle社によって開発されたリレーショナル・データベースです。loopback-connector-oracle モジュールは、node-oracledb に基づくLoopBackフレームワークのための Oracle コネクタです。

前提条件

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でデータベースにすぐ接続できる最もシンプルな形式です。 この場合、データソースには以下の設定があります。

例えば、以下のようになります。

{
  "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"
});

コネクションプーリングオプション

例えば、以下のようになります。

{
  "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 の型

Oracle の型から JSON

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>, and PASSWORD are optional parameters. The default values are localhost, 1521, admin, and 0raclep4ss respectively. The DATABASE setting is always XE.

• Run the test:

  npm test