Go to the first, previous, next, last section, table of contents.

20 MySQL クライアントツールと API

20.1 MySQL C API

C API コードは MySQL とともに配布されます。これは libmysqlclient ライブラリに含まれ、C プログラムからデータベースへのアクセスを許します。

MySQL ソースディストリビューション内のクライアントの多くは C で書かれています。C API の使用法を示す例を探すなら、これらのクライアントを調べてください。

他のクライアント API の多く(Java を除く全て)は、MySQL サーバとの通信にこのライブラリを使用します。そのため、例えば、他のクライアントプログラムで使用されるのと同じ環境変数の多くの利点を得ることができます。それらはライブラリから参照されるからです。これらの変数のリストについては「12.1 様々な MySQL プログラムの概要」節を参照して下さい。

クライアントは最大通信バッファサイズを持ちます。最初に割り当てられるバッファのサイズ(16K バイト)は自動的に最大サイズ(デフォルトは 24M)まで増加します。バッファサイズは必要に応じて増加するため、単純にデフォルトの最大制限を増加しても、さらに内部で資源を使用することはありません。このサイズチェックは主に間違ったクエリと通信パケットのためのチェックです。

通信バッファは一つの SQL ステートメント(クライアントからサーバへの通信)と、返されるデータ(サーバからクライアントへの通信)の１レコードを含むのに十分大きくなくてはいけません。各スレッドの通信バッファは、任意のレコードやクエリを処理するために、指定された制限まで動的に増大します。例えば、最大 16M のデータを含む BLOB 値がある場合、少なくとも 16M を通信バッファ制限として持つ必要があります(サーバとクライアントの両方で)。クライアントのデフォルトの最大値は 24M ですが、サーバの最大値のデフォルトは 1M です。これはサーバ起動時に、max_allowed_packet パラメータの値を変更することにより、増やすことが出来ます。「10.2.3 サーバーパラメーターのチューニング」節参照.

MySQL サーバは、各クエリ後に各通信バッファを net_buffer_length バイトに縮小します。クライアントでは、接続に割り当てられたバッファのサイズは、接続が閉じられるまで減少しません。クライアントメモリは接続がクローズされた時に調整されます。

スレッドプログラミングを行なう場合は、MySQL C API を --with-thread-safe-client 付きでコンパイルすべきです。これは C API を接続毎のスレッド安全にします。次の場合に限り、２つのスレッドは同じ接続を共有できます:

: ２つのスレッドが同じ接続上で同時に MySQL にクエリを送信することはできません。特に mysql_query() と mysql_store_result() の間で、他のスレッドが同じ接続を使用しないことを確実にする必要があります。
: 多くのスレッドが mysql_store_result() で取り出された別々の結果セットにアクセスできます。
: mysql_use_result を使用する場合、結果セットがクローズされるまで、他のスレッドが同じ接続上で何も尋ねないことを確実にする必要があります。

20.2 C API データ型

MYSQL

この構造体は一つのデータベース接続のハンドルを表わします。これはほとんど全ての MySQL 関数に使用されます。

MYSQL_RES

この構造体はレコードを返すクエリ(SELECT, SHOW, DESCRIBE, EXPLAIN)の結果を表わします。クエリから返される情報は、この節の残りでは結果セットと呼ばれます。

MYSQL_ROW

これはデータの１レコードの安全な型表現です。これは現在バイト文字列の配列として実装されています。(フィールド値がバイナリデータを含むことがある場合、これを NULL 終端文字列として扱うことはできません。そのような値は内部に NULL バイトを含むことがあるからです。) mysql_fetch_row() の呼び出しによりレコードが獲得されます。

MYSQL_FIELD

この構造体はフィールドについての情報、つまりフィールドの名前、型、サイズ等を含んでいます。このメンバは後でさらに詳細に説明されています。 mysql_fetch_field() を繰り返し呼び出すことにより、各フィールドの MYSQL_FIELD 構造体を得ることができます。フィールド値はこの構造体の一部ではありません; それは MYSQL_ROW 構造体に含まれています。

MYSQL_FIELD_OFFSET

これは、MySQL フィールドリストへのオフセットの安全な型表現です。 (mysql_field_seek() で使用されます。)オフセットはレコード内のフィールド番号で、0 から始まります。

my_ulonglong

レコード数と mysql_affected_rows(), mysql_num_rows() そして mysql_insert_id() に使用される型です。この型は 0 から 1.84e19 の範囲を与えます。システムによっては、my_ulonglong 型の値を表示しようとしても、動作しないことがあります。この値を表示するには、unsigned long に変換し、%lu 出力書式を使用してください。例:

