[PHP-doc 31] pg_copy_to/from Manual (draft)

[Youichi Iwakiri]

いわきりです
#こちらにも参加させてもらいました

PostgreSQL拡張モジュールに下記の関数を大垣さんに
追加してもらいました。
 pg_copy_to()
 pg_copy_from()

英語のマニュアルは大垣さんが用意してくださるそうなので
日本語の方だけ(というか英語での記述は出来ません)書きました。

ご意見等ありましたらご連絡下さい。

XMLで書いたほうが良いのでしょうが取りあえずplain textです。
#環境を構築せんといかんですね。


----
関数名
 pg_copy_to

 (PHP4 >= 4.2.0)
 pg_copy_to -- テーブル全体を配列として取得する

説明
mixed pg_copy_to(int connection_id, string table_name [, string delim [, string null_as]])

 引数
   connection_id
     pg_[p]connect()により返されるPostgreSQLコネクションID
   table_name
     対象とするテーブル名
   delim
     列を区切るための識別子
     ※任意の1バイト文字のみが指定可能(multibyte文字は未サポート)
     ※デフォルトは"\t"
   null_as
     NULL値の代替文字列を指定可能
     ※デフォルトは"\N"

 返り値:
  行を一要素とする一次元配列(array)を返す。
  失敗時はFALSE。

 この関数はPostgreSQLのSQLインタプリタであるpsqlの\copyコマンドに
 模した機能を提供するものです。SQLコマンドであるCOPYとは異なる点に
 注意して下さい。
 COPYコマンドはバックエンドが直接ファイルアクセスを行うためPostgreSQLの
 所持者(owner)で無ければ実行不可能ですが、\copyコマンドはフロントエンド側に
 テーブル全体の複製を取得しクライアント環境でファイルアクセスを実現するものです。
 そのため、データベースとの接続がローカル/リモート接続に関わらずクライアントの
 アクセス権によりファイル操作が行えます。

 pg_copy_to(), pg_copy_from()はテーブルとのデータの遣り取りを配列を介してのみ
 行えます。直接ファイルアクセスする機能は提供しません。
 

 例1 PostgreSQLよりテーブルを取得しファイルへ書き込む

 <?php
 $conn = pg_connect("dbname=sample");
 // "sample"という名前のデータベースに接続
 if (!$conn) {
   die("Can't connect DB server");
 }

 $rows = pg_copy_to($conn, "test");
 // "test"という名前のテーブル全行を$rowsに配列として取得
 pg_close($conn);
 
 $fd = fopen("test.dat", "wb");
 fwrite($fd, implode("\n", $rows));
 // $rowsを"\n"(改行)で連結した文字列に変換しファイルへ出力する
 fclose($fd);
 ?>

 例2 PostgreSQLよりテーブルをCSV形式で取得しブラウザへ送信

 <?php
 $conn = pg_connect("dbname=sample");
 // "sample"という名前のデータベースに接続
 if (!$conn) {
   die("Can't connect DB server");
 }

 $rows = pg_copy_to($conn, "test", ",");
 // "test"という名前のテーブル全行を$rowsに配列として取得
 // 区切り文字(delimiter)に","を指定
 pg_close($conn);

 $file = implode("\r\n", $rows);
 // Windows9x/XP/NTの行末コードで連結
 $file_size = strlen($file);

 header("Content-type: application/vnd.ms-excel");
 header("Content-Disposition: inline; filename=test.csv");
 header("Content-Length: $file_size");

 print $file;
 }
 
 ?>

----
関数名
 pg_copy_from

 (PHP4 >= 4.2.0)
 pg_copy_from -- 配列の要素をテーブルへ追加する

説明
int pg_copy_from(int connection_id, string table_name, array rows [, string delim [, string null_as]])

 引数
   connection_id
     pg_[p]connect()により返されるPostgreSQLコネクションID
   table_name
     対象とするテーブル名
   rows
     テーブルへ追加する各行を保持する配列
   delim
     列を区切るための識別子
     ※任意の1バイト文字のみが指定可能(multibyte文字は未サポート)
     ※デフォルトは"\t"
   nullas
     NULL値の代替文字列を指定可能
     ※デフォルトは"\N"

 戻り値
  成功した場合はtrue、失敗時はfalseを返す。

 更に詳細な情報は、pg_copy_to()を参照下さい。 


例1 PostgreSQLに行を追加する
 <?php
 $conn = pg_connect("dbname=sample");
 // "sample"という名前のデータベースに接続

 $rows = array();
 $rows[] = "data1,data2,data3";        // データは`,'区切り
 $rows[] = "data4,data5,data6";
 $rows[] = "data7,data8,data9";
 pg_copy_from($conn, "test", $rows, ",");
 // "test"という名前のテーブルに","区切りのデータを追加

 pg_close($conn);
 ?>

例2 PostgreSQLにファイルの内容を追加する

 <?php
 $conn = pg_connect("dbname=sample");
 // "sample"という名前のデータベースに接続

 $rows = file("/tmp/file");
 pg_copy_from($conn, "test", $rows);

 pg_close($conn);
 ?>

--- 
ここまで