直接ルーティングをサポートするAPI

Oracle接続プールおよびドライバはOracle Globally Distributed Databaseをサポートしています。

JDBC、UCP、OCIおよびOracle Data Provider for .NET (ODP.NET)は、接続チェックの一部としてシャーディング・キーを認識します。Apache Tomcat、WebsphereおよびWebLogicはシャーディングのためのUCPサポートを活用し、PHP、Python、PerlおよびNode.jsはOCIサポートを活用します。

Oracle JDBC API

Oracle Java Database Connectivity (JDBC)には、Oracle Globally Distributed Database構成内のデータベース・シャードに接続するためのAPIがあります。

JDBCドライバは指定されたシャーディング・キーおよびスーパー・シャーディング・キーを認識し、データが含まれている該当シャードに接続します。シャードに対する接続が確立されると、DML、SQL問合せなどのサポートされているデータベース操作は通常どおりに実行されます。

シャード対応アプリケーションは、データベース・シャーディングAPIを使用してシャーディング・キーを指定することで特定のシャードに接続します。

• OracleShardingKeyインタフェースは、現在のオブジェクトが、シャード・データベースで使用されるシャーディング・キーを表します。
• OracleShardingKeyBuilderインタフェースは、サポートされている様々なデータ型のサブキーを持つ複合シャーディング・キーを作成します。このインタフェースでは、新しいJDK 8ビルダー・パターンを使用してシャーディング・キーを作成します。
• OracleConnectionBuilderインタフェースは、ユーザー名とパスワード以外の追加パラメータを使用して、接続オブジェクトを構築します。
• OracleDataSourceクラスにより、createConnectionBuilderメソッドとcreateShardingKeyBuliderメソッドはデータベース・シャードのサポートが可能になります。
• OracleXADataSourceクラスにより、createConnectionBuilderメソッドはデータベース・シャードのサポートが可能になります。
• OracleConnectionクラスにより、setShardingKeyIfValidメソッドとsetShardingKeyメソッドはデータベース・シャードのサポートが可能になります。
• OracleXAConnectionクラスにより、setShardingKeyIfValidメソッドとsetShardingKeyメソッドはデータベース・シャードのサポートが可能になります。

詳細と例は、『Oracle Database JDBC開発者ガイド』を参照してください。

例9-1 JDBCを使用したシャード対応アプリケーション・コードの例

次のコードでは、JDBCシャーディングAPIの使用方法を示します

OracleDataSource ods = new OracleDataSource();
   ods.setURL("jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(HOST=myhost)(PORT=1521)(PROTOCOL=tcp))(CONNECT_DATA=(SERVICE_NAME=myorcldbservicename)))");
   ods.setUser("hr");
   ods.setPassword("hr");
 
  // Employee name is the sharding Key in this example.
  // Build the Sharding Key using employee name as shown below.

   OracleShardingKey employeeNameShardKey = ods.createShardingKeyBuilder()
                                               .subkey("Mary", JDBCType.VARCHAR)// First Name
                                               .subkey("Claire", JDBCType.VARCHAR)// Last Name
                                               .build();

   OracleShardingKey locationSuperShardKey = ods.createShardingKeyBuilder() // Building a super sharding key using location as the key
                                                .subkey("US", JDBCType.VARCHAR)
                                                .build();

   OracleConnection connection = ods.createConnectionBuilder()
                                    .shardingKey(employeeNameShardKey)
                                    .superShardingKey(locationSuperShardKey)
                                    .build();

Oracle Call Interface

Oracle Call Interface (OCI)には、Oracle Globally Distributed Database構成内のデータベース・シャードに接続するためのインタフェースがあります。

チャンクを対象に読取りまたは書込みを行う要求を作成するには、接続開始ステップでそのチャンクを格納している適切なデータベース(シャード)にアプリケーションをルーティングする必要があります。このルーティングを行うには、データ・キーを使用します。データ・キーにより、特定のチャンクへのルーティング(シャーディング・キーを指定)またはチャンクのグループへのルーティング(スーパー・シャーディング・キーを指定)が可能になります。

操作対象のチャンクを含む適切なシャードに接続するためには、アプリケーションでキーを指定してから、シャードされたOracle Databaseへの接続(スタンドアロン接続またはOCIセッション・プールから取得された接続)を取得する必要があります。OCIセッション・プールでは、プールから接続をチェックアウトする前にデータ・キーを指定する必要があります。

大まかに言うと、シャーディング・キーとシャード・グループ・キーを構成して、基礎となる接続でセッションを取得するには、次のステップを実行する必要があります。