printf (Number of rows: %lu\n", (unsigned long) mysql_num_rows(result));

MYSQL_FIELD 構造体は次のメンバを含みます:

char * name

フィールドの名前。null終端文字列。

char * table

このフィールドを含むテーブルの名前。計算されたフィールドでない場合のみ有効です。計算されたフィールドでは、table 値は空文字列です。

char * def

このフィールドのデフォルト値。null終端文字列。これは mysql_list_fields() 使用時にだけ設定されます。

enum enum_field_types type

フィールドの型。 type 値は次の一つです:

型の値	型の意味
`FIELD_TYPE_TINY`	`TINYINT` フィールド
`FIELD_TYPE_SHORT`	`SMALLINT` フィールド
`FIELD_TYPE_LONG`	`INTEGER` フィールド
`FIELD_TYPE_INT24`	`MEDIUMINT` フィールド
`FIELD_TYPE_LONGLONG`	`BIGINT` フィールド
`FIELD_TYPE_DECIMAL`	`DECIMAL` または `NUMERIC` フィールド
`FIELD_TYPE_FLOAT`	`FLOAT` フィールド
`FIELD_TYPE_DOUBLE`	`DOUBLE` または `REAL` フィールド
`FIELD_TYPE_TIMESTAMP`	`TIMESTAMP` フィールド
`FIELD_TYPE_DATE`	`DATE` フィールド
`FIELD_TYPE_TIME`	`TIME` フィールド
`FIELD_TYPE_DATETIME`	`DATETIME` フィールド
`FIELD_TYPE_YEAR`	`YEAR` フィールド
`FIELD_TYPE_STRING`	文字列 (`CHAR` または `VARCHAR`) フィールド
`FIELD_TYPE_BLOB`	`BLOB` または `TEXT` フィールド (最大長を確定するには `max_length` を使用して下さい)
`FIELD_TYPE_SET`	`SET` フィールド
`FIELD_TYPE_ENUM`	`ENUM` フィールド
`FIELD_TYPE_NULL`	`NULL`型フィールド
`FIELD_TYPE_CHAR`	非推奨; `FIELD_TYPE_TINY` を代わりに使用してください

IS_NUM() マクロで、フィールドが数値タイプかどうかをテストできます。フィールドが数値の場合、type メンバを IS_NUM() に渡すと TRUE と評価します:

if (IS_NUM(field->type))
    printf("Field is numeric\n");

unsigned int length

フィールドの幅。これはテーブル定義で指定されたものです。

unsigned int max_length

結果セットのフィールドの最大幅(実際の結果セットの中のレコードの最長フィールド値の長さ)。mysql_store_result() または mysql_list_fields() を使用する場合は、これはフィールドの最大幅になります。 mysql_use_result() を使用する場合は、この変数の値は 0 になります。

unsigned int flags

フィールドの種々のビットフラグ。flags 値は 0 または次のビットの一つ以上の組み合わせです:

フラグの値	フラグの意味
`NOT_NULL_FLAG`	フィールドは `NULL` にできない
`PRI_KEY_FLAG`	フィールドはプライマリキーの一部である
`UNIQUE_KEY_FLAG`	フィールドはユニークキーの一部である
`MULTIPLE_KEY_FLAG`	フィールドは非ユニークキーの一部である
`UNSIGNED_FLAG`	フィールドは `UNSIGNED` 属性を持っている
`ZEROFILL_FLAG`	フィールドは `ZEROFILL` 属性を持っている
`BINARY_FLAG`	フィールドは `BINARY` 属性を持っている
`AUTO_INCREMENT_FLAG`	フィールドは `AUTO_INCREMENT` 属性を持っている
`ENUM_FLAG`	フィールドは `ENUM` である (非推奨)
`BLOB_FLAG`	フィールドは `BLOB` または `TEXT` である (非推奨)
`TIMESTAMP_FLAG`	フィールドは `TIMESTAMP` である (非推奨)

BLOB_FLAG, ENUM_FLAG, TIMESTAMP_FLAG の使用は推奨されません。これらは型の属性ではなくフィールドの型を示すからです。代わりに field->type を FIELD_TYPE_BLOB, FIELD_TYPE_ENUM, FIELD_TYPE_TIMESTAMP に対してテストする方をお勧めします。次の例は flags 値の典型的な使用を示しています:

if (field->flags & NOT_NULL_FLAG)
    printf("Field can't be null\n");

flags 値の真偽状態を調べるために、次の便利なマクロを使用できます:

`IS_NOT_NULL(flags)`	このフィールドが `NOT NULL` として定義されていれば真
`IS_PRI_KEY(flags)`	このフィールドがプライマリキーならば真
`IS_BLOB(flags)`	このフィールドが `BLOB` または `TEXT` ならば真 (非推奨; 代わりに `field->type` をテストして下さい)

unsigned int decimals

数値フィールドの小数部桁数。

20.3 C API 関数概要

C API には次に一覧された関数が存在します。これらの関数は次の節でかなり詳細に説明されています。「20.4 C API 関数説明」節参照。

mysql_affected_rows()	最後の `UPDATE`, `DELETE`, `INSERT` クエリによって影響されたレコード数を返します。
mysql_close()	サーバ接続をクローズします。
mysql_connect()	MySQL サーバに接続します。この関数は推奨されません; 代わりに `mysql_real_connect()` を使用してください。
mysql_change_user()	接続中ののユーザとデータベースを変更します。
mysql_create_db()	データベースを生成します。この関数は推奨されません; 代わりに SQL コマンド `CREATE DATABASE` を使用してください。
mysql_data_seek()	クエリ結果セット中の任意のレコードにシークします。
mysql_debug()	与えられた文字列で `DBUG_PUSH` を行ないます。
mysql_drop_db()	データベースを破棄します。この関数は推奨されません; 代わりに SQL コマンド `DROP DATABASE` を使用してください。
mysql_dump_debug_info()	サーバに、デバッグ情報をログに書き出させます。
mysql_eof()	結果セットの最後のレコードが読まれたかどうかを判定します。この関数は推奨されません; 代わりに `mysql_errno()` または `mysql_error()` を使用して下さい。
mysql_errno()	最後の MySQL 関数からのエラー番号を返します。
mysql_error()	最後の MySQL 関数からのエラーメッセージを返します。
mysql_escape_string()	SQL ステートメント内で使用するために文字列中の特殊文字をエスケープします。
mysql_fetch_field()	テーブルの次のフィールドの型を返します。
mysql_fetch_field_direct()	テーブルの、番号で指定されたフィールドの型を返します。
mysql_fetch_fields()	全てのフィールド構造体の配列を返します。
mysql_fetch_lengths()	現在のレコード中の全てのフィールドの長さを返します。
mysql_fetch_row()	結果セットから次のレコードを取り出します。
mysql_field_seek()	指定されたフィールド上にフィールドカーソルを置きます。
mysql_field_count()	最後のクエリの結果のフィールドの数を返します。
mysql_field_tell()	最後の `mysql_fetch_field()` で使用されたフィールドカーソルの位置を返します。
mysql_free_result()	結果セットによって使用されたメモリを解放します。
mysql_get_client_info()	クライアントバージョン情報を返します。
mysql_get_host_info()	接続を説明する文字列を返します。
mysql_get_proto_info()	接続に使用されるプロトコルバージョンを返します。
mysql_get_server_info()	サーバのバージョン番号を返します。
mysql_info()	最後に実行されたクエリについての情報を返します。
mysql_init()	`MYSQL` 構造体を獲得または初期化します。
mysql_insert_id()	`AUTO_INCREMENT` フィールドに最後に生成された ID を返します。
mysql_kill()	指定されたスレッドを殺します。
mysql_list_dbs()	簡易正規表現に適合するデータベース名を返します。
mysql_list_fields()	簡易正規表現に適合するフィールド名を返します。
mysql_list_processes()	現在のサーバスレッドのリストを返します。
mysql_list_tables()	簡易正規表現に適合するテーブル名を返します。
mysql_num_fields()	結果セット中のフィールド数を返します。
mysql_num_rows()	結果セット中のレコード数を返します。
mysql_options()	`mysql_connect()` のための接続オプションを設定します。
mysql_ping()	サーバへの接続が動作しているかどうかをチェックします。必要であれば再接続します。
mysql_query()	NULL 終端文字列として記述された SQL クエリを実行します。
mysql_real_connect()	MySQL サーバに接続します。
mysql_real_query()	数えられた文字列として記述された SQL クエリを実行します。
mysql_reload()	権限テーブルを再読み込みするようにサーバに指示します。
mysql_row_seek()	結果セット内のあるレコードへシークします。`mysql_row_tell()` から返される値を使用します。
mysql_row_tell()	レコードカーソルの位置を返します。
mysql_select_db()	データベースに接続します。
mysql_shutdown()	データベースサーバをシャットダウンします。
mysql_stat()	文字列でサーバ状態を返します。
mysql_store_result()	クライアントに完全な結果セットを取り出します。
mysql_thread_id()	現在のスレッド ID を返します。
mysql_use_result()	各レコードの動的結果セットを初期化します。

サーバへ接続するには、接続ハンドラを初期化するために mysql_init() を呼びだし、それから mysql_real_connect() をそのハンドラで呼びだします (ホスト名、ユーザ名、パスワードのような他の情報に加えて)。その接続での処理が終了した時は、接続を終了させるために mysql_close() を呼びだします。

接続が有効な間は、クライアントは mysql_query() または mysql_real_query() を使用して SQL クエリをサーバに送信できます。この２つの違いは、mysql_query() は NULL終端文字列としてクエリが記述されることを期待するのに対し、mysql_real_query() は数えられた文字列を期待することです。文字列がバイナリデータ(NULバイトを含みことがある)を含む場合は、mysql_real_query() を使用する必要があります。

非SELECT クエリ(例えば、INSERT, UPDATE, DELETE)では、どれくらいのレコードが影響(変更)されたかを mysql_affected_rows() を呼び出すことで見つけ出すことができます。

SELECT クエリでは、選択されたレコードを結果セットとして取り出します。 (注意: いくつかのステートメントは、レコードを返すという点で SELECTに似ています。それは SHOW, DESCRIBE, EXPLAIN です。これらは SELECT ステートメントと同じ方法で扱われるべきです。)

クライアントが結果セットを処理するには２つの方法があります。一つ目は、 mysql_store_result() を呼び出すことで、結果セット全体を一度にすべて取り出すことです。この関数はサーバからクエリによって返されるすべてのレコードを取得し、それをクライアントに格納します。二つ目は、 mysql_use_result() を呼び出すことで、レコードごとの結果セット取り出しを初期化することです。この関数は取り出しを初期化しますが、実際にはサーバから何のレコードも得ません。

どちらの場合でも、mysql_fetch_row() を呼び出してレコードにアクセスします。mysql_store_result() では、mysql_fetch_row() は既にサーバから取得してあるレコードにアクセスします。 mysql_use_result() では、mysql_fetch_row() は実際にサーバからレコードを取り出します。各レコードのデータ値のサイズについての情報は mysql_fetch_lengths() を呼び出すことで得られます。

結果セットでの処理が終った後は、mysql_free_result() を呼び出し、それが使用していたメモリを解放して下さい。

この２つの取り出し機構は相補的なものです。クライアントプログラムは、必要によってもっとも適切なアプローチを選択すべきです。慣例的に、クライアントは一般に mysql_store_result() を使用する傾向にあります。

mysql_store_result() の利点は、すべてのレコードをクライアントに取って来るため、連続してレコードをアクセスできるだけでなく、結果セット中の現在のレコード位置を変更するために、mysql_data_seek() や mysql_row_seek() を使用して、結果セットの中を後や前に移動することができます。また、mysql_num_rows() を呼び出すことで、レコード数を見つけることもできます。一方、mysql_store_result() の必要メモリは、大きな結果セットではとても高く、out-of-memory 状態に遭遇する可能性が高くなります。

mysql_use_result() の利点は、一度に一つのレコードだけを保持するため、クライアントが結果セットに要求するメモリが少ないことです（そして、割当のオーバーヘッドも少ないので、mysql_use_result() はより速くなります）。不利な点は、サーバの拘束を避けるため、各レコードを素早く処理する必要があること、結果セット中でレコードのランダムアクセスができないこと（レコードを順番にアクセスすることしかできません）、そして、すべてのレコードを取り出さない限り、結果セット中にいくつのレコードがあるかを知ることができないことです。さらに、あなたが探している情報を、検索の途中で見つけることができて、問題が解決したとしても、すべてのレコードを取り出さなければなりません。

API はクライアントがクエリが SELECT であるかどうかを知ることなしに、（必要時だけレコードを取り出す）クエリに適切に応答できるようにします。それぞれの mysql_query()（または mysql_real_query()）の後で、 mysql_store_result() を呼び出すことで、これが可能です。結果セットの呼び出しが成功すると、クエリは SELECT であり、レコードを読むことができます。結果セット呼び出しが失敗した場合は、結果が実際に期待されたものであるかどうかを確定するために、mysql_field_count() を呼び出してください。mysql_field_count() が 0 を返す場合は、クエリはデータを返しません（クエリが INSERT, UPDATE, DELETE 等であることを示します）。つまりレコードが返ることを期待できません。 mysql_field_count() が 0 でない場合は、クエリはレコードを返すべきなのに、返さなかったということです。これはクエリが SELECT で失敗したということを示します。これをどのように行なうことができるかの例は、 mysql_field_count() の説明を参照してください。

mysql_store_result() と mysql_use_result() はどちらも、結果セットを作るフィールドについての情報（フィールドの数、その名前や型など）を獲得することができます。mysql_fetch_field() を繰り返し呼び出すことで順番に、または、mysql_fetch_field_direct() を呼び出すことでレコード内のフィールド番号で、レコード内のフィールド情報にアクセスすることができます。現在のフィールドカーソル位置は mysql_field_seek() を呼び出すことで変更できます。フィールドカーソルの設定は、その後の mysql_fetch_field() 呼び出しに影響します。 mysql_fetch_fields() を呼び出すことで、一度にすべてのフィールドの情報を得ることもできます。

エラーの検出、報告については、mysql_errno() と mysql_error() 関数の方法によって、MySQL はエラー情報へのアクセスを提供します。これらは、最後に呼び出された成功または失敗し得る関数についてのエラーコードとエラーメッセージを返し、エラーがいつ何で発生したかを確定することができます。

20.4 C API 関数説明

以下の説明では、NULL の引数または戻り値は C プログラミング言語での NULL を意味します。MySQL NULL 値ではありません。関数は通常ポインタか整数の値を返します。しかし関数説明に記述がある場合、ポインタを返す関数は、成功を示すために非 NULL 値を返し、エラーを示すために NULL を返します。整数を返す関数は、成功を示すために 0 を返し、エラーを示すために非0を返します。``非0'' は関数説明が他に述べていない限り、その意味になることに注意してください; 関数説明が他に述べている場合、これらに対して 0 以外の固有の値をテストしないでください:

if (result)                   /* 正しい */
    ... error ...

if (result < 0)               /* 間違い */
    ... error ...

if (result == -1)             /* 間違い */
    ... error ...

関数がエラーを返すとき、関数説明の エラー 節が起り得るエラーの種類を一覧しています。mysql_errno() の呼び出しによってどれが発生したかを見つけ出すことができます。エラーを表現する文字列は mysql_error() の呼び出しによって得られます。

20.4.1 `mysql_affected_rows()`

my_ulonglong mysql_affected_rows(MYSQL *mysql)

20.4.1.1 説明

最後の UPDATE, DELETE, INSERT クエリによって影響された(変更された)行数を返します。UPDATE, DELETE, INSERT ステートメントでの mysql_query() 直後に呼び出します。SELECT ステートメントでは、これは mysql_num_rows() に似た動きをします。

mysql_affected_rows() は現在マクロとして実装されています。

20.4.1.2 戻り値

0 より大きい整数は影響された行数または取り出された行数を示します。クエリの WHERE 節に適合したレコードがない場合またはクエリがまだ実行されていない場合は 0 です。クエリがエラーを返したか、SELECT クエリについて mysql_store_result() が呼ばれる前に mysql_affected_rows() が呼ばれた場合は -1 です。

20.4.1.3 エラー

無し。

20.4.1.4 例

mysql_query(&mysql,"UPDATE products SET cost=cost*1.25 WHERE group=10");
printf("%d products updated",mysql_affected_rows(&mysql));

20.4.2 `mysql_close()`

void mysql_close(MYSQL *mysql)

20.4.2.1 説明

前にオープンされた接続をクローズします。ハンドルが mysql_init() または mysql_connect() で自動的に割り当てられた場合、 mysql_close() は mysql で示される接続ハンドルの解放も行ないます。

20.4.2.2 戻り値

無し。

20.4.2.3 エラー

CR_COMMANDS_OUT_OF_SYNC: 不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR: MySQL サーバがいなくなった。
CR_SERVER_LOST: サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR: 未知のエラーが発生した。

20.4.3 `mysql_connect()`

MYSQL *mysql_connect(MYSQL *mysql, const char *host, const char *user, const char *passwd)

20.4.3.1 説明

この関数は推奨されません。代わりに mysql_real_connect() の使用をお勧めします。

mysql_connect() は host 上で動作している MySQL データベースエンジンへの接続の確立を試みます。mysql_get_client_info() を除く他のすべての API 関数を実行する前にmysql_connect() が成功終了している必要があります。

パラメータの意味は mysql_connect() の対応するパラメータと同じですが、接続パラメータは NULL にできることが異なります。この場合 C API は接続構造体に自動的にメモリを割り当て、mysql_close() 呼び出し時にそれを解放します。このアプローチの不利な点は接続が失敗した場合にエラーメッセージを取り出すことができないことです。（mysql_errno() または mysql_error() からエラー情報を得るには、正しい MYSQL ポインタを提供する必要があります。）

20.4.3.2 戻り値

mysql_real_connect() と同じ

20.4.3.3 エラー

mysql_real_connect() と同じ

20.4.4 `mysql_change_user()`

my_bool mysql_change_user(MYSQL *mysql, const char *user, const char *password, const char *db)

20.4.4.1 説明

ユーザを変更し、mysql で示された接続上で、db で示されたデータベースがデフォルト（現在の）データベースになります。その後のクエリでは、明示的なデータベースの指定を含んでいないテーブル参照について、このデータベースがデフォルトになります。

この関数は MySQL 3.23.3 で導入されました。

mysql_change_user() は接続されたユーザが認証されない場合、またはデータベースを使用する権限を持っていない場合に失敗します。この場合、ユーザとデータベースは変更されません。

デフォルトデータベースを持ちたくない場合、db パラメータを NULL に設定できます。

20.4.4.2 戻り値

成功時 0。エラーが発生した場合は非0。

20.4.4.3 エラー

mysql_real_connect() から得られるものと同じです。

CR_COMMANDS_OUT_OF_SYNC: 不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR: MySQL サーバがいなくなった。
CR_SERVER_LOST: サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR: 未知のエラーが発生した。
ER_UNKNOWN_COM_ERROR: MySQL サーバはこのコマンドを実装していない（おそらく古いサーバ）。
ER_ACCESS_DENIED_ERROR: ユーザまたはパスワードが間違っている。
ER_BAD_DB_ERROR: データベースが存在しない。
ER_DBACCESS_DENIED_ERROR: ユーザがデータベースへのアクセス権を持っていない。
ER_WRONG_DB_NAME: データベース名が長過ぎる。

20.4.4.4 例

if (mysql_change_user(&mysql, "user", "password", "new_database"))
{
   fprintf(stderr, "Failed to change user.  Error: %s\n",
           mysql_error(&mysql));
}

20.4.5 `mysql_create_db()`

int mysql_create_db(MYSQL *mysql, const char *db)

20.4.5.1 説明

db 引数によって指定されたデータベースを作成します。

この関数は推奨されません。代わりに mysql_query() を使って、SQL CREATE DATABASE ステートメントを発行することをお勧めします。

20.4.5.2 戻り値

データベースの作成が成功した場合は0。エラーが発生した場合は非0。

20.4.5.3 エラー

CR_COMMANDS_OUT_OF_SYNC: 不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR: MySQL サーバがいなくなった。
CR_SERVER_LOST: サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR: 未知のエラーが発生した。

20.4.5.4 例

if(mysql_create_db(&mysql, "my_database"))
{
   fprintf(stderr, "Failed to create new database.  Error: %s\n",
           mysql_error(&mysql));
}

20.4.6 `mysql_data_seek()`

void mysql_data_seek(MYSQL_RES *result, unsigned int offset)

20.4.6.1 説明

クエリ結果セット中の任意のレコードにシークします。これは、結果セット構造体がクエリのすべての結果を持っていることを要求します。そのため、 mysql_data_seek() は mysql_store_result() と共にだけ使用され、 mysql_use_result() と共には使用できません。

オフセットの値は 0 から mysql_num_rows(result)-1 でなくてはなりません。

20.4.6.2 戻り値

無し。

20.4.6.3 エラー

無し。

20.4.7 `mysql_debug()`

void mysql_debug(char *debug)

20.4.7.1 説明

与えられた文字列で DBUG_PUSH を行ないます。mysql_debug() はFred Fish debug library を使用します。この関数を使用するためには、デバッグをサポートするように、クライアントライブラリをコンパイルする必要があります。「G.1 MySQL server のデバッグ」節参照. 「G.2 Debugging a MySQL client」節参照.

20.4.7.2 戻り値

無し。

20.4.7.3 エラー

無し。

20.4.7.4 例

次に示した呼び出しは、クライアントライブラリが、クライアントマシン上の `/tmp/client.trace' にトレースファイルを生成します:

mysql_debug("d:t:O,/tmp/client.trace");

20.4.8 `mysql_drop_db()`

int mysql_drop_db(MYSQL *mysql, const char *db)

20.4.8.1 説明

db 引数によって指定されたデータベースを破棄します。

この関数は推奨されません。代わりに mysql_query() を使って、SQL DROP DATABASE ステートメントを発行することをお勧めします。

20.4.8.2 戻り値

データベースの破棄が成功した場合は0。エラーが発生した場合は非0。

20.4.8.3 エラー

CR_COMMANDS_OUT_OF_SYNC: 不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR: MySQL サーバがいなくなった。
CR_SERVER_LOST: サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR: 未知のエラーが発生した。

20.4.8.4 例

if(mysql_drop_db(&mysql, "my_database"))
  fprintf(stderr, "Failed to drop the database: Error: %s\n",
          mysql_error(&mysql));

20.4.9 `mysql_dump_debug_info()`

int mysql_dump_debug_info(MYSQL *mysql)

20.4.9.1 説明

いくつかのデバッグ情報をログにダンプするようにサーバに指示します。この動作をするためには、接続されたユーザが process 権を持っていなければなりません。

20.4.9.2 戻り値

コマンドが成功した場合は0。コマンドが失敗した場合は非0。

20.4.9.3 エラー

CR_COMMANDS_OUT_OF_SYNC: 不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR: MySQL サーバがいなくなった。
CR_SERVER_LOST: サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR: 未知のエラーが発生した。

20.4.10 `mysql_eof()`

my_bool mysql_eof(MYSQL_RES *result)

20.4.10.1 説明

この関数は推奨されません。mysql_errno() か mysql_error() が代わりに使用できます。

mysql_eof() は結果セットの最後のレコードが読まれたかどうかを調べます。

mysql_store_result() の呼び出しが成功して、結果セットを入手した場合、クライアントは一つのオペレーションですべてのセットを受け取ります。この場合、 mysql_fetch_row() から返される NULL は、常に結果セットの終端に達したことを意味し、mysql_eof() を呼ぶ必要はありません。

一方、結果セット取り出しの初期化のために mysql_use_result() を使用する場合、セットのレコードは mysql_fetch_row() を繰り返し呼ぶことにより、ひとつずつサーバから獲得されます。この処理中に接続上でエラーが発生し得るため、mysql_fetch_row() からの戻り値 NULL は、通常必ずしも結果セットの終端に達したことを意味しません。この場合 mysql_eof() を使用して、何が起こったかを検出できます。結果セットの終端に達した場合は mysql_eof() は非0値を返し、エラーが発生した場合は 0 を返します。

歴史的に mysql_eof() は標準 MySQL エラー関数 mysql_errno() と mysql_error() 以前に遡ります。これらのエラー関数は同じ情報を提供するので、これらの使用が mysql_eof() よりも好まれます。mysql_eof() は現在推奨されません。（実際、これらは多くの情報を提供します。エラー関数はエラーが発生した時のエラーの理由を示しますが、 mysql_eof() は真偽値だけを返します。）

20.4.10.2 戻り値

エラーが発生した場合は0。結果セットの終端に達した場合は非0。

20.4.10.3 エラー

無し。

20.4.10.4 例

次の例は mysql_eof の使用方法を示します:

mysql_query(&mysql,"SELECT * FROM some_table");
result = mysql_use_result(&mysql);
while((row = mysql_fetch_row(result)))
{
    // do something with data
}
if(!mysql_eof(result))  // mysql_fetch_row() failed due to an error
{
    fprintf(stderr, "Error: %s\n", mysql_error(&mysql));
}

しかし、標準 MySQL エラー関数で同じ効果を得ることができます:

mysql_query(&mysql,"SELECT * FROM some_table");
result = mysql_use_result(&mysql);
while((row = mysql_fetch_row(result)))
{
    // do something with data
}
if(mysql_errno(&mysql))  // mysql_fetch_row() failed due to an error
{
    fprintf(stderr, "Error: %s\n", mysql_error(&mysql));
}

20.4.11 `mysql_errno()`

unsigned int mysql_errno(MYSQL *mysql)

20.4.11.1 説明

mysql によって指定された接続上で、最後に呼び出された API 関数の成否のエラーコードを返します。戻り値0はエラーが発生しなかったことを意味します。クライアントエラーメッセージ番号は `errmsg.h' にリストされています。サーバエラーメッセージ番号は `mysqld_error.h' にリストされています。

20.4.11.2 戻り値:

エラーコード値。エラーが発生していない場合は0。

20.4.11.3 エラー

無し。

20.4.12 `mysql_error()`

char *mysql_error(MYSQL *mysql)

20.4.12.1 説明

mysql によって指定された接続上で、 mysql_error() は最後に呼び出された API 関数の成否を、エラーメッセージとして返します。エラー発生しなかった場合は空文字列 ("") が返されます。これは次の２つのテストが同じであることを意味します:

if(mysql_errno(&mysql))
{
    // an error occurred
}

if(mysql_error(&mysql)[0] != '\0')
{
    // an error occurred
}

クライアントエラーメッセージの言語は MySQL クライアントライブラリの再コンパイルで変更できます。現在はいくつかの言語で書かれたクライアントエラーメッセージを選択できます。「9.1 MySQL がサポートしている言語は？」節参照.

20.4.12.2 戻り値

エラーを表わす文字列。エラーが発生していない場合は空文字列。

20.4.12.3 エラー

無し。

20.4.13 `mysql_escape_string()`

unsigned int mysql_escape_string(char *to, const char *from, unsigned int length)

20.4.13.1 説明

from の文字列を、SQL ステートメントでサーバに送ることができるようにエスケープされた SQL 文字列に変換します。結果は to に入り、終端 null 文字を追加します。変換される文字列は `NUL' (ASCII 0), `\n', `\r', `\', `'', `"', Control-Z です。( 「7.1 リテラル:文字列と数値をどのように書くか？」節参照).

from で示される文字列はlength バイト長でなければなりません。 to バッファには少なくとも length*2+1 バイト長を割り当てる必要があります。（最悪の場合、それぞれの文字が２バイトに変換されることがあり、さらに終端 null バイトのための場所が必要です。） mysql_escape_string() が復帰するとき、to の内容は NUL 終端文字列になります。戻り値は変換された文字列の長さです。終端 null 文字は含みません。

20.4.13.2 例

char query[1000],*end;

end = strmov(query,"INSERT INTO test_table values(");
*end++ = '\'';
end += mysql_escape_string(end,"What's this",11);
*end++ = '\'';
*end++ = ',';
*end++ = '\'';
end += mysql_escape_string(end,"binary data: \0\r\n",16);
*end++ = '\'';
*end++ = ')';

if (mysql_real_query(&mysql,query,(unsigned int) (end - query)))
{
   fprintf(stderr, "Failed to insert row, Error: %s\n",
           mysql_error(&mysql));
}

上記の strmov() 関数は mysqlclient ライブラリに含まれていて、strcpy() のように働きますが、最初の引数の終りの null へのポインタを返します。

20.4.13.3 戻り値

to へ置かれた値の長さ。終端 null 文字は含みません。

20.4.13.4 エラー

無し。

20.4.14 `mysql_fetch_field()`

MYSQL_FIELD *mysql_fetch_field(MYSQL_RES *result)

20.4.14.1 説明

結果セットの一つのフィールドの定義を MYSQL_FIELD 構造体として返します。結果セット内の全てのフィールドについて情報を取り出すには、この関数を繰り返し呼んでください。mysql_fetch_field() はフィールドが残っていないと NULL を返します。

mysql_fetch_field() は、新しい SELECT クエリを実行するたびに、最初のフィールドについての情報を返すようにリセットされます。 mysql_fetch_field() で返されるフィールドは mysql_field_seek() の呼び出しにも影響をうけます。

テーブルを SELECT するために mysql_query() を呼び、しかしまだ mysql_store_result() を呼んでいない場合、 mysql_fetch_field() を BLOB フィールドの長さの問い合わせに使用すると、MySQL はデフォルトの blob 長 (8K bytes) を返します。 (8K サイズになるのは、MySQL は BLOB の最大長を知らないからです。これはいつかコンフィグ可能になるべきです。) 一度結果セットを取り出せば、field->max_length は指定したクエリ内でのこのフィールドの最大値の長さを含みます。

20.4.14.2 戻り値

現在のフィールドの MYSQL_FIELD 構造体。フィールドが残っていない場合は NULL。

20.4.14.3 エラー

無し。

20.4.14.4 例

MYSQL_FIELD *field;

while((field = mysql_fetch_field(result)))
{
    printf("field name %s\n", field->name);
}

20.4.15 `mysql_fetch_fields()`

MYSQL_FIELD *mysql_fetch_fields(MYSQL_RES *result)

20.4.15.1 説明

結果セットのすべての MYSQL_FIELD 構造体の配列を返します。各構造体は結果セットの一つのフィールドのフィールド定義を提供します。

20.4.15.2 戻り値

結果セットの全ての項目の MYSQL_FIELD 構造体の配列。

20.4.15.3 エラー

無し。

20.4.15.4 例

unsigned int num_fields;
unsigned int i;
MYSQL_FIELD *fields;

num_fields = mysql_num_fields(result);
fields = mysql_fetch_fields(result);
for(i = 0; i < num_fields; i++)
{
   printf("Field %u is %s\n", i, fields[i].name);
}

20.4.16 `mysql_fetch_field_direct()`

MYSQL_FIELD *mysql_fetch_field_direct(MYSQL_RES *result, unsigned int fieldnr)

20.4.16.1 説明

結果セット中のフィールドを示すフィールド番号 fieldnr が与えられ、そのフィールドのフィールド定義を MYSQL_FIELD 構造体として返します。この関数は任意のフィールドについての定義を取り出すことに使用できます。 fieldnr の値は 0 から mysql_num_fields(result)-1 の範囲にすべきです。

20.4.16.2 戻り値

指定されたフィールドの MYSQL_FIELD 構造体。

20.4.16.3 エラー

無し。

20.4.16.4 例

unsigned int num_fields;
unsigned int i;
MYSQL_FIELD *field;

num_fields = mysql_num_fields(result);
for(i = 0; i < num_fields; i++)
{
    field = mysql_fetch_field_direct(result, i);
    printf("Field %u is %s\n", i, field->name);
}

20.4.17 `mysql_fetch_lengths()`

unsigned long *mysql_fetch_lengths(MYSQL_RES *result)

20.4.17.1 説明

結果セット中の現在のレコードのフィールドの長さを返します。フィールドの値をコピーする場合、この長さ情報は最適化にも有用です。strlen() の呼び出しを回避できるためです。さらに、結果セットがバイナリデータを持つ場合は、データのサイズを特定するためにこの関数を使わなければなりません。なぜなら strlen() は NULL 文字を含むフィールドについての結果を正しく返さないからです。

空フィールドの長さと NULL 値を含むフィールドの長さは 0 です。この２つのケースを区別する方法については、mysql_fetch_row() の説明を参照して下さい。

20.4.17.2 戻り値

各フィールドのサイズ (終端 NUL 文字は含みません)を提供する unsigned long 整数の配列。エラーが発生した場合は NULL。

20.4.17.3 エラー

mysql_fetch_lengths() は結果セットの現在のレコードについてだけ有効です。mysql_fetch_row() を呼び出す前、または結果の全てのレコードを取り出した後にこれを呼んだ場合、NULL が返されます。

20.4.17.4 例

MYSQL_ROW row;
unsigned long *lengths;
unsigned int num_fields;
unsigned int i;

row = mysql_fetch_row(result);
if (row)
{
    num_fields = mysql_num_fields(result);
    lengths = mysql_fetch_lengths(result);
    for(i = 0; i < num_fields; i++)
    {
         printf("Column %u is %lu bytes in length.\n", i, lengths[i]);
    }
}

20.4.18 `mysql_fetch_row()`

MYSQL_ROW mysql_fetch_row(MYSQL_RES *result)

20.4.18.1 説明

結果セットの次のレコードを取り出します。mysql_store_result() の後に使用すると、これ以上取り出すレコードがない時は、NULL を返します。 mysql_use_result() の後に使用するなら、これ以上取り出すレコードがない場合やエラーが発生した場合に NULL を返します。

レコード内の値の数は mysql_num_fields(result) によって与えられます。 row が mysql_fetch_row() の呼び出しからの戻り値を保持する場合、値へのポインタは row[0] から row[mysql_num_fields(result)-1 としてアクセスされます。レコード内の NULL 値はNULL ポインタによって示されます。

レコードのフィールド値の長さは、mysql_fetch_lengths() の呼び出しで獲得できます。空フィールドと NULL を含むフィールドはどちらも長さ 0 を持ちます; フィールド値のポインタをチェックすることで、これらを区別できます。ポインタが NULL の場合、フィールドは NULL です; そうでなければフィールドは空です。

20.4.18.2 戻り値

次のレコードの MYSQL_ROW 構造体、エラーが発生したか、もう取り出すレコードがない場合は NULL。

20.4.18.3 エラー

CR_SERVER_LOST: サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR: 未知のエラーが発生した。

20.4.18.4 例

MYSQL_ROW row;
unsigned int num_fields;
unsigned int i;

num_fields = mysql_num_fields(result);
while ((row = mysql_fetch_row(result)))
{
   unsigned long *lengths;
   lengths = mysql_fetch_lengths(result);
   for(i = 0; i < num_fields; i++)
   {
       printf("[%.*s] ", (int) lengths[i], row[i] ? row[i] : "NULL");
   }
   printf("\n");
}

20.4.19 `mysql_field_count()`

unsigned int mysql_field_count(MYSQL *mysql)

3.22.24 より前の MySQL バージョンを使用している場合、 unsigned int mysql_num_fields(MYSQL *mysql) を代わりに使用すべきです。

20.4.19.1 説明

接続上の最後のクエリのフィールド数を返します。

この関数は通常 mysql_store_result() が NULL を返した時（そしてこのように結果セットポインタを持っていない時）に使用されます。この場合、 mysql_store_result() が空でない結果を提供すべきかどうかを調べるために、mysql_field_count() を呼び出すことができます。これは、クエリが SELECT（または SELECTに似た）ステートメントであるかを知ること無しに、クライアントプログラムに、適切な行動をとらせることができます。下に示される例は、これをどのように行なうことができるかを説明しています。

「20.4.51 mysql_query() が成功を返した後、mysql_store_result() が NULL を返す時があるのは何故？」節参照.

20.4.19.2 戻り値

結果セット中のフィールド番号を表す unsigned integer。

20.4.19.3 エラー

無し。

20.4.19.4 例

MYSQL_RES *result;
unsigned int num_fields;
unsigned int num_rows;

if (mysql_query(&mysql,query_string))
{
    // error
}
else // query succeeded, process any data returned by it
{
    result = mysql_store_result(&mysql);
    if (result)  // there are rows
    {
        num_fields = mysql_num_fields(result);
        // retrieve rows, then call mysql_free_result(result)
    }
    else  // mysql_store_result() returned nothing; should it have?
    {
        if(mysql_field_count(&mysql) == 0)
        {
            // query does not return data
            // (it was not a SELECT)
            num_rows = mysql_affected_rows(&mysql);
        }
        else // mysql_store_result() should have returned data
        {
            fprintf(stderr, "Error: %s\n", mysql_error(&mysql));
        }
    }
}

別の方法は、mysql_field_count(&mysql) 呼び出しを mysql_errno(&mysql) に置き換えることです。この場合、ステートメントが SELECT かどうかを mysql_field_count() の値から推測するのではなく、直接 mysql_store_result() からのエラーをチェックします。

20.4.20 `mysql_field_seek()`

MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES *result, MYSQL_FIELD_OFFSET offset)

20.4.20.1 説明

与えられたオフセットにフィールドカーソルを設定します。次の mysql_fetch_field() の呼び出しはそのオフセットに対応したフィールドを取り出します。

レコードの最初にシークするには、0 の offset 値を渡してください。

20.4.20.2 戻り値

フィールドカーソルの前の値。

20.4.20.3 エラー

無し。

20.4.21 `mysql_field_tell()`

MYSQL_FIELD_OFFSET mysql_field_tell(MYSQL_RES *result)

20.4.21.1 説明

最後の mysql_fetch_field() に使用したフィールドカーソルの位置を返します。この値は mysql_field_seek() への引数として使用できます。

20.4.21.2 戻り値

フィールドカーソルの現在のオフセット。

20.4.21.3 エラー

無し。

20.4.22 `mysql_free_result()`

void mysql_free_result(MYSQL_RES *result)

20.4.22.1 説明

mysql_store_result(), mysql_use_result(), mysql_list_dbs() 等によって結果セットに割り当てられたメモリを解放します。結果セットで何かを行なった時、mysql_free_result() を呼び出してそれが使用したメモリを解放する必要があります。

20.4.22.2 戻り値

無し。

20.4.22.3 エラー

無し。

20.4.23 `mysql_get_client_info()`

char *mysql_get_client_info(void)

20.4.23.1 説明

クライアントライブラリバージョンを表わす文字列を返します。

20.4.23.2 戻り値

MySQL クライアントライブラリバージョンを表わす文字列。

20.4.23.3 エラー

無し。

20.4.24 `mysql_get_host_info()`

char *mysql_get_host_info(MYSQL *mysql)

20.4.24.1 説明

使用中の接続タイプを表わす文字列を返します。サーバのホスト名を含みます。

20.4.24.2 戻り値

サーバホスト名と接続タイプを表わす文字列。

20.4.24.3 エラー

無し。

20.4.25 `mysql_get_proto_info()`

unsigned int mysql_get_proto_info(MYSQL *mysql)

20.4.25.1 説明

現在の接続に使用されているプロトコルバージョンを返します。

20.4.25.2 Return values

現在の接続に使用されているプロトコルバージョンを表わす符号無し整数値。

20.4.25.3 エラー

無し。

20.4.26 `mysql_get_server_info()`

char *mysql_get_server_info(MYSQL *mysql)

20.4.26.1 説明

サーバのバージョン番号を表わす文字列を返します。

20.4.26.2 戻り値

サーバのバージョン番号を表わす文字列。

20.4.26.3 エラー

無し。

20.4.27 `mysql_info()`

char * mysql_info(MYSQL *mysql)

20.4.27.1 説明

最も最近に実行されたクエリについての情報を文字列で返します。が、以下に挙げる構文に限ります。他の構文ではmysql_info() は NULL を返します。文字列の形式はクエリの型によって様々です。次に説明します (数値は例です; 文字列はクエリに適した値を含みます):

INSERT INTO ... SELECT ...: String format: Records: 100 Duplicates: 0 Warnings: 0
INSERT INTO ... VALUES (...),(...),(...)...: String format: Records: 3 Duplicates: 0 Warnings: 0
LOAD DATA INFILE ...: String format: Records: 1 Deleted: 0 Skipped: 0 Warnings: 0
ALTER TABLE: String format: Records: 3 Duplicates: 0 Warnings: 0
UPDATE: String format: Rows matched: 40 Changed: 40 Warnings: 0

注意: 複数の値リストがステートメント中に記述された場合にだけ、 mysql_info() は、INSERT ... VALUES ステートメントに非 NULL値を返します。

20.4.27.2 戻り値

最も最近に実行されたクエリについての追加情報を表わす文字列。クエリに有効な情報がない場合は NULL ポインタ。

20.4.27.3 エラー

無し。

20.4.28 `mysql_init()`

MYSQL * mysql_init(MYSQL *mysql)

20.4.28.1 説明

mysql_real_connect() に適した MYSQL オブジェクトの割り当てまたは初期化を行ないます。引数が NULL ポインタの場合、関数は新しいオブジェクトを割り当てて初期化し返します。そうでなければオブジェクトは初期化され、オブジェクトのアドレスが返されます。新しいオブジェクトが割り当てられた場合、mysql_close() はこのオブジェクトを解放します。

20.4.28.2 戻り値

初期化された MYSQL* ハンドル、または新しいオブジェクトを割り当てるのに十分なメモリがなかった場合は NULL ポインタ。

20.4.28.3 エラー

メモリ不足の場合は NULL が返されます。

20.4.29 `mysql_insert_id()`

my_ulonglong mysql_insert_id(MYSQL *mysql)

20.4.29.1 説明

前のクエリによって AUTO_INCREMENT フィールドに生成された ID を返します。 AUTO_INCREMENT フィールドを含むテーブルに INSERT クエリを実行した後で、この関数を使用してください。

注意: 前のクエリが AUTO_INCREMENT 値を生成しなかった場合、 mysql_insert_id() は 0 を返します。後のために値を保存する必要がある場合、値を生成するクエリの直後に mysql_insert_id() を呼び出すことに気をつけてください。

また、SQL LAST_INSERT_ID() 常に最後に生成された AUTO_INCREMENT 値を含み、クエリ間でリセットされないことに注意して下さい。その関数の値はサーバ内で保守されるからです。

20.4.29.2 戻り値

前のクエリによって更新された AUTO_INCREMENT フィールドの値。接続上の前のクエリがない場合、クエリが AUTO_INCREMENT 値を更新しなかった場合には 0 が返ります。

20.4.29.3 エラー

無し。

20.4.30 `mysql_kill()`

int mysql_kill(MYSQL *mysql, unsigned long pid)

20.4.30.1 説明

pid で指定されたスレッドを殺すようにサーバに頼みます。

20.4.30.2 戻り値

成功時0。失敗時非0。

20.4.30.3 エラー

CR_COMMANDS_OUT_OF_SYNC: 不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR: MySQL サーバがいなくなった。
CR_SERVER_LOST: サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR: 未知のエラーが発生した。

20.4.31 `mysql_list_dbs()`

MYSQL_RES *mysql_list_dbs(MYSQL *mysql, const char *wild)

20.4.31.1 説明

サーバ上の、wild 引数で指定された簡易正規表現に適合する、データベース名からなる結果セットを返します。wild はワイルドカード文字 `%' または `_' を含むことができます。また、全てのデータベースに適合するように NULL ポインタにできます。mysql_list_dbs() の呼び出しはクエリ SHOW databases [LIKE wild] を実行するのと同様です。

mysql_free_result() で結果セットを解放する必要があります。

20.4.31.2 戻り値

成功時 MYSQL_RES 結果セット。失敗した場合は NULL。

20.4.31.3 エラー

CR_COMMANDS_OUT_OF_SYNC: 不当な順にコマンドが実行された。
CR_OUT_OF_MEMORY: メモリ不足。
CR_SERVER_GONE_ERROR: MySQL サーバがいなくなった。
CR_SERVER_LOST: サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR: 未知のエラーが発生した。

20.4.32 `mysql_list_fields()`

MYSQL_RES *mysql_list_fields(MYSQL *mysql, const char *table, const char *wild)

20.4.32.1 説明

与えられたテーブル内の、wild 引数で指定された簡易正規表現に適合するフィールド名からなる結果セットを返します。wild はワイルドカード文字 `%' または `_' を含むことができます。また、全てのフィールドに適合するように NULL ポインタにできます。 mysql_list_fields() はクエリ SHOW COLUMNS FROM table [LIKE wild] を実行するのと同様です。

注意: mysql_list_fields() の代わりに SHOW COLUMNS FROM tbl_name の使用を勧めます。

mysql_free_result() で結果セットを解放する必要があります。

20.4.32.2 戻り値

成功時 MYSQL_RES 結果セット。エラーが発生した場合は NULL。

20.4.32.3 エラー

CR_COMMANDS_OUT_OF_SYNC: 不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR: MySQL サーバがいなくなった。
CR_SERVER_LOST: サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR: 未知のエラーが発生した。

20.4.33 `mysql_list_processes()`

MYSQL_RES *mysql_list_processes(MYSQL *mysql)

20.4.33.1 説明

現在のサーバスレッドを示す結果セットを返します。これは mysqladmin processlist や SHOW PROCESSLIST クエリで報告されるものと同じ種類の情報です。

mysql_free_result() で結果セットを解放する必要があります。

20.4.33.2 戻り値

成功時 MYSQL_RES 結果セット。失敗した場合は NULL。

20.4.33.3 エラー

CR_COMMANDS_OUT_OF_SYNC: 不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR: MySQL サーバがいなくなった。
CR_SERVER_LOST: サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR: 未知のエラーが発生した。

20.4.34 `mysql_list_tables()`

MYSQL_RES *mysql_list_tables(MYSQL *mysql, const char *wild)

20.4.34.1 説明

wild 引数で指定された簡易正規表現に適合する、現在のデータベース内のテーブル名からなる結果セットを返します。wild はワイルドカード文字 `%' または `_' を含むことができます。また、全てのテーブルに適合するように NULL ポインタにできます。 mysql_list_tables() はクエリ SHOW tables [LIKE wild] を実行するのと同様です。

mysql_free_result() で結果セットを解放する必要があります。

20.4.34.2 戻り値

成功時 MYSQL_RES 結果セット。失敗した場合は NULL。

20.4.34.3 エラー

CR_COMMANDS_OUT_OF_SYNC: 不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR: MySQL サーバがいなくなった。
CR_SERVER_LOST: サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR: 未知のエラーが発生した。

20.4.35 `mysql_num_fields()`

unsigned int mysql_num_fields(MYSQL_RES *result)

または

unsigned int mysql_num_fields(MYSQL *mysql)

二番目の形式は MySQL 3.23 以上では動作しません。MYSQL* 引数を通す場合は、代わりに unsigned int mysql_field_count(MYSQL*mysql) を使用しなくてはいけません。

20.4.35.1 説明

結果セット中のフィールド数を返します。

注意: 結果セットへのポインタまたは接続ハンドルのいずれかからフィールドの数を得ることができます。mysql_store_result() または mysql_user_result() が NULL を返した（つまり結果セットポインタが無い）場合、接続ハンドルを使用します。この場合、 mysql_field_count() を呼び出して、mysql_store_result() が空でない結果を提供すべきかどうかを決定できます。これにより、クライアントプログラムはクエリが SELECT（または SELECT に似た）ステートメントだったかどうかを知ることなしに、適切な行動を取ることができます。以下に示す例はこれをどのように行なうかを説明しています。

「20.4.51 mysql_query() が成功を返した後、mysql_store_result() が NULL を返す時があるのは何故？」節参照.

20.4.35.2 戻り値

結果セット中のフィールド数を表わす符号無し整数。

20.4.35.3 エラー

無し。

20.4.35.4 例

MYSQL_RES *result;
unsigned int num_fields;
unsigned int num_rows;

if (mysql_query(&mysql,query_string))
{
    // error
}
else // query succeeded, process any data returned by it
{
    result = mysql_store_result(&mysql);
    if (result)  // there are rows
    {
        num_fields = mysql_num_fields(result);
        // retrieve rows, then call mysql_free_result(result)
    }
    else  // mysql_store_result() returned nothing; should it have?
    {
        if (mysql_errno(&mysql))
	{
           fprintf(stderr, "Error: %s\n", mysql_error(&mysql));
	}
        else if (mysql_field_count(&mysql) == 0)
        {
            // query does not return data
            // (it was not a SELECT)
            num_rows = mysql_affected_rows(&mysql);
        }
    }
}

（結果セットが返るべきクエリであることを知っている場合の）方法は、 mysql_errno(&mysql) コールを mysql_field_count(&mysql) が 0 かどうかのチェックに置き換えることです。これは何かが悪い場合にだけ起こります。

20.4.36 `mysql_num_rows()`

my_ulonglong mysql_num_rows(MYSQL_RES *result)

20.4.36.1 説明

結果セット中のレコード数を返します。

mysql_num_rows() の使用は、結果セットを返すのに mysql_store_result() か mysql_use_result() のどちらを使用するかに依存します。mysql_store_result() を使用する場合、 mysql_num_rows() はすぐに呼ぶことができます。 mysql_use_result() を使用する場合、結果セットの全てのレコードが取り出されるまで、mysql_num_rows() は正しい値を返しません。

20.4.36.2 戻り値

結果セットのレコード数。

20.4.36.3 エラー

無し。

20.4.37 `mysql_options()`

int mysql_options(MYSQL *mysql, enum mysql_option option, const char *arg)

20.4.37.1 説明

特別な接続オプションを設定し、接続の振舞いに影響を与えるために使用できます。この関数は複数のオプションを設定するために複数回呼ぶことができます。

mysql_options() は mysql_init() の後で、 mysql_connect() や mysql_real_connect() の前に呼ばれなければなりません。

option 引数は設定したいオプションです; arg 引数はオプションに対する値です。オプションが整数の場合、arg は整数値へのポインタです。

有効なオプション値:

オプション	引数型	機能
`MYSQL_OPT_CONNECT_TIMEOUT`	`unsigned int *`	接続タイムアウト（秒）。
`MYSQL_OPT_COMPRESS`	使用しない	圧縮クライアント／サーバプロトコルを使用する。
`MYSQL_OPT_NAMED_PIPE`	使用しない	NT 上の MySQL サーバへの接続に名前付パイプを使用する。
`MYSQL_INIT_COMMAND`	`char *`	MySQL サーバへの接続時に実行するコマンド。再接続時に自動的に再実行される。
`MYSQL_READ_DEFAULT_FILE`	`char *`	`my.cnf' の代わりに指定されたオプションファイルからオプションを読み込む。
`MYSQL_READ_DEFAULT_GROUP`	`char *`	`my.cnf' または `MYSQL_READ_DEFAULT_FILE` で指定されたファイルから指定されたグループのオプションを読み込む。

注意: MYSQL_READ_DEFAULT_FILE と MYSQL_READ_DEFAULT_GROUP を使用する場合、client グループが常に読まれます。

オプションファイル中に指定されるグループは次のオプションを含むことができます:

`compress`	圧縮クライアント／サーバプロトコルを使用する。
`database`	接続命令中でデータベースが指定されない場合、このデータベースに接続する。
`debug`	デバッグオプション
`host`	デフォルトホスト名
`init-command`	MySQL サーバへの接続時に実行するコマンド。再接続時に自動的に再実行される。
`password`	デフォルトパスワード
`pipe`	NT 上の MySQL サーバへの接続に名前付パイプを使用する。
`port`	デフォルトポート番号
`return-found-rows`	`UPDATE` 使用時、`mysql_info()` が更新された行の代わりに見つかった行を返すようにする。
`socket`	デフォルトソケット番号
`timeout`	接続タイムアウト（秒）。
`user`	デフォルトユーザ

オプションファイルについてのさらなる情報は、「4.15.4 オプションファイル ( my.cnf )」節を参照して下さい。

20.4.37.2 戻り値

成功の場合は0。未知のオプションを使用した場合は非0。

20.4.37.3 例

MYSQL mysql;

mysql_init(&mysql);
mysql_options(&mysql,MYSQL_OPT_COMPRESS,0);
mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,"odbc");
if (!mysql_real_connect(&mysql,"host","user","passwd","database",0,NULL,0))
{
    fprintf(stderr, "Failed to connect to database: Error: %s\n",
          mysql_error(&mysql));
}

