1.1   対象読者

このドキュメントは、PostgresForestデータベースにおいて動作させるアプリ ケーションプログラムの設計および開発を行う開発者を対象としています。

本ドキュメントでは、読者はPostgreSQLの管理に関する一般的な知識を持って いることを前提としています。PostgreSQLに関する情報は、 PostgreSQLのドキュメント (http://www.postgresql.jp/document/pg815doc/html/) 等を 参照してください。

2.1   複数ノード間におけるデータの整合性

PostgresForestでは、複数のDBノードにSQL文を発行することで高可用性およ び分散処理を実現します。

SERIAL型、OID、CURRENT_TIMESTAMPやnow()関数などは、アプリケーションか ら使用されると、それぞれのDBサーバ上で自動的に値が生成されます。これら の値は、複数のDBサーバ上で使用されると、その値が必ずしも同じ値になると は限らず、結果として一貫性の取れない状況が発生する可能性があります。

PostgresForestでは、複数のサーバ上で自動生成されるこれらの値の整合性を 保つ方法を提供していませんので、これらの機能を使っている場合には、アプ リケーション側で対処を行う必要があります。

2.2   テーブルのパーティション化にともなうSQL文の制約

PostgresForestでは、単一のテーブルを分割して複数サーバに配置し、アプリ ケーションからは（仮想的に）単一のテーブルとしてアクセスすることが可能 ですが、パーティションの配置の仕方によってはSQL文の利用に制限が生じる ことがあります。

具体的には、パーティション化したテーブルのパーティションを分散させて配 置した場合、JOINやサブクエリなどの利用に制限が発生します。

2.3   エラーの発生とそのハンドリング

PostgresForestでは、アプリケーションにエラー（SQLException）が返却され るケースは、大別して

• アプリケーションSQLのエラー（サポートしていないSQL、テーブルが存在しない、など）
• ノードの障害などで処理を継続できない場合
• ノード間デッドロックが発生した場合（後述）

があります。

これらのエラーが発生した場合には、アプリケーション側からトランザクショ ンを明示的にロールバックする必要があります。

2.4   ノード間デッドロック

SQLベースのレプリケーションを実装したPostgresForestでは、複数のトラン ザクションから同一レコードの更新を行うと、ノード間デッドロックが発生す る場合があります。ノード間のデッドロックが発生すると、アプリケーション に制御が戻らず、そのアプリケーションは処理を継続することができなくなり ます。

そのようなトランザクションを発行する場合、SELECT FOR UPDATEやLOCKなど のSQL文に、あらかじめ「NOWAIT」を付けて実行するか、あるいは利用する PostgreSQL （サーババックエンド）にロックのタイムアウトを検出する同梱 のパッチを適用する必要があります。

3.1   テーブル種別の選び方

PostgresForestでは、以下の二種類のテーブル種別を利用することができます （実際の作成方法については、「PostgresForest管理者ガイド」を参照）。

3.2   テーブル設計時の留意事項

4.1   接続方法

PostgresForestのドライバは、JDBCドライバとして実装されているため、デー タベースへ接続する場合には、通常のJDBCアプリケーションと同様に Connectionオブジェクトを生成する必要があります。

なお、JDBC接続する際の接続文字列（JDBC URL）は、PostgresForest専用の設 定項目を指定する必要があります。

4.2   接続文字列の書式

PostgresForestでは、JDBCの接続文字列としてPostgresForest特有の設定情報 を指定する必要があります。

書式:

jdbc:postgresforest:GSC=<GSC情報>[[,<GSC情報>]…][;CONFIG=<CONFIG名>]@<ユーザDB名>

設定方法サンプル:

Class.forName("org.postgresforest.Driver");
Connection con = DriverManager.getConnection(
       "jdbc:postgresforest:GSC=//host1:5432/gsc,//host2:5432/gsc;CONFIG=myconfig@testdb",
       "forest", "passwd");

接続文字列の「CONFIG=」を変更することで、GSCのコンフィギュレーションを 使い分けることができます。例えば、オンラインのWebトランザクションの場 合にはタイムアウトを30秒程度とし、バッチ処理の場合にはタイムアウトを5 分にする、などの切り替えが可能となります。

4.3   DataSourceにおける設定

TomcatなどでDataSourceを用いてデータベースへの接続を行う場合には、以下のように設定を行います。

Tomcat4.1での設定サンプル:

<Resource name="jdbc/testdb" auth="Container"

          type="javax.sql.DataSource"/>
<ResourceParams name="jdbc/testdb">
  <parameter><name>username</name><value>forest</value></parameter>

  <parameter><name>password</name><value>forest</value></parameter>
  <parameter><name>driverClassName</name>
    <value>org.postgresforest.Driver</value></parameter>

  <parameter><name>url</name>
    <value>jdbc:postgresforest:GSC=//host1:5432/gsc,//host2:5432/gsc@testdb</value></parameter>
</ResourceParams>

Tomcat5.5での設定サンプル:

<Resource name="jdbc/testdb" auth="Container" type="javax.sql.DataSource"
             maxActive="100" maxIdle="30" maxWait="10000"

             username="forest" password="forest" driverClassName="org.postgresforest.Driver"
             url="jdbc:postgresforest:GSC=//host1:5432/gsc,//host2:5432/gsc@testdb" />

4.4   Autocommitモード

PostgresForestでは、原則としてautocommitモードをfalseとして使用する必 要があります。:

con.setAutoCommit(false);

PostgresForestでは、DBノード間の整合性を保つために全ノードに対する COMMIT処理をユーザが指示したタイミング（commit()メソッド呼び出し時）で 同時に行います。そのため、autocommitモードがonの状態で自動的にCOMMITが 行われてしまうと、一部のDBノードでエラーが発生した場合に整合性が崩れる 原因となります。

5.1   SQL処理の概要

PostgresForestでは、ユーザーアプリケーションからのSQL文を独自に解析し、 SQL文の分散処理・並列処理などを内部で行っています。そのため、構文解析 の仕様、およびPostgresForestのパーティションテーブルに対する処理の仕様 上、SQL文の一部において利用上の制約があります。

SELECT * FROM t1 WHERE uid=1001;

SELECT * FROM t1 WHERE uid IN (1001, 1002, 1003);

SELECT * FROM t1;

SELECT * FROM t1 WHERE uid > 1000;

5.2   全般的な制約事項

5.3   SELECTコマンドにおける制約と留意点

5.4   INSERTコマンド

5.5   UPDATEコマンドにおける制約と留意点

The partition attribute (COLNAME) is specified to be t\he column to change.

5.6   DELETEコマンド

5.7   その他のSQLコマンド

5.8   PostgresForestにおけるシーケンス機能の実装方法

シーケンス（シリアル型）については、PostgresForestにおいてはノードごとに値が変わってくる可 能性があるため、使用を推奨しない。

シリアル型を用いて採番をする必要がある場合、採番用のテーブルを作成し、以下のようにして実装 することを推奨する。

採番テーブル作成方法:

CREATE TABLE seq ( seqname VARCHAR(16) PRIMARY KEY, seqval INTEGER );
INSERT INTO seq VALUES ( ‘testseq’, 0 );

シーケンス更新用トランザクション:

BEGIN;
SELECT seqval FROM seq WHERE seqname = ‘testseq’ FOR UPDATE NOWAIT;
UPDATE seq SET seqval = seqval + 1 WHERE seqname = ‘testseq’;
COMMIT;

「SELECT FOR UPDATE NOWAIT」は、該当レコードのレコードロックを獲得しよ うとするが、ロックを獲得できなかった場合にエラーが返却される。 PostgresForest環境においてノード間においてロック獲得の競合が発生すると、 ノード間デッドロックが起こりうるが、NOWAITを付加することによって、ロッ ク獲得エラー（SQLException）がアプリケーションに返却される。

よって、エラーが発生した場合にアプリケーションからリトライを行うことで、 シーケンスと同等の採番の仕組みを実現することができる。PostgresForestに おけるNOWAITを用いたシーケンスの実装は、以下のようになる。詳細は、 PostgresForest配布パッケージの examples/Sequence/ 以下のサンプルコード を参照のこと。

なお、SQLExceptionのgetMessage()で取得できるエラーメッセージは以下のようになる。:

ERROR: could not obtain lock on row in relation "seq"
  Location: heapam.c:2157:heap_lock_tuple
 ServerSQLState: 55P03

また、getSQLState()によって取得できるコードは「55P03」となる。この例外をキャッチした場合 には、トランザクションをロールバックし、再度リトライすることができる。

6.1   エラー処理概要

各DBノードで発生したエラー（例外）については、

1. アプリケーションにエラーとして返却するもの
2. PostgresForest内部で処理してアプリケーションには正常を返却するもの

とに大別される。

エラー種別の判別は、エラーメッセージの文字列およびエラーコードをもって行われる（PostgreSQL において発生し得るエラーコードの一覧は、PostgreSQLオフィシャルマニュアル「付録A. PostgreSQLエラーコード」を参照）。

エラーが発生した場合に、エラーが発生したノードを障害発生とみなして切り離した上で正常な結果 を返してきたノードだけを使って処理を続行させるか、あるいは他のノードも含めてロールバックを 行うかは設定可能であり、デフォルトの設定がdisterror.propertiesファイルに記述されている。

6.2   切り離し対象エラーとロールバック対象エラー

以下のエラーが発生した場合には、PostgresForestでは該当エラーを障害と判断し、発生ノードを切 り離した上で、エラーが発生していないノードだけで処理を継続する。アプリケーションに対しては、 「正常」が返却される（例外は発生しない）。

以下のエラーが発生した場合には、切り離しをせずにすべてのノードをロール バックして、アプリケーションにエラーを返却する。

6.3   ノード間デッドロック発生時のエラー処理

複数のDBノード上でロック獲得が競合し、ノードをまたいでデッドロック状態 になる場合、ロックのタイムアウト検出の設定を行うことで、デッドロック状 態を解消することができる（要ロックタイムアウトパッチ）。

ノードをまたいだデッドロックが検出され、トランザクションがロールバック されると、アプリケーションに対しては以下のエラーが返却される。

アプリケーションでは、SQL例外をキャッチして上記例外かどうかを調べるこ とによって、ノード間デッドロックの発生およびその解消を確認することがで きる。エラー種別の判別は、SQLException のgetMessage()あるいは getSQLState()メソッドを使って行う。

上記例外が発生すると、該当のトランザクションはエラー発生状態となり、ア プリケーションからはロールバックしかできない状態となる。

6.4   エラーコード一覧

PostgreSQLオフィシャルマニュアル「付録A. PostgreSQLエラーコード 」を参照。

7.1   サーバステータスの取得方法

PostgresForestのドライバを用いて、サーバステータスなどを取得するには、 以下のクラスおよびメソッドを用いる。:

ResultSet rs = conn.getGscMetaData().getServer();
while ( rs.next() )
{
    int serverId = rs.getInt(1);
    int status = rs.getInt(3);
}

7.2   その他メタデータへのアクセス

PostgresForsetのメタデータ（GSC情報）へのアクセスには、以下のクラスおよびメソッドを用いる。