1. PL/SQLパッケージおよびタイプ・リファレンス
  2. DBMS_CONNECTION_POOL

47 DBMS_CONNECTION_POOL

DBMS_CONNECTION_POOLパッケージは、データベース常駐接続プール(DRCP)を管理するインタフェースを提供します。

データベース初期化パラメータENABLE_PER_PDB_DRCPは、DRCPがCDB ROOT DRCPモードで構成されるか、PDBごとのDRCPモードで構成されるかを制御します。デフォルト値はFALSEで、この場合DRCPがCDBレベルで構成されます。

  • データベース構成パラメータENABLE_PER_PDB_DRCPの値がTRUEに設定されている場合、次のようになります:

    • 各PDB管理者は、DBMS_CONNECTION_POOLパッケージを使用してプール構成を管理できます。ROOTがDBMS_CONNECTION_POOLパッケージを使用してプール構成を管理しようとすると、エラーがスローされます。

    • cpool$表のnum_cbrokおよびmaxconn_cbrokプール・パラメータの値は無視されます。PDB管理者は、DBMS_CONNECTION_POOL.ALTER_PARAM()プロシージャを使用してこれらのパラメータを変更することはできません。これらのパラメータは、CONNECTION_BROKERSデータベース・パラメータを使用して設定できます。これらのパラメータを動的に変更できるのは、ROOTのみです。

  • ENABLE_PER_PDB_DRCPパラメータの値がFALSEに設定されている場合、ROOTのみがDBMS_CONNECTION_POOLパッケージを使用してプール構成を管理できます。PDB管理者がDBMS_CONNECTION_POOLパッケージを使用してプール構成を管理しようとすると、エラーがスローされます。
  • 次のDRCPパラメータには、0からSB4MAXVAL (2147483647) - 1の範囲の値を指定できます。
    • minsize
    • num_cbrok
    • maxconn_cbrok

参照:

データベース常駐接続プールの詳細は、『Oracle Database概要』を参照してください。

この章では、次の項目について説明します。

47.1 DBMS_CONNECTION_POOLサブプログラムの要約

次の表では、DBMS_CONNECTION_POOLパッケージのサブプログラムをアルファベット順に示し、簡単に説明します。

表47-1 DBMS_CONNECTION_POOLパッケージのサブプログラム

サブプログラム 説明

ADD_POOLプロシージャ

 新しいプールを複数プールDRCPに追加します。

ALTER_PARAMプロシージャ

他のパラメータに影響を与えることなく、特定の構成パラメータをスタンドアロン単位で変更します。

CONFIGURE_POOLプロシージャ

拡張オプションでプールを構成します。

REMOVE_POOLプロシージャ

 プールを複数プールDRCPから削除します。

RESTORE_DEFAULTSプロシージャ

プールをデフォルト設定に戻します

START_POOLプロシージャ

操作を行うためにプールを開始します。このプロシージャをコールした後にのみ、接続クライアントでプールを使用してセッションを作成できます。

STOP_POOLプロシージャ

プールを停止し、登録されている接続クライアントに対してプールを使用不可にします。

47.1.1 ADD_POOLプロシージャ

このプロシージャを使用して、新しいDRCPプールを追加できます。

構文

DBMS_CONNECTION_POOL.ADD_POOL (
   pool_name                IN VARCHAR2,
   minsize                  IN PLS_INTEGER   DEFAULT 0,
   maxsize                  IN PLS_INTEGER   DEFAULT 40,
   incrsize                 IN PLS_INTEGER   DEFAULT 2,
   session_cached_cursors   IN PLS_INTEGER   DEFAULT 20,
   inactivity_timeout       IN PLS_INTEGER   DEFAULT 300,
   max_think_time           IN PLS_INTEGER   DEFAULT 120,
   max_use_session          IN PLS_INTEGER   DEFAULT 500000,
   max_lifetime_session     IN PLS_INTEGER   DEFAULT 86400,
   max_txn_think_time       IN PLS_INTEGER   DEFAULT 0);

パラメータ

ノート:

プールの追加時にプール構成を認識している場合は、次のパラメータの値を指定できます。そうでない場合は、後でCONFIGURE_POOLサブプログラムをコールし、新しいプール名および構成オプションを指定できます。

表47-2 ADD_POOLプロシージャのパラメータ

パラメータ 説明

pool_name

DRCPに追加するプールの名前。

minsize

