Node-oracledb 5.0 にネストされたカーソル、データベースの起動、プリフェッチのチューニングが追加 (2020/06/29)

6月 25, 2020

https://blogs.oracle.com/opal/node-oracledb-50-adds-nested-cursors-database-startup-and-prefetch-tuning
投稿者：Christopher Jones | Senior Principal Product Manager

リリースのお知らせです。
Oracle DatabaseにアクセスするためのNode.jsモジュールである
node-oracledbの新しいメジャーリリースがnpmから公開されています。

主な機能

Oracle クライアントライブラリを見つけるための新しい初期化機能、
クエリフェッチのチューニングのためのカスタマイズ可能なプリフェッチ、
入れ子になったカーソルのサポート、データベースの起動とシャットダウン。

node-oracledb 5.0 リリースは、Node.js ユーザーに大小さまざまな機能強化をもたらします。
すべての詳細については CHANGELOG を参照してください。

主な変更点

Oracle Clientライブラリを検索するための新しい初期化関数。

新しい oracledb.initOracleClient() 関数を使用して、Oracle Client の使用を構成することができます。
例えば、Oracle Clientライブラリの場所を渡すことができます。
これはWindowsとmacOSで最も便利です。特に最近のmacOSの変更によりライブラリへのアクセスが制限されています。
Linuxではいくつかの制限があります。この関数は、tnsnames.oraのようなオプションの設定ファイルがあるディレクトリ名も受け付けます。
この新機能は、WindowsとmacOS上でのNode.jsのインストールを自動化し、
複数のOracle Clientライブラリのバージョンをインストールしておくことを容易にし、
ユーザーにアプリケーションを配布することを容易にします。

例えば、Windows上でOracle Instant ClientライブラリをC:\oracleinstantclient_19_6に解凍した場合、
このディレクトリをPATHに追加する必要がなくなりました。代わりに、アプリケーション内のディレクトリを設定することができます。

const oracledb = require('oracledb');
try {
oracledb.initOracleClient({libDir: 'C:/oracle/instantclient_19_6'});
} catch (err) {
console.error('Whoops!');
console.error(err);
process.exit(1);
}

(libdir にバックスラッシュを使用している場合は、それを 2 倍にする必要があります)。

node-oracledb 5 for macOS では、既存の Windows の機能を拡張して、
Instant Client のライブラリを node-oracledb のバイナリモジュールと同じディレクトリに置くことができるようにしました。
initOracleClient() の代わりに package.json スクリプトセクションを使用することができます。

"scripts": {
"postinstall": "ln -s $HOME/instantclient/libclntsh.dylib $(npm root)/oracledb/build/Release",
"start": "node index.js"
},

これは、macOS上でInstant Clientを~/libに置くほど便利ではないかもしれませんが、
最近のNode.jsバイナリはデフォルトでこのディレクトリにアクセスしなくなりました。
しかし、最近の Node.js バイナリはデフォルトではこのディレクトリにアクセスできなくなりました。
AppleのmacOSユーザーは、更新されたインストール手順と新機能を確認してください。

Node-oracledbの初期化を参照してください。

クエリのチューニングのためのプリフェッチ。

新しい execute() オプション prefetchRows を既存の fetchArraySize オプションと組み合わせて使用することで、
クエリ行のフェッチのパフォーマンスとメモリ使用量を調整することができます。
これらのチューニングパラメータを使用することで、クエリ実行後の行のフェッチに使用する内部バッチサイズを調整することで、
システムやネットワークの負荷を軽減することができます。
これらのパラメータを設定することで、ネットワークコストとアプリケーションのメモリ使用量やデータコピーのバランスをとることができます。
値は、行がアプリケーションに返される方法やタイミングには影響しません。

例えば、クエリが小さく固定した数の行を返す場合、次のようにします。

const myoffset = 0; // do not skip any rows (start at row 1)
const mymaxnumrows = 20; // get 20 rows

sql = `SELECT last_name
FROM employees
ORDER BY last_name
OFFSET :offset ROWS FETCH NEXT :maxnumrows ROWS ONLY`;

binds = { offset: myoffset, maxnumrows: mymaxnumrows };

options = { prefetchRows: mymaxnumrows + 1, fetchArraySize: mymaxnumrows };

result = await connection.execute(sql, binds, options);

この例では、すべての行をプリフェッチすることで、
内部実行とデータフェッチのフェーズをデータベースへの1回のラウンドトリップだけで完了させることができます。
以前のnode-oracledbのバージョンでは、2つの行だけがプリフェッチされ、
2回目のラウンドトリップで残りの行がフェッチされていました。prefetchRowsの値は、
クエリで返される行数よりも1つ大きい値になることに注意してください。
クエリに最適な prefetchRows と fetchArraySize の値は、チューニングによって決定されます。
場合によっては、prefetchRows をデフォルト値の 2 のままにしたまま
fetchArraySize を変更することだけが最良であることに気づくかもしれません。

フェッチパフォーマンスのチューニングを参照してください。

入れ子になったカーソルのサポート。

以下のようなクエリをサポートしています。

const sql = `SELECT department_name,
CURSOR(SELECT salary, commission_pct
FROM employees e
WHERE e.department_id = d.department_id
ORDER BY salary) as nc
FROM departments d
ORDER BY department_name`;

const result = await connection.execute(sql);
console.dir(result.rows, {depth: null});

以下のような出力が得られます。

[
[ 'Accounting', [ [ 8300, null ], [ 12008, null ] ] ],
[ 'Administration', [ [ 4400, null ] ] ],
[ 'Benefits', [] ],
[ 'Construction', [] ],
[ 'Contracting', [] ],
[ 'Control And Credit', [] ],
[ 'Corporate Tax', [] ],
[
'Executive',
[ [ 17000, null ], [ 17000, null ], [ 24000, null ] ]
],
[
'Finance',
[
[ 6900, null ],
[ 7700, null ],
[ 7800, null ],
[ 8200, null ],
[ 9000, null ],
[ 12008, null ]
]
],
. . .

「ネストされたカーソルの取得」を参照してください。

データベースの起動とシャットダウン。

新しいスタートアップおよびシャットダウン機能により、データベースを簡単かつ柔軟に制御することができます。
「データベースの起動とシャットダウン」を参照してください。

新しいプール属性 queueMax が追加されました。

これは、すべてのプールされた接続がすでに使用されているときにキューに入れることができる pool.getConnection() リクエストの数を制限することで、
接続の嵐から保護するのに役立ちます。制限を超えた接続リクエストは、 queueTimeout 期間を待たずに直ちに失敗します。
デフォルトの queueMax は 500 です。これを 0 に設定するとキューイングを無効にすることができ、
-1 に設定するとすべてのリクエストがキューイングされるようになります。

カスタムプロミスライブラリのサポートを削除しました。

内部の JavaScript の実装は、よりクリーンな async/await モデルを使用するようにリファクタリングされ、
カスタム Promise ライブラリのサポートは必然的に削除されました。
代わりにネイティブの Node.js Promise の実装を使用してください。

このリリースでは、テストスイートとドキュメントも改善されました。ぜひチェックしてみてください。

リソース

Node-oracledb installation instructions are here.

Node-oracledb documentation is here.

Node-oracledb change log is here.

Issues and questions about node-oracledb can be posted on GitHub or Slack (link to join Slack).

Finally, contributions to node-oracledb are more than welcome, see CONTRIBUTING.

A new major release of node-oracledb, the Node.js module for accessing Oracle Database, is available from npm.

このブログを検索

Oracle Cloud Infrastructure Blog(翻訳)