いったんデータベースサーバへの接続の確立が成功すれば、この節で説明する関数を使ってSQLの問い合わせやコマンドを実行します。
PQexec サーバへコマンドを送り、その結果を待ちます。
PGresult *PQexec(PGconn *conn,
const char *query);
戻り値はPGresultへのポインタ、場合によってはNULLポインタです。メモリ不足の状態、あるいはバックエンドへのコマンド送信が不可能といった深刻なエラーの場合を除けば、通常 NULL 以外のポインタが返ります。戻り値がNULLの場合には、PGRES_FATAL_ERROR が起こった場合と同様に扱われなければいけません。エラーの詳しい情報は、 PQerrorMessage で得ることができます。
PGresult構造体は、バックエンドからの問い合わせ結果をカプセル化したものです。libpqアプリケーションのプログラマは、PGresultによる抽象化に注意を払うべきです。PGresultの内容は以下に挙げるアクセッサ関数を使って取り出してください。PGresult構造体中のフィールドは将来予告なく変更されることがあります。ですから直接フィールドを参照することは避けてください（PostgreSQLリリース6.4 の初期の段階から、PGresult構造体の定義を libpq-fe.h の中から外しました。以前に作成したプログラムが PGresultのフィールドを直接操作している場合、 libpq-int.hをインクルードすれば使い続けることができます。しかしそのプログラムは是非とも修正してください）。
PQresultStatus コマンドの結果ステータスを返します。
ExecStatusType PQresultStatus(const PGresult *res)
PQresultStatus は以下のうちどれかの値を返します。
PGRES_EMPTY_QUERY -- バックエンドへ送信した文字列が空だった。
PGRES_COMMAND_OK -- データを返さないコマンドの実行が成功した。
PGRES_TUPLES_OK -- 問い合わせの実行に成功した。
PGRES_COPY_OUT -- （サーバからの）データのコピーアウトの開始。
PGRES_COPY_IN -- （サーバーへの）データのコピーインの開始。
PGRES_BAD_RESPONSE -- サーバからの応答が不正だった。
PGRES_NONFATAL_ERROR
PGRES_FATAL_ERROR
結果ステータスがPGRES_TUPLES_OKであれば、問い合わせが返した行を以下で説明するルーチンを使って取り出すことができます。ただし、たまたまSELECT文が返す行が 0 個だったような場合でも PGRES_TUPLES_OKとなることに注意してください。 PGRES_COMMAND_OKは、INSERTやUPDATEのように行を返すことがありえないコマンドに対するステータスです。 PGRES_EMPTY_QUERYが返るのは、クライアントアプリケーション側にバグの可能性がある場合です。
PQresStatus PQresultStatusが返す列挙型のステータスコードから、コードを説明する文字列定数に変換します。
char *PQresStatus(ExecStatusType status);
PQresultErrorMessage 問い合わせに関するエラーメッセージを返します。エラーが何もなければ、空の文字列を返します。
char *PQresultErrorMessage(const PGresult *res);
（接続に対する）PQerrorMessageも、 PQexec または PQgetResult 呼び出しの直後なら（結果に対する）PQresultErrorMessageと同じ文字列を返します。しかし後続する操作を実行すると、接続に対するエラーメッセージは変化してしまうのに対し、PGresult はオブジェクトが破棄されるまでその内部のエラーメッセージを維持し続けます。この PQresultErrorMessageは個々のPGresult オブジェクトに結び付けられたステータスを見るときに、そして PQerrorMessageは接続における最後の操作のステータスを見るときに使ってください。
PQclear PGresult に割り当てられた記憶領域を解放します。個々の問い合わせ結果は、必要なくなったときに PQclearで解放するべきです。
void PQclear(PQresult *res);
PGresult オブジェクトは、必要な間保持することができます。新しい問い合わせを発行する場合でも、接続を閉じてしまうまでは PGresult は消えません。PGresult を解放するには、PQclearを呼び出さなくてはいけません。その操作に失敗してしまうと、フロントエンドアプリケーションのメモリリークを引き起こしてしまいます。
PQmakeEmptyPGresult 与えられたステータスを持った、空の PGresult オブジェクトを生成します。
PGresult* PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
空のPGresultオブジェクトを割り当て、初期化する、libpqの内部ルーチンです。一部のアプリケーションでは、それ自身でPGresultオブジェクトを生成すると便利なので（特にエラーステータスを含めたオブジェクト）この関数はエクスポートされています。connがNULLでなく、ステータスがエラーを示している場合、コネクションの現在のerrorMessageが PGresultにコピーされます。なお、 libpq 自体が返す PGresult と同じように、最後に PQclear をこのオブジェクトに対して呼び出すべきです。
PQescapeString SQL 問い合わせ内で使用される文字列をエスケープします。
size_t PQescapeString (char *to, const char *from, size_t length);
(例えば不特定多数のユーザから入力されるなど)信頼できない入力元から受けとった文字列を含める場合、セキュリティ上の理由よりそのままSQL問い合わせに含めてはいけません。その代わり、SQL パーサで解釈されてしまう特殊な文字をクォートしなければなりません。
PQescapeString はこの操作を行います。from は、エスケープ対象とする文字列の先頭文字を指し、length 引数はその文字列内の文字数をカウントします(終端を示すゼロバイトは不要でカウントされません)。to はバッファを指し、少なくともlengthの値の2倍以上を保持できるバッファでなければなりません。さもなくば、この動作は不定となります。 PQescapeString を呼び出すことで、from 文字列を、特別な文字を安全なものに置き換え、終端を示すゼロバイトを追加して、エスケープしたものがtoに書き出されます。 PostgreSQL の文字列リテラルを括らなければならない単一引用符は、結果文字列には含まれません。
PQescapeString はtoに書き出された文字数を返します。ただし、終端を示すゼロバイトは含まれません。 to from 文字列バッファが重なる場合の動作は不定です。
PQescapeBytea SQL 問い合わせ内で使用されるバイナリ文字列(bytea 型)をエスケープします。
unsigned char *PQescapeBytea(unsigned char *from,
size_t from_length,
size_t *to_length);
ある ASCII 文字は、SQL 文内の bytea 型の文字列リテラルの一部として使用される場合、エスケープされる必要があります(全ての文字をエスケープしても構いません)。一般的に文字をエスケープするためには、それを 10進のASCII 値を 3桁の8進数字に変換し、その前に2つのバックスラッシュを付けます。単一引用符(')とバックスラッシュ(\)文字は別途特別なエスケープシーケンスを持ちます。より詳細は、 ユーザガイド を参照して下さい。 PQescapeBytea は、こういった操作を行い、最低限必要な文字だけをエスケープします。
from 引数は、エスケープ対象とする文字列の先頭文字を指し、from_length 引数はこのバイナリ文字列内の文字数を反映します(終端を示すゼロバイトは不要で、カウントされません)。to_length 引数は、結果となるエスケープされた文字長を保持するためのバッファを指します。結果文字列長には、終端を示すゼロバイトは含まれません。
PQescapeBytea は from 引数のバイナリ文字列をエスケープしたものを、呼び出し側が用意したバッファに返します。返された文字列は、PostgreSQL 文字列リテラルパーサと bytea 入力関数で適切に処理されるように置換された、全ての特殊な文字列を持ちます。終端を示すゼロバイトも追加されます。PostgreSQLの文字列リテラルを括らなければならない単一引用符は、結果文字列には含まれません。
PQntuples 問い合わせの結果中のタプル（行）の数を返します。
int PQntuples(const PGresult *res);
PQnfields 問い合わせ結果の各行のフィールド（列）の数を返します。
int PQnfields(const PGresult *res);
PQfname 与えられたフィールド（列）インデックスに対応するフィールド名を返します。フィールドのインデックスは0から始まります。
char *PQfname(const PGresult *res,
int field_index);
PQfnumber 与えられたフィールド（列）の名前に対応するフィールドインデックスを返します。
int PQfnumber(const PGresult *res,
const char *field_name);
与えられた名前がどのフィールドとも一致しない場合は-1が返されます。
PQftype 与えられたフィールドインデックスに対応する、フィールドの型をで返します。返される整数は、型の内部コーディングです。フィールドインデックスは0から始まります。
Oid PQftype(const PGresult *res,
int field_index);
システムテーブルpg_typeに問い合わせることで、個々のデータ型の名前とプロパティを取得することができます。組み込み済みデータ型のOIDは、ソースツリーの中の src/include/catalog/pg_type.hに定義されています。
PQfmod 与えられたフィールドインデックスに対応する、そのフィールドのデータ型固有の修飾データを返します。フィールドインデックスは0から始まります。
int PQfmod(const PGresult *res,
int field_index);
PQfsize
与えられたフィールドインデックスに対応する、フィールドのサイズを
バイト数で返します。フィールドインデックスは0から始まります。
int PQfsize(const PGresult *res,
int field_index);
PQfsizeは、タプル内の指定されたフィールドに割り当てられた領域のサイズを返します。つまりこれは、このデータ型のサーバにおけるバイナリ表現のサイズです。フィールドが可変長の場合は-1を返します。
PQbinaryTuples PGresultがバイナリタプルデータを含む場合は1を、ASCIIデータの場合は0を返します。
int PQbinaryTuples(const PGresult *res);
いまのところ、バイナリのタプルデータを返せるのは、バイナリカーソルからデータを取り出す問い合わせだけです。
PQgetvalue PGresultから1つのタプルを取り、その中から1つのフィールド（列）の値を返します。タプルとフィールドのインデックスは0から始まります。
char* PQgetvalue(const PGresult *res,
int tup_num,
int field_num);
ほとんどの問い合わせでは、PQgetvalueが返す値は属性値をNULL終端の文字列で表現したものとなります。しかし PQbinaryTuples()が 1 の場合、 PQgetvalueが返す値はバックエンドサーバの内部フォーマットによるバイナリ型表現です（ただしフィールドが可変長であってもそのサイズ部分は含まれていません）。したがって、これを正しい C の型にキャストして変換するのはプログラマの責任です。PQgetvalueが返すポインタは、PGresult 構造体の記憶領域の一部を指します。これを変更してはいけません。もし値を PGresult 構造体自身の寿命を超えて使うのであれば、明示的に別の記憶領域にコピーしなければいけません。
PQgetisnull フィールドが NULL であるかどうかテストします。タプルとフィールドのインデックスは0から始まります。
int PQgetisnull(const PGresult *res,
int tup_num,
int field_num);
この関数はフィールドが NULL であれば 1 を、そうでなければ 0 を返します（PQgetvalue は NULL フィールドに対して NULL ポインタではなく、空文字列を返すことに注意してください）。
PQgetlength フィールド（属性）の長さをバイト数で返します。タプルとフィールドのインデックスは0から始まります。
int PQgetlength(const PGresult *res,
int tup_num,
int field_num);
これは個々のデータ値に対する実際のデータ長で、PQgetvalue が指すオブジェクトのサイズです。文字表現の値の場合、このサイズは PQfsize で得られるバイナリサイズとはあまり関連しないことに注意してください。
PQprint 指定された出力ストリームへ、すべてのタプルと、別途指定した属性名を表示します。
void PQprint(FILE* fout, /* 出力ストリーム */
const PGresult *res,
const PQprintOpt *po);
struct {
pqbool header; /* フィールド名ヘッダと行数表示の有無 */
pqbool align; /* フィールドの桁数合わせの有無 */
pqbool standard; /* 旧式フォーマット */
pqbool html3; /* HTMLテーブル出力の有無 */
pqbool expanded; /* テーブルを広げて表示 */
pqbool pager; /* 出力の際のページャ使用の是非 */
char *fieldSep; /* フィールド区切り文字 */
char *tableOpt; /* HTML 文のtable...
タグに追加する文字列 */
char *caption; /* HTML 文のcaption
に追加する文字列 */
char **fieldName; /* フィールド名に置き換わる文字列の配列。
NULL終端 */
} PQprintOpt;
この関数は、psqlにて問い合わせ結果を出力するために使用されていましたが、もはやそうしたケースはなく、この関数は積極的にサポートされなくなりました。
PQcmdStatus PGresult を生成した SQL コマンドのコマンド状態文字列を返します。
char * PQcmdStatus(const PGresult *res);
PQcmdTuples SQL コマンドによって影響を受けた行数を返します。
char * PQcmdTuples(const PGresult *res);
PGresult を生成した SQL コマンドが INSERT、UPDATE、DELETE の場合、これは影響を受けた行の数を文字列として返します。コマンドが全く影響を与えなければ、空文字列を返します。
PQoidValue SQL コマンドが正確に1行を OID を持つテーブルに挿入する INSERT の場合、挿入した行のオブジェクト ID を返します。さもなくば、 InvalidOid を返します。
Oid PQoidValue(const PGresult *res);
libpq ヘッダファイルを読み込んでいれば、 Oid 型と定数 InvalidOid は定義されています。これらはどちらも何らかの整数型です。
PQoidStatus SQL コマンドがINSERT の場合、挿入された行のオブジェクトIDを持つ文字列を返します(挿入された行が1行でなかった場合や対象としたテーブルが OID を持たない場合、この文字列は0 となります。)。
char * PQoidStatus(const PGresult *res);
この関数は PQoidValue によって置き換えられました。これはスレッドセーフではありません。