プール内のプール・サーバーの最小数。デフォルト値は0です。

maxsize

プールで許可されるプール・サーバーの最大数。デフォルト値は40です。

incrsize

アプリケーションの要求時にプール・サーバーが使用不可になっている場合にプールに追加されるプール・サーバーの数。デフォルト値は2です。

session_cached_cursors

各プール・サーバー・セッションでキャッシュするセッション・カーソルの数。デフォルト値は20です。

プールのすべての接続でSESSION_CACHED_CURSORSを有効にします。これは、既存のinit.oraパラメータです。

inactivity_timeout

プールのアイドル・セッションのTTL(有効期間)。このパラメータは、プールが最大容量まで使用されていないときに、プールを縮小するのに役立ちます。この期間中プールで接続がアイドル状態のままになると、接続はクローズされます。デフォルト値は300です。

max_think_time

プールからオープン・トランザクションが含まれていないプール・サーバーを取得した後のクライアントの最大非アクティブ時間(秒数)。クライアント・アプリケーションが、プールからプール・サーバーを取得した後、MAX_THINK_TIMEで指定した時間内にデータベース・コールを発行しない場合、プール・サーバーは解放されてクライアント接続が終了します。デフォルト値は120です。

max_use_session

接続を取得し、プールに解放できる最大回数。デフォルト値は500000です。

max_lifetime_session

プールされたセッションのTTL (有効期間)の秒数。デフォルト値は86400です。

max_txn_think_time

プールからオープン・トランザクションを含むプール・サーバーを取得した後のクライアントの最大非アクティブ時間(秒数)。クライアント・アプリケーションがプールからプール・サーバーを取得した後、MAX_TXN_THINK_TIMEで指定した時間内にデータベース・コールを発行しない場合、プール・サーバーは解放されてクライアント接続が終了します。このパラメータのデフォルト値は、MAX_THINK_TIMEパラメータの値です。オープン・トランザクションを含む接続のための時間を確保するために、MAX_TXN_THINK_TIMEパラメータの値は、MAX_THINK_TIME値よりも高い値に設定できます。

ノート:

pool_nameパラメータには、次の検証チェックがあります。

  • プール名は一意である必要があります。
  • 英字で始まる必要があります。
  • 2番目以降の位置に英数字を含めることができます。
  • 2番目以降の位置にアンダースコア(_)を含めることができます。
  • プール名に許可される最大長は128です。

参照:

このプロシージャで構成可能なすべてのデータベース常駐接続プールのパラメータのリストおよび説明については、『Oracle Database管理者ガイド』を参照してください。

例

exec dbms_connection_pool.add_pool('mypool')

47.1.2 ALTER_PARAMプロシージャ

このプロシージャは、特定のデータベース常駐接続プール(DRCP)構成パラメータをスタンドアロン単位で変更します。他のパラメータは影響を受けません。

構文

DBMS_CONNECTION_POOL.ALTER_PARAM (
   pool_name     IN  VARCHAR2 DEFAULT 'SYS_DEFAULT_CONNECTION_POOL',   
   param_name    IN  VARCHAR2,   
   param_value   IN  VARCHAR2);

パラメータ

表47-3 ALTER_PARAMプロシージャのパラメータ

パラメータ 説明

pool_name

構成するプール。

param_name

CONFIGURE_POOLからの任意のパラメータ名。

ブローカ・パラメータ: NUM_CBROKおよびMAXCONN_CBROKの場合、次のルールが適用されます。

  • PDBごとのDRCPが有効になっている場合、ALTER_PARAM()を使用してこれらのパラメータを設定することはできません。データベース初期化パラメータconnection_brokersを使用することが、それらを設定する唯一の方法です。

  • CDB ROOTレベルのDRCPでは、これらのパラメータがconnection_brokersを使用して設定されていない場合、管理者はALTER_PARAM()プロシージャを使用してパラメータを設定できます。

    これらのパラメータを設定するには、connection_brokersを使用することをお薦めします。

param_value

param_nameのパラメータ値。

参照:

このプロシージャで構成可能なすべてのDRCPのパラメータのリストおよび説明については、Oracle Database管理者ガイドを参照してください。

例外

表47-4 ALTER_PARAMプロシージャの例外

例外 説明

ORA-56500

接続プールが見つかりません

ORA-56504

接続プール構成パラメータ名が無効です

ORA-56505

接続プール構成パラメータ値が無効です