上記は、圧縮クライアント／サーバプロトコルを使用し、my.cnf ファイル中の odbc セクションから追加オプションを読むように、クライアントに要求します。

20.4.38 `mysql_ping()`

int mysql_ping(MYSQL *mysql)

20.4.38.1 説明

サーバへの接続が動作しているかどうかをチェックします。ダウンしている場合は、自動的に再接続を試みます。

この関数は、長い間静かにしているクライアントが、サーバが接続をクローズしたかどうかをチェック（と再接続）するために使用できます。

20.4.38.2 戻り値

サーバが生きている場合0。他の値はエラーを示します。

20.4.38.3 エラー

CR_COMMANDS_OUT_OF_SYNC: 不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR: MySQL サーバがいなくなった。
CR_UNKNOWN_ERROR: 未知のエラーが発生した。

20.4.39 `mysql_query()`

int mysql_query(MYSQL *mysql, const char *query)

20.4.39.1 説明

NULL 終端文字列 query で示される SQL クエリを実行します。クエリはひとつの SQL ステートメントでなければなりません。終端のセミコロン (`;')や \g をステートメントに追加すべきではありません。

mysql_query() はバイナリデータを含むクエリには使用できません（バイナリデータは `\0' 文字を含むことがあります。これはクエリ文字列の最後として解釈されます）。この場合、mysql_real_query() を代わりに使用してください。

20.4.39.2 戻り値

クエリが成功した場合は0。クエリが失敗した場合は非0。

20.4.39.3 エラー

CR_COMMANDS_OUT_OF_SYNC: 不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR: MySQL サーバがいなくなった。
CR_SERVER_LOST: サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR: 未知のエラーが発生した。

20.4.40 `mysql_real_connect()`

MYSQL *mysql_real_connect(MYSQL *mysql, const char *host, const char *user, const char *passwd, const char *db, unsigned int port, const char *unix_socket, unsigned int client_flag)

20.4.40.1 説明

host 上で動作している MySQL データベースエンジンへの接続の確立を試みます。 mysql_get_client_info() 以外の他の API 関数を実行する前に、 mysql_real_connect() が成功している必要があります。

mysql_real_connect() を呼び出す前に、MYSQL 構造体を獲得または初期化するために mysql_init() を呼ぶ必要があることに注意してください。

最初のパラメータは既存の MYSQL 構造体のアドレスです。 mysql_real_connect() を呼ぶ前に、MYSQL 構造体の初期化のために mysql_init() を呼ぶ必要があります。後述の例を参照してください。
host の値はホスト名か IP アドレスのどちらでも可能です。 host が NULL または文字列 "localhost" の場合はローカルホストへの接続とみなされます。OS がソケットをサポートする場合(Unix) または名前つきパイプをサポートする場合(Win32)、サーバへの TCP/IP 接続の代わりに使用されます。
user パラメータはユーザの MySQL ログイン ID が入っています。 user が NULL の場合、現在のユーザとみなされます。Windows ODBC 下では、現在のユーザは明示的に指定されなければなりません。Unix 下では現在のログイン名が適用されます。 Windows ODBC では, カレントのユーザー名を与えなければなりません。「16.4 ODBC 管理プログラムの各種項目を埋めるには？」節参照.
passwd パラメータは user のパスワードが入っています。もし passwd が NULL の場合、空白のパスワードフィールドを持つ user テーブル内のレコードだけが適合チェックされます。このような方法で、パスワードが記述されたかどうかによってユーザが異なる特権を得るように、データベース管理者が MySQL 特権システムを設定することができます。注意: mysql_connect() を呼び出す前に passwd を暗号化しないでください。パスワードの暗号化はクライアント API で自動的に処理されます。
db が NULL でない場合、接続はこの値をデフォルトデータベースにセットします。
port が 0 でない場合、値は TCP/IP 接続のポート番号として使用されます。host パラメータが接続のタイプを決定することに注意してください。
unix_socket が NULL でない場合、文字列は使用されるソケットまたは名前つきパイプを記述します。host パラメータが接続のタイプを決定することに注意してください。

client_flag の値は通常 0 ですが、とても特殊な状況のため次のフラグの組み合わせを設定できます:

フラグ名	フラグの意味
`CLIENT_FOUND_ROWS`	影響された行数ではなく見つかった行数を返します
`CLIENT_NO_SCHEMA`	`db_name.tbl_name.col_name` を許しません。これは ODBC のためです; その構文を使用した場合、パーサがエラーを生成します。これはいくつかの ODBC プログラムのバグのトラップに役立ちます。
`CLIENT_COMPRESS`	圧縮プロトコルを使用します
`CLIENT_ODBC`	クライアントが ODBC クライアント。これは `mysqld` をさらに ODBC-フレンドリに変更します。

mysql_real_connect() の最初の引数に NULL ポインタを記述することもできます。これは C API が接続構造体のメモリを割り当て、 mysql_close() 呼び出し時に自動的に解放されます。この方法の不利な点は、接続が失敗した場合に mysql_real_connect() からのエラーメッセージを取り出すことができないことです。

最初の引数が NULL ポインタでない場合は、存在する MYSQL 構造体のアドレスであるべきです。

20.4.40.2 戻り値

接続が成功した場合は MYSQL* 接続ハンドルです。接続が失敗した場合は C NULL ポインタです。接続に成功すると、最初のパラメータが {NULL} でない場合、戻り値はそのパラメータの値と同じです。

20.4.40.3 エラー

CR_CONN_HOST_ERROR: MySQL サーバへの接続に失敗した。
CR_CONNECTION_ERROR: ローカル MySQL サーバへの接続に失敗した。
CR_IPSOCK_ERROR: IP ソケットの生成に失敗した。
CR_OUT_OF_MEMORY: メモリ不足。
CR_SOCKET_CREATE_ERROR: Unix ソケットの生成に失敗した。
CR_UNKNOWN_HOST: ホスト名の IP アドレスを見つけるのに失敗した。
CR_VERSION_ERROR: 異なるプロトコルバージョンを使用するクライアントライブラリでサーバへの接続を試みた結果のプロトコルミスマッチ。これは、とても古いクライアントライブラリを使用して、--old-protocol オプション付きで開始していない新しいサーバに接続する場合に発生します。
CR_NAMEDPIPEOPEN_ERROR;: Win32 上の名前つきパイプの生成に失敗した。
CR_NAMEDPIPEWAIT_ERROR;: Win32 上の名前つきパイプの wait に失敗した。
CR_NAMEDPIPESETSTATE_ERROR;: Win32 上のパイプハンドラの獲得に失敗した。

20.4.40.4 例

MYSQL mysql;

mysql_init(&mysql);
if (!mysql_real_connect(&mysql,"host","user","passwd","database",0,NULL,0))
{
    fprintf(stderr, "Failed to connect to database: Error: %s\n",
          mysql_error(&mysql));
}

20.4.41 `mysql_real_query()`

int mysql_real_query(MYSQL *mysql, const char *query, unsigned int length)

20.4.41.1 説明

query で示される SQL クエリを実行します。これは length バイト長です。クエリはひとつの SQL ステートメントでなければなりません。終端のセミコロン(`;')や \g をステートメントに追加すべきではありません。

バイナリデータを含むクエリは mysql_real_query() を使用しなければなりません。バイナリデータは `\0' 文字を含むことがあるからです。また、mysql_real_query() は mysql_query() よりも速いです。クエリの strlen() を呼ばないからです。

20.4.41.2 戻り値

クエリが成功した場合は0。クエリが失敗した場合は非0。

20.4.41.3 エラー

CR_COMMANDS_OUT_OF_SYNC: 不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR: MySQL サーバがいなくなった。
CR_SERVER_LOST: サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR: 未知のエラーが発生した。

20.4.42 `mysql_reload()`

int mysql_reload(MYSQL *mysql)

20.4.42.1 説明

MySQL サーバに、アクセス権テーブルを再読み込みするように依頼します。接続されたユーザは reload 特権を持つ必要があります。

この関数は推奨されません。代わりに、SQL FLUSH PRIVILEGES ステートメントを発行する mysql_query() の使用が推奨されます。

20.4.42.2 戻り値

成功時0。失敗時非0。

20.4.42.3 エラー

CR_COMMANDS_OUT_OF_SYNC: 不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR: MySQL サーバがいなくなった。
CR_SERVER_LOST: サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR: 未知のエラーが発生した。

20.4.43 `mysql_row_seek()`

MYSQL_ROW_OFFSET mysql_row_seek(MYSQL_RES *result, MYSQL_ROW_OFFSET offset)

20.4.43.1 説明

レコードカーソルをクエリ結果セット中の絶対レコードに設定します。これは、結果セット構造体がクエリのすべての結果を持っていることを要求します。そのため、 mysql_row_seek() は mysql_store_result() と共にだけ使用でき、 mysql_use_result() と共には使用できません。

オフセットは mysql_row_tell() または mysql_row_seek() 呼びだしからの戻り値であるべきです。この値は単純なレコード番号ではありません;レコード番号を使用して結果セット内のレコードにシークしたい場合は、 mysql_data_seek() を代わりに使用してください。

20.4.43.2 戻り値

レコードカーソルの前の値。この値はその後の mysql_row_seek() 呼びだしに渡すことができます。

20.4.43.3 エラー

無し。

20.4.44 `mysql_row_tell()`

MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES *result)

20.4.44.1 説明

最後の mysql_fetch_row() についてレコードカーソルの現在の位置を返します。この値は mysql_row_seek() への引数として使用できます。

mysql_row_tell() は mysql_store_result() の後にだけ使用すべきで、mysql_use_result() の後には使用すべきではありません。

20.4.44.2 戻り値

行カーソルの現在のオフセット。

20.4.44.3 エラー

無し。

20.4.45 `mysql_select_db()`

int mysql_select_db(MYSQL *mysql, const char *db)

20.4.45.1 説明

mysql で示される現在の接続に、デフォルト(現在の)データベースとして db で示されるデータベースを使用するように指示します。以降のクエリでは、明示的にデータベースを指定しないテーブル参照について、このデータベースがデフォルトになります。

接続されたユーザがデータベースを使用する権限を持っていると証明されなければ、mysql_select_db() は失敗します。

20.4.45.2 戻り値

成功時0。失敗時非0。

20.4.45.3 エラー

CR_COMMANDS_OUT_OF_SYNC: 不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR: MySQL サーバがいなくなった。
CR_SERVER_LOST: サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR: 未知のエラーが発生した。

20.4.46 `mysql_shutdown()`

int mysql_shutdown(MYSQL *mysql)

20.4.46.1 説明

データベースサーバにシャットダウンするように要求します。接続されたユーザは shutdown 特権を持っている必要があります。

20.4.46.2 戻り値

成功時0。失敗時非0。

20.4.46.3 エラー

CR_COMMANDS_OUT_OF_SYNC: 不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR: MySQL サーバがいなくなった。
CR_SERVER_LOST: サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR: 未知のエラーが発生した。

20.4.47 `mysql_stat()`

char *mysql_stat(MYSQL *mysql)

20.4.47.1 説明

mysqladmin status で提供されるのと同様の情報を文字列として返します。これは秒での uptime と、実行中のスレッド数、問い合わせ数、再読み込み数、オープンテーブル数を含みます。

20.4.47.2 戻り値

サーバ状態を表わす文字列。エラーが発生した場合 NULL。

20.4.47.3 エラー

CR_COMMANDS_OUT_OF_SYNC: 不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR: MySQL サーバがいなくなった。
CR_SERVER_LOST: サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR: 未知のエラーが発生した。

20.4.48 `mysql_store_result()`

MYSQL_RES *mysql_store_result(MYSQL *mysql)

20.4.48.1 説明

データを取り出すクエリ(SELECT, SHOW, DESCRIBE, EXPLAIN)が成功する毎に、mysql_store_result() または mysql_use_result() を呼び出す必要があります。

mysql_store_result() はクエリのすべての結果をクライアントへ読み込み、 MYSQL_RES 構造体を割り当て、この構造体に結果を配置します。

返されるレコードが無い場合、空の結果セットが返されます。 (空の結果セットは NULL 戻り値とは異なります。)

一度 mysql_store_result() を呼び出したら、結果セット中にいくつのレコードがあるかを見つけるために、mysql_num_rows() を呼び出すことができます。

結果セットからレコードを取り出すために mysql_fetch_row() を呼び出すことができます。また、結果セット内の現在のレコード位置を設定／取得するために mysql_row_seek() と mysql_row_tell() を呼び出すことができます。

一度結果セットで行なうと、mysql_free_result() を呼び出す必要があります。

「20.4.51 mysql_query() が成功を返した後、mysql_store_result() が NULL を返す時があるのは何故？」節参照.

20.4.48.2 戻り値

結果の MYSQL_RES 結果構造体。エラーがある場合 NULL。

20.4.48.3 エラー

CR_COMMANDS_OUT_OF_SYNC: 不当な順にコマンドが実行された。
CR_OUT_OF_MEMORY: メモリ不足。
CR_SERVER_GONE_ERROR: MySQL サーバがいなくなった。
CR_SERVER_LOST: サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR: 未知のエラーが発生した。

20.4.49 `mysql_thread_id()`

unsigned long mysql_thread_id(MYSQL *mysql)

20.4.49.1 説明

現在の接続のスレッド ID を返します。この値は、スレッドを殺すための mysql_kill() への引数として使用できます。

接続が失われて、mysql_ping() で再接続した場合、スレッド ID は変更されます。これはスレッド ID を後で使うために取得して格納すべきではないことを意味します。必要な時にそれを取得すべきです。

20.4.49.2 戻り値

現在の接続のスレッド ID。

20.4.49.3 エラー

無し。

20.4.50 `mysql_use_result()`

MYSQL_RES *mysql_use_result(MYSQL *mysql)

20.4.50.1 説明

データを取り出すクエリ(SELECT, SHOW, DESCRIBE, EXPLAIN)が成功する毎に、 mysql_store_result() または mysql_use_result() を呼び出す必要があります。

mysql_use_result() は結果セット検索を開始しますが, mysql_store_result() のように、実際にクライアントに結果セットを読み取りません. 代わりに、各レコードは mysql_fetch_row() 呼びだしが行なわれることにより、個々に取り出されます。 mysql_use_result() はクエリの結果を、一時テーブルやローカルバッファに格納すること無く、サーバから直接読み込みます。これは mysql_store_result() よりもいくらか速く、少ないメモリを使用します。この場合、クライアントは現在の行と接続バッファ ( max_allowed_packet bytes まで増加する ) のメモリだけを割り当てます。

一方、クライアント側で各行について多くの処理を行なう場合や、ユーザが ^S (スクロール停止) を入力できるような画面に出力を送る場合は、mysql_use_result() を使用すべきではありません。これはサーバと連携しており、他のスレッドがデータが取り出されるテーブルを更新する事を邪魔します。

mysql_use_result() 使用時、NULL 値を取り出すまで mysql_fetch_row() を実行する必要があります。そうしないと、次のクエリは前のクエリから結果を取り出します。これを忘れると、C API はエラー Commands out of sync; You can't run this command now を与えます！

mysql_use_result() から返される結果では、 mysql_data_seek(), mysql_row_seek(), mysql_row_tell(), mysql_num_rows(), mysql_affected_rows() を使用できません。また、mysql_use_result() が終了するまで他のクエリの発行もできません。(全ての行をフェッチした後に、フェッチされた行数を知るために mysql_num_rows を呼び出すことができます。)

一度結果セットで行なうと、mysql_free_result() を呼び出す必要があります。

20.4.50.2 戻り値

結果の MYSQL_RES 結果構造体。エラーがある場合 NULL。

20.4.50.3 エラー

CR_COMMANDS_OUT_OF_SYNC: 不当な順にコマンドが実行された。
CR_OUT_OF_MEMORY: メモリ不足。
CR_SERVER_GONE_ERROR: MySQL サーバがいなくなった。
CR_SERVER_LOST: サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR: 未知のエラーが発生した。

20.4.51 `mysql_query()` が成功を返した後、`mysql_store_result()` が `NULL` を返す時があるのは何故？

mysql_query() の呼び出しが成功した後に mysql_store_result() が NULL を返すことがあります。これが起こったとき、次の条件のどれかの発生を意味します:

malloc() が失敗した (例えば、結果セットが大き過ぎた場合)。
データが読めなかった (接続のエラー)。
クエリがデータを返さなかった (INSERT, UPDATE, DELETE)。

ステートメントが空でない結果を提供するかどうかは mysql_field_count() の呼び出しによっていつでもチェックできます。 mysql_field_count() が 0 を返す場合、結果は空で最後のクエリは値を返さないステートメントです (例えば、INSERT や DELETE)。 mysql_field_count() が非 0 値を返す場合、ステートメントは空でない結果を提供します。例はmysql_field_count() 関数の説明を参照してください。

mysql_error() または mysql_errno() を呼び出すことによってエラーのテストもできます。

20.4.52 クエリから得られる結果は何か？

クエリによって返される結果セットに加えて、次の情報も得ることができます:

mysql_affected_rows() は、INSERT, UPDATE または DELETE を行なった時の最後のクエリで、影響された行数を返します。 WHERE 節がない DELETE が使用されて、テーブルが切り詰められた場合は例外です。これはとても速いです！この場合、 mysql_affected_rows() は影響された行数を 0 と返します。
mysql_num_rows() は結果セットのレコード数を返します。 mysql_store_result() では、mysql_num_rows() は mysql_store_result() が復帰したすぐ後に呼び出すことができます。 mysql_use_result() では、mysql_num_rows() は mysql_fetch_row() ですべてのレコードを取り出した後にだけ呼ぶ出すことができます。
mysql_insert_id() は、AUTO_INCREMENT インデックスを持つテーブルに行を挿入した最後のクエリによって生成された ID を返します。「20.4.29 mysql_insert_id()」節参照.
いくつかのクエリ (LOAD DATA INFILE..., INSERT INTO ... SELECT ..., UPDATE) は追加情報を返します。結果は mysql_info() で返されます。返す文字列の形式については、mysql_info() の説明を参照してください。 mysql_info() は追加情報がない場合は NULL ポインタを返します。

20.4.53 最後に挿入された行のユニーク ID をどのように得られるか？

AUTO_INCREMENT 属性を持つ項目を含むテーブルにレコードを挿入する場合、mysql_insert_id() 関数で与えられた ID を得ることができます。

mysql_query() に渡すクエリ文字列内のLAST_INSERT_ID() 関数を使用することでも、ID を取り出すことができます。

次のコードを実行することで、AUTO_INCREMENT インデックスが使用されたかどうかチェックできます。これは、クエリが AUTO_INCREMENT インデックスを伴う INSERT だったかどうかもチェックできます:

if (mysql_error(&mysql)[0] == 0 &&
    mysql_num_fields(result) == 0 &&
    mysql_insert_id(&mysql) != 0)
{
    used_id = mysql_insert_id(&mysql);
}

生成された最後の ID は接続毎にサーバ内で維持されています。他のクライアントによって変更はされません。他の AUTO_INCREMENT 項目を非マジック値 (すなわち、NULL でなく 0 でない値) で更新する場合でも、それは変更されません。

また、他のテーブルにその ID を挿入しようとする場合、次で行なうことができます:

INSERT INTO foo (auto,text)
    VALUES(NULL,'text');              # generate ID by inserting NULL
INSERT INTO foo2 (id,text)
    VALUES(LAST_INSERT_ID(),'text');  # use ID in second table

20.4.54 C API でのリンクの問題

C API でリンクする時、いくつかのシステム上では次のエラーになります:

gcc -g -o client test.o -L/usr/local/lib/mysql -lmysqlclient -lsocket -lnsl

Undefined        first referenced
 symbol          in file
floor            /usr/local/lib/mysql/libmysqlclient.a(password.o)
ld: fatal: Symbol referencing errors. No output written to client

これは、あなたのシステム上では、コンパイル/リンク行の最後に、math ライブラリ (-lm) を含める必要があることを意味します。

20.4.55 スレッド安全クライアントを作る方法

クライアントは `ほとんど' スレッド安全です。一番大きな問題は `net.c' (ソケットから読み込みをするサブルーチンを含むファイル) が割り込み安全でないことです。これは、サーバからの長い読み込みを中断できるように、自身のアラームを持ちたいだろうという考慮で行なわれました。

標準クライアントライブラリはスレッドオプションでコンパイルされていません。

スレッド安全クライアントを得るためには、-lmysys, -lstring, -ldbug ライブラリとサーバが使用する net_serv.o を使用します。

スレッドクライアントを使用する時、`thr_alarm.c' ルーチンを大いに使用できます。mysys ライブラリからのルーチンを使用する場合、覚えておかなければならないことは my_init() を最初に呼ぶことだけです！

mysql_real_connect() を除く全ての関数は現在スレッド安全です。スレッド安全クライアントライブラリをコンパイルし、それをスレッド安全なマナーで使用するための方法を、次の注意で説明します。(この mysql_real_connect() についての注意は、実際には mysql_connect() にも有効です。しかし mysql_connect() は推奨されませんので、とにかく mysql_real_connect() を使用すべきです。)

mysql_real_connect() をスレッド安全にするためには、クライアントを次のコマンドで再コンパイルする必要があります:

shell> CPPFLAGS=-DTHREAD_SAFE_CLIENT ./configure ...

標準クライアントのリンク時に未定義シンボルのためいくつかのエラーが出るでしょう。これはデフォルトでは pthread ライブラリが含まれていないためです。

結果の `libmysqlclient.a' ライブラリはスレッド安全です。これの意味することは、同じ接続ハンドル(mysql_real_connect() で返される)に、同時に２つのスレッドからクエリを行なわない限り、クライアントコードはスレッド安全ということです; クライアント／サーバプロトコルは、与えられた接続上で同時に一つの要求だけを許します。複数のスレッドから同じ接続を使用したい場合は、 mysql_query() と mysql_store_result() の組み合わせのまわりで mutex lock を行なう必要があります。一度 mysql_store_result() の用意ができると、ロックは解放でき、他のスレッドが同じ接続にクエリを行なうことができます。(他の言葉で言うと、正しいロックプロトコルを使用する限り、別のスレッドは、mysql_store_result() で生成される別の MYSQL_RES ポインタを使用できます。) POSIX スレッドでプログラムを行なう場合、 pthread_mutex_lock() と pthread_mutex_unlock() を、mutex lock の確立と解放に使用できます。

mysql_store_result() でなく mysql_use_result() を使用する場合、mysql_use_result() の回りと mysql_fetch_row() 呼び出しにロックが必要です。しかし、スレッド化クライアントに本当に一番良いのは、 mysql_use_result() を使用しないことです。

20.5 MySQL Perl API

This section documents the Perl DBI interface. The former interface was called mysqlperl. DBI/DBD が Perl インターフェースとして現在推奨されているので、 mysqlperl に関してはここでは述べない。

20.5.1 `DBI` with `DBD::mysql`

DBI は多くのデーターベースとの一般的なインターフェースである。これは、多くのデーターベースと動作するスクリプトを変更なしに書けることを意味する。そのためには、それぞれのデータベース用のデータベースドライバ (DBD) が必要である。 MySQL では、そのドライバは DBD::mysql である。

Perl5 DBI に関する詳細は、DBIウェッブページを参照のこと：

http://www.symbolstone.org/technology/perl/DBI/index.html

Object Oriented Programming (OOP) に関する詳細は、Perl OOP ページを参照のこと：

http://language.perl.com/info/documentation.html

Installation instructions for MySQL Perl support are given in 「4.10 Perl のインストールについて」節.

20.5.1.1 The `DBI` interface

Portable DBI methods

`connect`	データベースサーバと接続する
`disconnect`	データベースサーバとの接続を切る
`prepare`	SQL文を設定する
`execute`	設定されたSQL文を実行する
`do`	SQL文を設定し、実行する
`quote`	挿入するためのクォート文字、または `BLOB` 値
`fetchrow_array`	フィールドの配列として次の行を取り出す
`fetchrow_arrayref`	フィールドの配列参照として次の行を取り出す
`fetchrow_hashref`	ハッシュテーブルへの参照として次の行を取り出す
`fetchall_arrayref`	配列の配列として全データを取り出す
`finish`	命令を終了し、リソースからシステムを切り離す
`rows`	影響のあった行の数を返す
`data_sources`	ローカルホスト上で利用できるデータベースの配列を返す
`ChopBlanks`	`fetchrow_*` メソッドが空白を取り除くかどうかを管理する
`NUM_OF_PARAMS`	設定された命令文中の placeholder の数
`NULLABLE`	どのカラムに `NULL` 値があるか？
`trace`	Perform tracing for debugging

MySQL 固有メソッド

`insertid`	最後の `AUTO_INCREMENT` 値
`is_blob`	どのカラムが `BLOB` か？
`is_key`	どのカラムがキーか？
`is_num`	どのカラムが数値型か？
`is_pri_key`	どのカラムがプライマリキーか？
`is_not_null`	どのカラムが `NULL` 値か？　`NULLABLE` 参照。
`length`	利用可能なカラムサイズの最大値
`max_length`	実際に存在しているカラムサイズの最大値
`NAME`	カラム名
`NUM_OF_FIELDS`	返されたフィールドの数
`table`	返されたセットのテーブル名
`type`	全てのカラムの型
`_CreateDB`	データベースを作成する
`_DropDB`	データベースを削除する。＊＊＊このメソッドは危険である＊＊＊

以下の節に、より詳細な Perl メソッドの解説がある。 Variables used for method return values have these meanings:

$dbh: Database handle
$sth: Statement handle
$rc: Return code (often a status)
$rv: Return value (often a row count)

汎用 DBI メソッド

connect($data_source, $username, $password)

データソースとのデータベース接続をするために connect を使う。 $data_source 値は DBI:driver_name: ではじめること。 DBD::mysql ドライバーを用いた connect の使用例：

$dbh = DBI->connect("DBI:mysql:$database", $user, $password);
$dbh = DBI->connect("DBI:mysql:$database:$hostname",
                    $user, $password);
$dbh = DBI->connect("DBI:mysql:$database:$hostname:$port",
                    $user, $password);

ユーザー名またはパスワードが未設定の場合、 <DBI は環境変数である DBI_USER と DBI_PASS をそれぞれ使う。ホスト名を指定しない場合は、'localhost' がデフォルトとなる。ポート番号を指定しない場合は、MySQL ポート（3306）がデフォルトとなる。 As of Msql-Mysql-modules version 1.2009, the $data_source value allows certain modifiers:

mysql_read_default_file=file_name: Read `filename' as an option file. For information on option files, see 「4.15.4 オプションファイル ( my.cnf )」節.
mysql_read_default_group=group_name: The default group when reading an option file is normally the [client] group. By specifying the mysql_read_default_group option, the default group becomes the [group_name] group.
mysql_compression=1: Use compressed communication between the client and server (MySQL 3.22.3 or later).
mysql_socket=/path/to/socket: Specify the pathname of the Unix socket that is used to connect to the server (MySQL 3.21.15 or later).

Multiple modifiers may be given; each must be preceded by a semicolon. For example, if you want to avoid hardcoding the user name and password into a DBI script, you can take them from the user's `~/.my.cnf' option file instead by writing your connect call like this:

$dbh = DBI->connect("DBI:mysql:$database"
                . ";mysql_read_default_file=$ENV{HOME}/.my.cnf",
                $user, $password);

This call will read options defined for the [client] group in the option file. If you wanted to do the same thing, but use options specified for the [perl] group as well, you could use this:

$dbh = DBI->connect("DBI:mysql:$database"
                . ";mysql_read_default_file=$ENV{HOME}/.my.cnf"
                . ";mysql_read_default_group=perl",
                $user, $password);

disconnect

disconnect メソッドは、データベースとのデータベースハンドルを切断する。プログラムを終了する直前に呼び出されるのが典型的である。例：

$rc = $dbh->disconnect;

prepare($statement)

データベースエンジンで実行するためのSQL文を設定し、execute メソッドで使用出来るステートメントハンドル ($sth) を返す。 the execute method. Typically you handle SELECT statements (and SELECT-like statements such as SHOW, DESCRIBE and EXPLAIN) by means of prepare and execute. 例：

$sth = $dbh->prepare($statement)
    or die "Can't prepare $statement: $dbh->errstr\n";

execute

execute メソッドは、設定されたSQL文を実行する。非 SELECT 文のときは、影響のあった行の数を返す。If no rows are affected, execute returns "0E0", which Perl treats as zero but regards as true. SELECT 文のときは、SQL要求を開始するのみである。データを操作する fetch_* メソッドの内の一つを記述する必要がある。例：

$rv = $sth->execute
          or die "can't execute the query: $sth->errstr;

do($statement)

do メソッドはSQL文を設定・実行し、影響のあった行の数を返す。このメソッドは、「非 select」文、すなわち、高度（ドライバーの限界のため）で設定できない文、一度の実行（inserts, deletes など）で済む文のときに一般的に用いられる。例：

$rv = $dbh->do($statement)
        or die "Can't execute $statement: $dbh- >errstr\n";

quote($string)

quote メソッドは、文字列中にエスケープ文字があるときに用いられ、クォート文字を文の外側に付加する。例：

$sql = $dbh->quote($string)

fetchrow_array

このメソッドはデータの次の行を取り出し、フィールドの値の配列として返す。例：

while(@row = $sth->fetchrow_array) {
        print qw($row[0]\t$row[1]\t$row[2]\n);
}

fetchrow_arrayref

このメソッドはデータの次の行を取り出し、フィールドの値の配列への参照として返す。例：

while($row_ref = $sth->fetchrow_arrayref) {
        print qw($row_ref->[0]\t$row_ref->[1]\t$row_ref->[2]\n);
}

fetchrow_hashref

このメソッドはデータの行を取り出し、名前・値のペアのフィールドを含んだハッシュテーブルへの参照を返す。このメソッドは、上で示した配列参照（訳注：fetchrow_arrayref）よりもかなり効率的ではない。例：

while($hash_ref = $sth->fetchrow_hashref) {
        print qw($hash_ref->{firstname}\t$hash_ref->{lastname}\t\
                $hash_ref- > title}\n);
}