1. シャーディング・キー記述子を割り当てるため、OCIDescriptorAlloc()をコールし、シャーディング・キーを構成するためにOCI_DTYPE_SHARDING_KEYとして記述子型パラメータを指定します。
2. シャード・グループ・キー記述子を割り当てるため、OCIDescriptorAlloc()をコールし、シャード・グループ・キーを構成するためにOCI_DTYPE_SHARDING_KEYとして記述子型パラメータを指定します。
3. シャーディング・キーおよびシャード・グループ・キー情報が含まれる前のステップの初期化済認証ハンドルを使用してOCISessionGet()をコールし、シャーディング・キーで指定されたシャードおよびチャンクと、シャード・グループ・キーで指定されたチャンクのグループに対するデータベース接続を取得します。

OCIセッション・プールへの接続、スタンドアロン接続、およびカスタム・プール接続の作成の詳細は、『Oracle Call Interface開発者ガイド』を参照してください。

Oracle Universal Connection Pool API

Oracle Universal Connection Pool (UCP)には、Oracle Globally Distributed Database構成内のデータベース・シャードに接続するためのAPIがあります。

シャード対応のアプリケーションは、createShardingKeyBuilderおよびcreateConnectionBuilderという拡張シャーディングAPIを使用してシャーディング・キーを指定することによって、特定のシャードへの接続を取得します。

大まかに言うと、アプリケーションがシャード・データベースと連携するようにするには、次のステップに従う必要があります。

1. シャード・ディレクタおよびグローバル・サービスが反映されるようにURLを更新します。

2. 次のプール・パラメータをプール・レベルおよびシャード・レベルで設定します。

   • setInitialPoolSizeでは、UCPの開始時に作成する接続の初期数を設定します。

   • setMinPoolSizeでは、実行時にプールで維持する接続の最小数を設定します。

   • setMaxPoolSizeでは、接続プールに許容される接続の最大数を設定します

   • setMaxConnectionsPerShardでは、シャードごとの最大接続数を設定します

3. createShardingKeyBuilderを使用してシャーディング・キー・オブジェクトを作成します。

4. createConnectionBuilderを使用して接続を確立します。

5. 特定のシャードのスコープ内でトランザクションを実行します。

例9-2 UCPシャーディングAPIを使用した接続の確立

シャーディング・キーを作成し、UCPシャーディングAPIコールを使用して接続を確立する方法を示すコード片を次に示します。

...

PoolDataSource pds =                                
     PoolDataSourceFactory.getPoolDataSource();
  
  // Set Connection Pool properties
pds.setURL(DB_URL);
pds.setUser("hr");  
pds.setPassword("****");
pds.setInitialPoolSize(10);
pds.setMinPoolSize(20);
pds.setMaxPoolSize(30);
                
// build the sharding key object

OracleShardingKey shardingKey = 
    pds.createShardingKeyBuilder() 
      .subkey("[e-mail]", OracleType.VARCHAR2)
      .build(); 

  // Get an UCP connection for a shard
Connection conn = 
    pds.createConnectionBuilder()
     .shardingKey(shardingKey)
     .build();
...

例9-3 UCP接続プールを使用したシャード対応アプリケーション・コードの例

この例では、プール設定をプール・レベルおよびシャード・レベルで定義しています。

import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;

import oracle.jdbc.OracleShardingKey;
import oracle.jdbc.OracleType;
import oracle.jdbc.pool.OracleDataSource;
import oracle.ucp.jdbc.PoolDataSource;
import oracle.ucp.jdbc.PoolDataSourceFactory;