ORA-56507

接続プールの変更構成に失敗しました

例

DBMS_CONNECTION_POOL.ALTER_PARAM(
   'SYS_DEFAULT_CONNECTION_POOL', 'MAX_LIFETIME_SESSION', '120');

47.1.3 CONFIGURE_POOLプロシージャ

このプロシージャは、拡張オプションでプールを構成します。

構文

DBMS_CONNECTION_POOL.CONFIGURE_POOL (
   pool_name                IN VARCHAR2 DEFAULT 'SYS_DEFAULT_CONNECTION_POOL',
   minsize                  IN NUMBER   DEFAULT 4,
   maxsize                  IN NUMBER   DEFAULT 40,
   incrsize                 IN NUMBER   DEFAULT 2,
   session_cached_cursors   IN NUMBER   DEFAULT 20,
   inactivity_timeout       IN NUMBER   DEFAULT 300,
   max_think_time           IN NUMBER   DEFAULT 120,
   max_use_session          IN NUMBER   DEFAULT 500000,
   max_lifetime_session     IN NUMBER   DEFAULT 86400,
   max_txn_think_time       IN NUMBER);

パラメータ

表47-5 CONFIGURE_POOLプロシージャのパラメータ

パラメータ 説明

pool_name

構成するプール。

minsize

プール内にプールされるサーバーの最小数。

maxsize

プール内にプールできるサーバーの最大数。

incrsize

アプリケーションの要求時に、プールされたサーバーが使用不可になっている場合、プールを増大させるプールされたサーバーの数。

session_cached_cursors

プールのすべての接続でSESSION_CACHED_CURSORSを有効にします。これは、既存のinit.oraパラメータです。

inactivity_timeout

プールのアイドル・セッションのTTL(有効期間)。このパラメータは、プールが最大容量まで使用されていないときに、プールを縮小するのに役立ちます。この期間中プール接続がアイドル状態のまま続くと、接続は切断されます。

max_think_time

プールからオープン・トランザクションが含まれていないプール・サーバーを取得した後のクライアントの最大非アクティブ時間(秒数)。クライアント・アプリケーションが、プールからプール・サーバーを取得した後、MAX_THINK_TIMEで指定した時間内にデータベース・コールを発行しない場合、プール・サーバーは解放されてクライアント接続が終了します。

max_use_session

接続を取得し、プールに解放できる最大回数。

max_lifetime_session

プールされたセッションのTTL(有効期間)。

max_txn_think_time

プールからオープン・トランザクションを含むプール・サーバーを取得した後のクライアントの最大非アクティブ時間(秒数)。クライアント・アプリケーションがプールからプール・サーバーを取得した後、MAX_TXN_THINK_TIMEで指定した時間内にデータベース・コールを発行しない場合、プール・サーバーは解放されてクライアント接続が終了します。このパラメータのデフォルト値は、MAX_THINK_TIMEパラメータの値です。オープン・トランザクションを含む接続のための時間を確保するために、MAX_TXN_THINK_TIMEパラメータの値は、MAX_THINK_TIME値よりも高い値に設定できます。

例外

表47-6 CONFIGURE_POOLプロシージャの例外

例外 説明

ORA-56500

接続プールが見つかりません

ORA-56507

接続プールの変更構成に失敗しました

使用上のノート

  • 時間はすべて秒単位で指定します。

  • すべてのパラメータは、要求パターンの統計に基づいて設定する必要があります。

  • minsizeは、サーバー・リソースの消費に下限が設けられることを考慮して設定する必要があります。このパラメータは、非アクティブ期間が短い場合に、タイムアウトによってプールが極端に少なくなることを防ぎます。

  • maxsizeは、同時実行性、応答時間およびサーバー・リソースの消費に上限が設けられることを考慮して設定する必要があります。

  • session_cached_cursorsは、通常、最も頻繁に使用される文の数に設定されます。これにより、サーバーのカーソル・リソースが占有されます。

  • 不確かな場合は、incrementおよびinactivity_timeoutは設定しないでください。プールには、適切なデフォルト値が使用されます。

  • max_use_sessionおよびmax_lifetime_sessionは、一定期間に新しいセッションを取得することで、潜在的なバグ、リーク、蓄積、問題などに対してソフトウェアの回復または予防的アプローチを可能にします。

  • 接続プールでは、プールされたサーバーの5%が認証のために保持され、少なくとも1つのプールされたサーバーが認証のために常時保持されます。maxsizeパラメータの設定時には、認証と接続の両方に対して十分な数のプールされたサーバーがあることを確認します。