fetchall_arrayref

このメソッドは、SQL文より返されたデータ（の行）の全てを得るために使う。このメソッドは、各行への参照の配列の配列への参照を返す。入れ子のループを使ってデータを利用・表示する。例：

my $table = $sth->fetchall_arrayref
                or die "$sth->errstr\n";
my($i, $j);
for $i ( 0 .. $#{$table} ) {
        for $j ( 0 .. $#{$table->[$i]} ) {
                print "$table->[$i][$j]\t";
        }
        print "\n";
}

finish

そのステートメントハンドルからそれ以上データを取り出さないことを示す。ステートメントハンドルや、つかんでいたシステムリソースを解放するためにこのメソッドを呼び出す。例：

$rc = $sth->finish;

rows

最後の命令により、（データの更新、削除、などで）影響のあった行の数を返す。このメソッドは do あるいは非 SELECT execute 文を実行した後に、たいてい使われる。例： Example:

$rv = $sth->rows;

NULLABLE

配列の各要素に対し、ブール値の配列への参照を返す。 TRUE であればそのカラムに NULL 値が含まれていることを示す。例： Example:

$null_possible = $sth->{NULLABLE};

NUM_OF_FIELDS

この属性は、SELECT 文や SHOW FIELDS 文によって返されたフィールドの数を示している。命令文が結果を返したかどうかをチェックするのに、これを使うことが出来る：０値は、INSERT, DELETE または UPDATE のような非 SELECT 文を示している。例： Example:

$nr_of_fields = $sth->{NUM_OF_FIELDS};

data_sources($driver_name)

このメソッドは、'localhost' ホスト上の MySQL サーバで利用可能なデータベースの名前を含んだ配列を返す。例：

@dbs = DBI->data_sources("mysql");

ChopBlanks

この属性は、 fetchrow_* メソッドが返り値から前後の空白を除去するかどうかを決定する。例：

$sth->{'ChopBlanks'} =1;

trace($trace_level)

trace($trace_level, $trace_filename)

The trace method enables or disables tracing. When invoked as a DBI class method, it affects tracing for all handles. When invoked as a database or statement handle method, it affects tracing for the given handle (and any future children of the handle). Setting $trace_level to 2 provides detailed trace information. Setting $trace_level to 0 disables tracing. Trace output goes to the standard error output by default. If $trace_filename is specified, the file is opened in append mode and output for all traced handles is written to that file. Example:

DBI->trace(2);                # trace everything
DBI->trace(2,"/tmp/dbi.out"); # trace everything to /tmp/dbi.out
$dth->trace(2);               # trace this database handle
$sth->trace(2);               # trace this statement handle

You can also enable DBI tracing by setting the DBI_TRACE environment variable. Setting it to a numeric value is equivalent to calling DBI->(value). Setting it to a pathname is equivalent to calling DBI->(2,value).