public class MaxConnPerShard
{    
  public static void main(String[] args) throws SQLException
  {    
    String url = "jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(HOST=shard-dir1)(PORT=3216)
 (PROTOCOL=tcp))(CONNECT_DATA=(SERVICE_NAME=shsvc.shpool.oradbcloud)(REGION=east)))";
    String user="testuser1", pwd = "testuser1";  
  
    int maxPerShard = 100, initPoolSize = 20;    

    PoolDataSource pds = PoolDataSourceFactory.getPoolDataSource();
    pds.setConnectionFactoryClassName(OracleDataSource.class.getName());
    pds.setURL(url);
    pds.setUser(user);
    pds.setPassword(pwd);
    pds.setConnectionPoolName("testpool");
    pds.setInitialPoolSize(initPoolSize);    

    // set max connection per shard
    pds.setMaxConnectionsPerShard(maxPerShard);
    System.out.println("Max-connections per shard is: "+pds.getMaxConnectionsPerShard());
                
    // build the sharding key object
    int shardingKeyVal = 123;    
    OracleShardingKey sdkey = pds.createShardingKeyBuilder()
        .subkey(shardingKeyVal, OracleType.NUMBER)
        .build();

    // try to build maxPerShard connections with the sharding key
    Connection[] conns = new Connection[maxPerShard];
    for (int i=0; i<maxPerShard; i++)
    {      
      conns[i] = pds.createConnectionBuilder()
          .shardingKey(sdkey)
          .build();
    
Statement stmt = conns[i].createStatement();
      ResultSet rs = stmt.executeQuery("select sys_context('userenv', 'instance_name'),
       sys_context('userenv', 'chunk_id') from dual");
      while (rs.next()) {
        System.out.println((i+1)+" - inst:"+rs.getString(1)+", chunk:"+rs.getString(2));
      }
      rs.close();
      stmt.close();
    }      

    System.out.println("Try to build "+(maxPerShard+1)+" connection ...");
    try {
      Connection conn = pds.createConnectionBuilder()
          .shardingKey(sdkey)
          .build();

      Statement stmt = conn.createStatement();
      ResultSet rs = stmt.executeQuery("select sys_context('userenv', 'instance_name'),
       sys_context('userenv', 'chunk_id') from dual");
      while (rs.next()) {
        System.out.println((maxPerShard+1)+" - inst:"+rs.getString(1)+",
         chunk:"+rs.getString(2));
      }
      rs.close();
      stmt.close();

      System.out.println("Problem!!! could not build connection as max-connections per
        shard exceeded");
      conn.close();
    } catch (SQLException e) {
      System.out.println("Max-connections per shard met, could not build connection
        any more, expected exception: "+e.getMessage());
    }    
    for (int i=0; i<conns.length; i++)
    {
      conns[i].close();
    }        
  }
}

Oracle Data Provider for .NET API

Oracle Data Provider for .NET (ODP.NET)には、Oracle Globally Distributed Database構成内のデータベース・シャードに接続するためのAPIがあります。

ODP.NET APIを使用すると、シャード対応アプリケーションはOracleConnectionクラスのSetShardingKey(OracleShardingKey shardingKey, OracleShardingKey superShardingKey)インスタンス・メソッドなどのAPIでシャーディング・キーおよびスーパー・シャーディング・キーを指定することで、特定のシャードへの接続を取得します。

大まかに言うと、.NETアプリケーションがシャード・データベースと連携するようにするには、次のステップを実行する必要があります。

1. ODP.NET管理対象外ドライバを使用します。

   シャーディングは、ODP.NET接続プールを使用する場合もODP.NET接続プールを使用しない場合もサポートされます。各プールは、シャード・データベースの異なるシャードへの接続を保持できます。

   ノート:

   Oracle Data Provider for .NET (ODP.NET)管理対象外ドライバは、Oracle Database 23cでは非推奨であり、将来のリリースでサポートされなくなる可能性があります。既存の管理対象外ODP.NETアプリケーションをODP.NET管理対象ドライバに移行することをお薦めします。

2. OracleShardingKeyクラスを使用して、シャーディング・キー、およびスーパー・シャーディング・キーの別のインスタンスを設定します。

3. ODP.NETが指定したシャーディング・キーおよびスーパー・シャーディング・キーを使用する接続を返すことができるように、OracleConnection.Open()を呼び出す前に、OracleConnection.SetShardingKey()メソッドを呼び出します。

   これらのキーは、OracleConnectionがクローズ状態のときに設定する必要があります。そうしないと、例外がスローされます。

例9-4 ODP.NETを使用したシャード対応アプリケーション・コードの例

using System;
using Oracle.DataAccess.Client;
 
class Sharding
{
  static void Main()
  {
    OracleConnection con = new OracleConnection
      ("user id=hr;password=hr;Data Source=orcl;");
    //Setting a shard key
    OracleShardingKey shardingKey = new OracleShardingKey(OracleDbType.Int32, 123);
    //Setting a second shard key value for a composite key
    shardingKey.SetShardingKey(OracleDbType.Varchar2, "gold");
    //Creating and setting the super shard key
    OracleShardingKey superShardingKey = new OracleShardingKey();
    superShardingKey.SetShardingKey(OracleDbType.Int32, 1000);
    
    //Setting super sharding key and sharding key on the connection
    con.SetShardingKey(shardingKey, superShardingKey);
    con.Open();

    //perform SQL query
  }
}