47.1.4 REMOVE_POOLプロシージャ

このプロシージャを使用して、DRCPからプールを削除できます。

構文

DBMS_CONNECTION_POOL.REMOVE_POOL (
   pool_name     IN  VARCHAR2);

パラメータ

表47-7 REMOVE_POOLプロシージャのパラメータ

パラメータ 説明

pool_name

削除するプール。

ノート:

次の場合、このプロシージャはエラーを生成します。

  • 指定したプールが存在しない。
  • デフォルトのプールを削除しようとした。
  • アクティブなプールを停止せずに削除しようとした。

例外

表47-8 REMOVE_POOLプロシージャの例外

例外 説明

ORA-56620

プールが存在しないため、プール<pool_name>の削除に失敗しました。

ORA-56620

データベースが読取り専用であるため、プール<pool_name>の削除に失敗しました。
ORA-56620 プールがアクティブであるため、プール<pool_name>の削除に失敗しました。
ORA-56620 プール名は空にできないため、プール<pool_name==NULL>の削除に失敗しました。
ORA-56620 デフォルトのプールは削除できないため、プールSYS_DEFAULT_CONNECTION_POOLの削除に失敗しました。

ノート:

エラー・メッセージは動的文字列であるため、同じエラー番号がすべての例外エラーに使用されます。

例

exec dbms_connection_pool.remove_pool('mypool')

47.1.5 RESTORE_DEFAULTSプロシージャ

このプロシージャは、プールをデフォルト設定に戻します。

構文

DBMS_CONNECTION_POOL.RESTORE_DEFAULTS (
   pool_name   IN  VARCHAR2 DEFAULT 'SYS_DEFAULT_CONNECTION_POOL');

パラメータ

表47-9 RESTORE_DEFAULTSプロシージャのパラメータ

パラメータ 説明

pool_name

戻されるプール。

例外

表47-10 RESTORE_DEFAULTSプロシージャの例外

例外 説明

ORA-56500

接続プールが見つかりません

ORA-56507

接続プールの変更構成に失敗しました

47.1.6 START_POOLプロシージャ

このプロシージャは、操作を行うためにプールを開始します。これがコールされた後に、接続クラスがプールを使用してセッションを作成できます。

構文

DBMS_CONNECTION_POOL.START_POOL (
   pool_name  IN  VARCHAR2 DEFAULT 'SYS_DEFAULT_CONNECTION_POOL');

パラメータ

表47-11 START_POOLプロシージャのパラメータ

パラメータ 説明

pool_name

開始するプール。

例外

表47-12 START_POOLプロシージャの例外

例外 説明

ORA-56500

接続プールが見つかりません

ORA-56501

接続プールの起動に失敗しました

使用上のノート

インスタンスを再起動(停止後に起動)すると、DRCPプールは自動的に開始されます。

47.1.7 STOP_POOLプロシージャ

このプロシージャは、プールを停止し、登録されている接続クラスに対してプールを使用不可にします。

構文

DBMS_CONNECTION_POOL.STOP_POOL (
   pool_name   IN   VARCHAR2 DEFAULT 'SYS_DEFAULT_CONNECTION_POOL',
   draintime   IN   PLS_INTEGER DEFAULT 2147483647);

パラメータ

表47-13 STOP_POOLプロシージャのパラメータ

パラメータ 説明

pool_name

停止するプール。

draintime

アクティブなDRCPプールは、指定した接続ドレイン時間後に閉じることも、接続がアイドル状態になるのを待たずにすぐに閉じることもできます。

draintimeには、次の整数値を指定できます:

  • 0: バインド済のプールされたサーバーをすぐに閉じます。

  • x: バインド済のプールされたサーバーをx秒後に閉じます。

ノート:

古い動作(プールがアイドル状態で非アクティブになってからのみプールを閉じる)を保持する場合は、draintimeパラメータを渡さないでください。

例外

表47-14 STOP_POOLプロシージャの例外

例外 説明

ORA-56500

接続プールが見つかりません

ORA-56506

接続プールの停止に失敗しました

使用上のノート

このプロシージャにより、プールが停止しオフラインになります。プールに関連付けられた永続的なデータ(プール名、構成パラメータなど)は破損しません。