MySQL 固有メソッド

The methods shown below are MySQL-specific and not part of the DBI standard. Several of them are now deprecated: is_blob, is_key, is_num, is_pri_key, is_not_null, length, max_length, and table. Where DBI-standard alternatives exist, they are noted below.

insertid

MySQL の特徴である AUTO_INCREMENT を使うとき、新しい自動繰り上がり値がここに記憶される。例： Example:

$new_id = $sth->{insertid};

As an alternative, you can use $dbh->{'mysql_insertid'}.

is_blob

配列の各要素に対し、ブール値の配列への参照を返す。TRUE であればそのカラムが BLOB 値であることを示す。例：

$keys = $sth->{is_blob};

is_key

配列の各要素に対し、ブール値の配列への参照を返す。TRUE であればそのカラムがキーであることを示す。例：

$keys = $sth->{is_key};

is_num

配列の各要素に対し、ブール値の配列への参照を返す。TRUE であればそのカラムが数値型であることを示す。例：

$nums = $sth->{is_num};

is_pri_key

配列の各要素に対し、ブール値の配列への参照を返す。TRUE であればそのカラムがプライマリーキーであることを示す。例：

$pri_keys = $sth->{is_pri_key};

is_not_null

配列の各要素に対し、ブール値の配列への参照を返す。FALSE であればそのカラムが NULL 値を含むことを示す。例：

