いったんデータベースサーバへの接続の確立が成功すれば、この節で説明する関数を使って 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で なく、ステータスがエラーを示している場合、接続の現在のエラーメッセージが 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 の文字列リテラルを括らなければならない単一引用符は、結果文字列には含まれません。
PQunescapeBytea エスケープされたバイナリデータの文字列表現を、バイナリデータに変換します。 PQescapeBytea の反対。
unsigned char *PQunescapeBytea(unsigned char *from, size_t *to_length);
from パラメータは、BYTEA 列の PQgetvalue で返されるようなエスケープ文字列をポイントしています。PQunescapeBytea は、この文字列表現をバイナリ表現に変換しながら、用意されたバッファに格納していきます。また、エラーで NULL になってるバッファにポインタを返し、そのバッファのサイズを to_length に返します。このポインタは、のちに関数 free(3) の引数として使用することができます。
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(PGresult *res);
PQcmdTuples SQL コマンドによって影響を受けた行数を返します。
char * PQcmdTuples(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 となります)。コマンドが INSERT でない場合は、空文字列を返します。
char * PQoidStatus(const PGresult *res);
この関数は PQoidValue によって置き換えられました。 これはスレッドセーフではありません。