$not_nulls = $sth->{is_not_null};

is_not_null is deprecated; 前述の NULLABLE 属性を使用するほうが望ましい。それが DBI の標準である。

length

max_length

それぞれのメソッドは、カラムサイズの配列への参照を返す。length 配列は、（テーブル記述で定義された）各カラムの利用可能最大値を示す。 max_length 配列は、テーブル中に実際に存在している最大値を示す。例：

$lengths = $sth->{length};
$max_lengths = $sth->{max_length};

NAME

カラム名の配列への参照を返す。例：

$names = $sth->{NAME};

table

テーブル名の配列への参照を返す。例：

$tables = $sth->{table};

type

カラムの型の配列への参照を返す。例：

$types = $sth->{type};

20.5.2 `DBI`/`DBD` に関するそれ以上の情報

DBI に関するそれ以上の情報は perldoc コマンドで得られる。

perldoc DBI
perldoc DBI::FAQ
perldoc DBD::mysql

他のフォーマットに変換するツール、pod2man, pod2html なども使うことが出来る。

そしてもちろん、DBI の最新情報は DBI ウェッブページで見ることが出来る：

http://www.symbolstone.org/technology/perl/DBI/index.html

20.6 MySQL Eiffel wrapper

The MySQL Contrib directory contains an Eiffel wrapper written by Michael Ravits

You can also find this at: http://www.netpedia.net/hosting/newplayer/

20.7 MySQL Java connectivity (JDBC)

There are 2 supported JDBC drivers for MySQL (the twz and mm driver). You can find a copy of these at http://www.mysql.com/Contrib. For documentation consult any JDBC documentation and the drivers own documentation for MySQL specific features.

20.8 MySQL PHP API

PHP is a server-side, HTML embedded scripting language that may be used to create dynamic web pages. It contains support for accessing several databases, including MySQL. PHP may be run as a separate program, or compiled as a module for use with the Apache web server.

The distribution and documentation are available at the PHP website.