MySQL中文參考手冊MySQL中文參考手冊譯者：晏子 (clyan@sohu.com）
GB 碼主頁：http://linuxdb.yeah.net
Big5 轉碼者：statue
(statue@bbs.yzu.edu.tw）
詞彙轉換：彭武興 (wilson@mailbox.com.tw)
Big5 碼主頁：
http://cnpa.yzu.edu.tw/~cfc/docs/mysqldoc_big5/manual_toc.html
Big5 碼分站：
http://php.wilson.gs/mysqldoc/big5/manual_toc.html
C API代碼是隨MySQL分發的，它被包含在mysqlclient庫且允許C程式存取一個資料庫。
在 MySQL原始碼版本中的很多客戶是用C編寫的。如果你正在尋找演示怎樣使用C API的例子，看一下這些客戶程式。
大多數其他客戶 API(除了Java的所有)都使用mysqlclient庫與MySQL伺服器通信。這意味著，例如，你能利用很多被其他客戶程式使用的同一環境變數，因為他們從庫中引用。對這些變數的一張表，見12.1 不同的MySQL程式的概述。
客戶有一個最大通訊緩衝區大小。初始分配的緩衝區大小(16K字節) 自動地增加到最大尺寸(內定的最大值是24M)。因為緩衝區大小只是按保証需求而被增加，簡單地增加內定的最大限制並不造成更多被消耗。該尺寸檢查主要是一個對錯誤的查詢和通訊包的檢查。
通訊緩衝區必須足夠大以便一個單獨的SQL語句(對客戶-伺服器傳輸)和一行返回的數據(對伺服器-客戶傳輸)。每個執行緒的通訊緩衝區被動態擴大到最大限制來處理任何查詢或行。例如，如果你包含大到16M數據的BLOB值，你必須有一個至少16M通訊緩衝區限制(在伺服器和客戶兩端)。客戶的內定最大值是24M，但是在伺服器端的內定最大值是1M。你可以在伺服器啟動時通過改變max_allowed_packet參數的值來改變它。見10.2.3 調節伺服器參數。
MySQL伺服器在每個查詢後縮小每個通訊緩衝區到net_buffer_length個字節。對客戶，與一個連接相關的緩衝區的大小沒被減少，直到連接被關閉，在此時客戶內存被回收。
如果你用執行緒的編程，你應該用--with-thread-safe-client編譯MySQL
C API，這將使C API執行緒對每個連接更安全。你可以讓2個執行緒共享相同的連接，只要如果你做下列事情：
mysql_query()和mysql_store_result()之間沒有其他執行緒正在使用同一個連接。
mysql_store_result()檢索出來的不同結果集合。mysql_use_result，你必須保証沒有其他執行緒在同一個連接上正在詢問任何東西，直到結果集合被關閉。
MYSQL MYSQL_RES SELECT, SHOW, DESCRIBE,
EXPLAIN)的結果。從查詢返回的資訊在本章下文稱為結果集合。MYSQL_ROW mysql_fetch_row()獲得。 MYSQL_FIELD mysql_fetch_field()對每一列獲得MYSQL_FIELD結構。字段值不是這個結構的部分﹔他們被包含在一個MYSQL_ROW結構中。MYSQL_FIELD_OFFSET 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 char * table table值是一個空字符串。char * def 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()，這個變數的值是零。unsigned int flags flags值可以是零個或多個下列位設置：| 標誌值 | 標誌含義 |
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_BLOB、FIELD_TYPE_ENUM或FIELD_TYPE_TIMESTAMP，最好是測試field->type。下面例子演示了一個典型的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 在 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() | 執行指定為一個空結尾的字符串的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()期望查詢作為一個空結尾的字符串來指定而mysql_real_query()期望一個計數的字符串。如果字符串包含二進制數據(它可以包括空字節)，你必須使用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()是非零，查詢應該有返回行，但是沒有。這表明查詢是一個失敗的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借助於mysql_errno()和mysql_error()函數提供錯誤資訊的存取。他們返回最近調用的可能成功或失敗的函數的錯誤代碼或錯誤消息，允許你確定何時發生一個錯誤和什麼錯誤。
在下面的描述中，一個NULL參數或返回值含義是在C編程語言環境的NULL，不是一個MySQL
NULL值。
返回一個值的函數一般返回一個指針或一個整數。除非另外指定，返回一個指針的函數返回一個非
NULL值表明成功，或一個NULL值表明一個錯誤，而返回一個整數的函數返回零表示成功，或非零表示一個錯誤。注意，“非零”只有這個含義。除非函數描述另外說明，不要測試一個零以外的其他值：
if (result) /* 正確 */
... error ...
if (result < 0) /* 不正確 */
... error ...
if (result == -1) /* 不正確 */
... error ...
當函數返回一個錯誤時，函數描述的錯誤小節列出錯誤可能的類型。你可以調用mysql_errno()找出發生了這些重的哪一個。錯誤的字符串表示可以調用mysql_error()獲得。
mysql_affected_rows()my_ulonglong mysql_affected_rows(MYSQL *mysql)
返回受到最後一個UPDATE、DELETE或INSERT查詢影響(變化)的行數。可以在針對UPDATE、DELETE或INSERT語句的mysql_query()之後立即調用。對於SELECT語句，mysql_affected_rows()的功能於mysql_num_rows()相同。
mysql_affected_rows()目前以一個宏(macro)來實現。
大於零的一個整數表示受到影響或檢索出來的行數。零表示沒有匹配查序中WHERE子句的記錄或目前還沒有查詢被執行。-1表示查詢返回一個錯誤，或對於一個SELECT查詢，mysql_affected_rows()在調用mysql_store_result()之前被調用。
沒有。
mysql_query(&mysql,"UPDATE products SET cost=cost*1.25 WHERE group=10");
printf("%d products updated",mysql_affected_rows(&mysql));
mysql_close()void mysql_close(MYSQL *mysql)
關閉一個以前打開了的連接。如果句柄由mysql_init()或mysql_connect()自動分配，mysql_close()也釋放被mysql指向的連接句柄。
沒有。
CR_COMMANDS_OUT_OF_SYNC CR_SERVER_GONE_ERROR CR_SERVER_LOST CR_UNKNOWN_ERROR
mysql_connect()MYSQL *mysql_connect(MYSQL *mysql, const char *host, const char *user, const char
*passwd)
該函數不推薦使用，而更好使用mysql_real_connect()。
mysql_connect()試圖建立一個對運行在host的一個MySQL資料庫引擎的連接。mysql_connect()必須在你能執行其他API函數之前成功地完成，除了mysql_get_client_info()。
參數的含義與mysql_connect()相應的參數相同，不同的是連接參數可以是NULL。在這種情況下，C
API 自動為連接結構分配內存，並且當你調用mysql_close()，釋放它。這種方法的缺點是如果連接失敗，你不能檢索出一條錯誤消息。（為了從mysql_errno()或mysql_error()得到錯誤資訊，你必須提供一個有效的MYSQL指針。）
同mysql_real_connect()。
同mysql_real_connect()。
mysql_change_user()my_bool mysql_change_user(MYSQL *mysql, const char *user, const char *password,
const char *db)
改變用戶並且使得由db指定資料庫成為由mysql指定的連接上的內定(當前)資料庫。在隨後的查詢中，這個資料庫是不包括一個明確的資料庫指定符的表引用的內定值。
這個函數功能在MySQL 3.23.3中引入。
除非連接的用戶能被認証或如果他沒有權限使用資料庫，mysql_change_user()失敗。在這種情況下，用戶和資料庫都沒被改變。
如果你不想有一個內定資料庫，db參數可以被設置為NULL。
成功，零。如果發生一個錯誤發生，非零。
與你能從mysql_real_connect()得到的相同。
CR_COMMANDS_OUT_OF_SYNC CR_SERVER_GONE_ERROR CR_SERVER_LOST CR_UNKNOWN_ERROR ER_UNKNOWN_COM_ERROR ER_ACCESS_DENIED_ERROR ER_BAD_DB_ERROR ER_DBACCESS_DENIED_ERROR ER_WRONG_DB_NAME if (mysql_change_user(&mysql, "user", "password", "new_database"))
{
fprintf(stderr, "Failed to change user. Error: %s\n",
mysql_error(&mysql));
}
mysql_create_db()int mysql_create_db(MYSQL *mysql, const char *db)
創建由db參數命名的資料庫。
這個函數不推薦，而最好使用mysql_query()發出一條SQL
CREATE DATABASE語句。
如果資料庫成功地被創造，零。如果發生一個錯誤，非零。
CR_COMMANDS_OUT_OF_SYNC CR_SERVER_GONE_ERROR CR_SERVER_LOST CR_UNKNOWN_ERROR if(mysql_create_db(&mysql, "my_database"))
{
fprintf(stderr, "Failed to create new database. Error: %s\n",
mysql_error(&mysql));
}
mysql_data_seek()void mysql_data_seek(MYSQL_RES *result, unsigned long long offset)
在一個查詢結果集合中定位任意行。這要求結果集合結構包含查詢的全部結果，這樣mysql_data_seek()可以僅需與mysql_store_result()一起使用，不是與mysql_use_result()。
偏移量應該是從0到mysql_num_rows(result)-1範圍的一個值。
無。
無。
mysql_debug()void mysql_debug(char *debug)
用一個給定字符串做一個DBUG_PUSH。mysql_debug()使用Fred
Fish 調試庫。為了使用這個函數，你必須編譯客戶庫以支援調試。見G.1 調試一個MySQL伺服器和節G.2 調試一個MySQL客戶。
無。
無。
下面所示的調用使得客戶庫在客戶機器上的“/tmp/client.trace”中產生一個跟蹤文件：
mysql_debug("d:t:O,/tmp/client.trace");
mysql_drop_db()int mysql_drop_db(MYSQL *mysql, const char *db)
拋棄由db參數命名的資料庫。
這個函數不推薦，而最好使用mysql_query()發出一條SQL
DROP DATABASE語句。
如果資料庫成功地被破拋棄，零。如果發生一個錯誤，非零。
CR_COMMANDS_OUT_OF_SYNC CR_SERVER_GONE_ERROR CR_SERVER_LOST CR_UNKNOWN_ERROR if(mysql_drop_db(&mysql, "my_database"))
fprintf(stderr, "Failed to drop the database: Error: %s\n",
mysql_error(&mysql));
mysql_dump_debug_info()int mysql_dump_debug_info(MYSQL *mysql)
指示服務者將一些調試資訊寫入日誌文件。連接的用戶對此必須有precess權限才能工作。
如果命令成功，零。如果發生一個錯誤，非零。
CR_COMMANDS_OUT_OF_SYNC CR_SERVER_GONE_ERROR CR_SERVER_LOST CR_UNKNOWN_ERROR
mysql_eof()my_bool mysql_eof(MYSQL_RES *result)
這個函數不推薦，而使用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()返回非零值，並且如果發生一個錯誤，返回零。
在時間上，mysql_eof()先於標準MySQL錯誤函數mysql_errno()和mysql_error()。因為這些錯誤函數提供相同的資訊，他們的使用更好mysql_eof()，它現在不建議使用。（事實上，他們提供更多的資訊，因為mysql_eof()值返回一個布爾值，而錯誤函數指出當發生錯誤時的出錯原因。）
如果發生一個錯誤，零。如果到達結果集合的結束，非零。
無。
下列例子顯示你必須如何使用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));
}
mysql_errno()unsigned int mysql_errno(MYSQL *mysql)
對於由mysql指定的連接，mysql_errno()返回最近調用的可能成功或失敗的API函數的錯誤代碼。返回值零意味著沒有錯誤發生。客戶錯誤消息編號列出在MySQL“errmsg.h”頭文件中。伺服器錯誤消息編號列出在“mysqld_error.h”中。
一個錯誤代碼值。如果沒有錯誤發生，零。
無。
mysql_error()char *mysql_error(MYSQL *mysql)
對於由mysql指定的連接，mysql_errno()返回最近調用的可能成功或失敗的API函數的錯誤代碼。如果沒有錯誤發生，返回空字符串("")。這意味著下列兩個測試是等價的：
if(mysql_errno(&mysql))
{
// an error occurred
}
if(mysql_error(&mysql)[0] != '\0')
{
// an error occurred
}
客戶錯誤消息的語言可通過重新編譯MySQL客戶庫來改變。目前，你能在幾種不同的語言間選取錯誤消息。見9.1 MySQL支援什麼語言？。
一個描述錯誤的字符串。如果沒有錯誤發生，空字符串。
無。
mysql_escape_string()unsigned int mysql_escape_string(char *to, const char *from, unsigned int length)
把在from中的字符串編碼為在一條SQL語句刈莃以發給伺服器的轉義的SQL字符串，將結果放在to中，
並且加上一個終止的空字節。編碼的字符是NUL（ASCII 0)、‘\n’、‘\r’、‘\’、‘'’、‘"’和Control-Z(見7.1 文字：如何寫字符串和數字)。
由from指向的字符串必須是length個字節長。你必須分配to的緩衝區至少length*2+1個字節長。（在更壞的情況，每個字符可能需要使用2個字節被編碼，並且你需要為終止空字節的空間)
當mysql_escape_string()返回時，to的內容將是空字符終止的字符串。返回值是編碼後的字符串的長度，不包括終止空字符。
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()，但是返回一個指向空終止的第一個參數的指針。
放進to的值的長度，不包括終止空字符。
無。
mysql_fetch_field()MYSQL_FIELD *mysql_fetch_field(MYSQL_RES *result)
返回作為一個MYSQL_FIELD結構的一個結果集合的一個列的定義。重複調用這個函數在結果集合中檢索所有關於列的資訊。當沒有剩下更多的字段時，mysql_fetch_field()返回NULL。
在每次你執行一個新的SELECT查詢，mysql_fetch_field()被重置（reset)以返回有關第一列的資訊。由mysql_fetch_field()返回的字段也受調用mysql_field_seek()的影響。
如果你調用mysql_query()在一張表上執行一個SELECT，但是沒調用mysql_store_result()，如果你調用mysql_fetch_field()詢問一個BLOB字段的長度，MySQL返回內定BLOB長度(8K字節)。（選擇8K的長度是因為MySQL不知道BLOB的最大長度。這應該在某個時候是它可配置)
一旦你已經檢索了結果集合，field->max_length包含了在特定查詢中對於該列最大值的長度。
當前列的MYSQL_FIELD結構。如果沒有列剩下，NULL。
無。
MYSQL_FIELD *field;
while((field = mysql_fetch_field(result)))
{
printf("field name %s\n", field->name);
}
mysql_fetch_fields()MYSQL_FIELD *mysql_fetch_fields(MYSQL_RES *result)
返回一個結果集合的所有MYSQL_FIELD結構的數組。每個結構提供結果結合中一列的字段定義。
一個結果集合的所有MYSQL_FIELD結構的一個數組。
無。
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);
}
mysql_fetch_field_direct()MYSQL_FIELD *mysql_fetch_field_direct(MYSQL_RES *result, unsigned int fieldnr)
給定在一個結果集合中的一個列的字段編號fieldnr，返回作為MYSQL_FIELD結構的列的字段定義。你可以使用這個函數檢索任意列的義。fieldnr的值應該在從0到mysql_num_fields(result)-1範圍內。
指定列的MYSQL_FIELD結構。
無。
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);
}
mysql_fetch_lengths()unsigned long *mysql_fetch_lengths(MYSQL_RES *result)
返回在結果集合內的當前行的列長度。如果你計劃拷貝字段值，這個長度資訊對最佳化也是有用的，因為你可以避免調用strlen()。另外，如果結果集合刈荺含二進制數據，你必須使用這個函數確定數據的大小，因為strlen()對包含空字符的任何字段返回不正確的結果。
空列和包含NULL的列的長度值是零。為了看清如何區分這兩種情況，見mysql_fetch_row()的說明。
表示每列大小的無符號長整數的一個數組(不包括任何終止空字符)。如果出現一個錯誤，NULL。
mysql_fetch_lengths()只對結果集合的當前行有效。如果你在調用mysql_fetch_row()之前或在檢索出在結果中的所有以後，它返回NULL。
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]);
}
}
mysql_fetch_row()MYSQL_ROW mysql_fetch_row(MYSQL_RES *result)
檢索一個結果集合的下一行。當在mysql_store_result()之後使用時，如果沒有更多的行可見所時，mysql_fetch_row()返回NULL。當在mysql_use_result()之後使用時，當沒有更多的行可檢索時或如果出現一個錯誤，mysql_fetch_row()返回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﹔否則字段是空的。
下一行的一個MYSQL_ROW結構。如果沒有更多的行可檢索或如果出現一個錯誤，NULL。
CR_SERVER_LOST CR_UNKNOWN_ERROR 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");
}
mysql_field_count()unsigned int mysql_field_count(MYSQL *mysql)
如果你正在使用一個比3.22.24早MySQL版本，你應該使用unsigned
int mysql_num_fields(MYSQL *mysql)。
返回在連接上的最近查詢的列的數量。
這個函數一般用在mysql_store_result()返回NULL時（這樣你沒有結果設置指針)。在這種情況中，你能調用mysql_field_count()確定mysql_store_result()是否應該產生了一個非空的結果。這允許一個客戶程式執行正確的操作，而不必知道查詢是否是一條SELECT（或類SELECT)語句。下面顯示的例子說明這怎樣可以做到。
見20.4.51 為什麼在mysql_query()返回成功後，mysql_store_result()有時返回NULL?。
在結果集合中表示字段數量字的一個無符號整數。
無。
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_errno(&mysql)代替mysql_field_count(&mysql)調用。在這種情況中，你直接檢查來自mysql_store_result()的一個錯誤而非從mysql_field_count()值來推斷語句是否是一個SELECT。
mysql_field_seek()MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES *result, MYSQL_FIELD_OFFSET offset)
將字段光標設置到給定的偏移量。下一次調用mysql_fetch_field()將檢索與該偏移量關聯的列的字段定義。
為了定位於行的起始，傳遞一個值為0的offset值。
字段光標的先前的值。
無。
mysql_field_tell()MYSQL_FIELD_OFFSET mysql_field_tell(MYSQL_RES *result)
返回用於最後一個mysql_fetch_field()的字段光標的位置。這個值可用作mysql_field_seek()的一個參數。
字段光標的當前偏移量。
無。
mysql_free_result()void mysql_free_result(MYSQL_RES *result)
釋放由mysql_store_result()、mysql_use_result()、mysql_list_dbs()等為一個結果集合分配的內存。當你用完了一個結果集合時，你必須調用mysql_free_result()來釋放它使用的內存。
無。
無。
mysql_get_client_info()char *mysql_get_client_info(void)
返回代表客戶庫的版本的字符串。
代表MySQL客戶庫版本的一個字符串。
無。
mysql_get_host_info()char *mysql_get_host_info(MYSQL *mysql)
返回描述正在使用的連接類型的字符串，包括服務其主機名。
表示伺服器主機名者和連接類型的字符串。
無。
mysql_get_proto_info()unsigned int mysql_get_proto_info(MYSQL *mysql)
返回當前連接使用的協議版本。
表示被當前連接使用的協議版本的一個無符號整數。
無。
mysql_get_server_info()char *mysql_get_server_info(MYSQL *mysql)
返回表示伺服器版本號的字符串。
表示伺服器版本號的一個字符串。
無。
mysql_info()char *mysql_info(MYSQL *mysql)
檢索一個字符串，它提供有關最近執行的查詢的資訊，但是對下面列出的語句。對其他語句，mysql_info()返回NULL。字符串的格式隨查詢類型而變化，如下所述。數字僅僅是說明性的﹔字符串將包含對查詢適當的值。
INSERT INTO ... SELECT ... Records: 100 Duplicates: 0 Warnings: 0 INSERT INTO ... VALUES (...),(...),(...)... Records: 3 Duplicates: 0 Warnings: 0 LOAD DATA INFILE ... Records: 1 Deleted: 0 Skipped: 0 Warnings: 0 ALTER TABLE Records: 3 Duplicates: 0 Warnings: 0 UPDATE Rows matched: 40 Changed: 40 Warnings: 0 注意，只有多個值在語句中指定，mysql_info()對INSERT
... VALUES語句才返回非NULL值。
表示最近執行的查詢的附加資訊的一個字符串。如果得不到查詢的任何資訊，NULL。
無。
mysql_init()MYSQL *mysql_init(MYSQL *mysql)
分配或初始化適合mysql_real_connect()的一個MYSQL對像。如果mysql是一個NULL指針，函數分配、初始化並且返回一個新對像。否則對像被初始化並且返回對像的地址。如果mysql_init()分配一個新對像，它將在調用mysql_close()關閉連接時被釋放。
一個被初始化的MYSQL*句柄。如果沒有足夠的內存來分配一個新對像，NULL。
在內存不夠的情況下，返回NULL。
mysql_insert_id()my_ulonglong mysql_insert_id(MYSQL *mysql)
返回由先前的查詢為一個AUTO_INCREMENT列產生的ID。在你執行一個INSERT查詢向一個包含AUTO_INCREMENT字段的表中插入後，使用這個函數。
注意，如果先前的查詢不產生一個AUTO_INCREMENT值，mysql_insert_id()返回0。如果你需要在以後保存該值，必須在查詢產生了該值後馬上調用mysql_insert_id()。
也要注意，SQL的LAST_INSERT_ID()函數總是包含最近產生的AUTO_INCREMENT值，並且在查詢之間不被重置，因為該函數的值在伺服器端維護。
有先前的查詢更新的AUTO_INCREMENT字段的值。如果在連接上沒有先前的詢問或如果查詢沒更新AUTO_INCREMENT值，返回零。
無。
mysql_kill()int mysql_kill(MYSQL *mysql, unsigned long pid)
要求伺服器殺死由pid指定的執行緒。
成功，零。如果出現一個錯誤，非零。
CR_COMMANDS_OUT_OF_SYNC CR_SERVER_GONE_ERROR CR_SERVER_LOST CR_UNKNOWN_ERROR
mysql_list_dbs()MYSQL_RES *mysql_list_dbs(MYSQL *mysql, const char *wild)
返回一個結果集合，它用在伺服器上的匹配wild參數指定的簡單正則表達式的資料庫名組成。wild可以包含通配符字符“%”或“_”，或可以是匹配所有的資料庫的一個NULL指針。調用mysql_list_dbs()類似於執行查詢SHOW
databases [LIKE wild]。
你必須用mysql_free_result()釋放結果集合。
成功，一個MYSQL_RES結果集合。如果出現一個錯誤，NULL。
CR_COMMANDS_OUT_OF_SYNC CR_OUT_OF_MEMORY CR_SERVER_GONE_ERROR CR_SERVER_LOST CR_UNKNOWN_ERROR
mysql_list_fields()MYSQL_RES *mysql_list_fields(MYSQL *mysql, const char *table, const char *wild)
返回一個結果集合，它用在給定表中的匹配wild參數指定的簡單正則表達式的列名組成。wild可以包含通配符字符“%”或“_”，或可以是匹配所有列的一個NULL指針。調用mysql_list_fields()類似於執行查詢SHOW
COLUMNS FROM tbl_name [LIKE wild]。
注意，建議你使用SHOW COLUMNS FROM tbl_name而不是mysql_list_fields()。
你必須用mysql_free_result()釋放結果集合。
成功，一個MYSQL_RES的結果集合。如果出線一個錯誤，NULL。
CR_COMMANDS_OUT_OF_SYNC CR_SERVER_GONE_ERROR CR_SERVER_LOST CR_UNKNOWN_ERROR
mysql_list_processes()MYSQL_RES *mysql_list_processes(MYSQL *mysql)
返回一個描述當前伺服器執行緒的結果集合。這是與mysqladmin
processlist或SHOW PROCESSLIST查詢報告的相同資訊。
你必須用mysql_free_result()釋放結果集合。
成功，一個MYSQL_RES結果集合。如果發生一個錯誤，NULL。
CR_COMMANDS_OUT_OF_SYNC CR_SERVER_GONE_ERROR CR_SERVER_LOST CR_UNKNOWN_ERROR
mysql_list_tables()MYSQL_RES *mysql_list_tables(MYSQL *mysql, const char *wild)
返回一個結果集合，它用在當前資料庫中的匹配wild參數指定的簡單正則表達式的表名組成。wild可以包含通配符字符“%”或“_”，或可以是匹配所有表的一個NULL指針。調用mysql_list_tables()類似於執行詢問SHOW
tables [LIKE wild]。
你必須用mysql_free_result()釋放結果集合。
成功，一個MYSQL_RES結果集合。如果出現一個錯誤，NULL。
CR_COMMANDS_OUT_OF_SYNC CR_SERVER_GONE_ERROR CR_SERVER_LOST CR_UNKNOWN_ERROR
mysql_num_fields()unsigned int mysql_num_fields(MYSQL_RES *result)
或
unsigned int mysql_num_fields(MYSQL *mysql)
第二中形式在MySQL 3.22.24或更新版本上不能工作。為了傳遞一個MYSQL*
參數，你必須使用unsigned int mysql_field_count(MYSQL *mysql)。
在結果集合中返回列的數量。
注意，你也可以通過一個指向一個結果集合或一個連接句柄的指針獲得列的數量。如果mysql_store_result()或mysql_user_result()返回NULL，你將使用連接句柄（而這樣你沒有結果集合指針)。在這種情況下，你可以調用mysql_field_count()確定mysql_store_result()是否應該產生非空的結果。這允許客戶程式采取成正確的行動，不必知道查詢是否是一個SELECT（或類SELECT)語句。下面被顯示出的例子說明這怎麼可以被做。
見20.4.51 為什麼在mysql_query()返回成功後，mysql_store_result()有時返回NULL?。
表示一個結果集合中字段數量的一個無符號整數。
無。
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_field_count(&mysql)
= 0的一個檢查來代替mysql_errno(&mysql)。這只會發生在出錯了的情形。
mysql_num_rows()my_ulonglong mysql_num_rows(MYSQL_RES *result)
在結果集合中返回行的數量。
mysql_num_rows()的使用取決於你是否使用mysql_store_result()或mysql_use_result()返回一個結果集合。如果你使用mysql_store_result()，mysql_num_rows()可以馬上被調用。如果你使用mysql_use_result()，mysql_num_rows()將不會返回正確的值，直到在結果集合中的所有行均被檢索了。
在結果集合中行的數量。
無。
mysql_options()int mysql_options(MYSQL *mysql, enum mysql_option option, const char *arg)
能用於設置額外連接選項並且影響一個連接的行為。這個函數可以被多次調用來設置多個選項。
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 |
告訴mysql_info()返回找到的行，而不是在使用UPDATE時，返回更新的行。
|
socket |
內定套接字號 |
timeout |
以秒計的連接超時。 |
user |
內定用戶 |
對於選項文件的更多資訊，見4.15.4 選項文件。
成功，零。如果你使用了未知的選項，非零。
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小節讀取額外的選項。
mysql_ping()int mysql_ping(MYSQL *mysql)
檢查到伺服器的連接是否正在工作。如果它關閉了，自動嘗試一個再連接。
這個函數可被已經空閑很長時間的客戶使用，來檢查伺服器是否關閉了連接並且如有必要重新連接。
如果伺服器活著，零。如果出現一個錯誤，非零。
CR_COMMANDS_OUT_OF_SYNC CR_SERVER_GONE_ERROR CR_UNKNOWN_ERROR
mysql_query()int mysql_query(MYSQL *mysql, const char *query)
執行指向空終止的字符串query的SQL查詢，查詢必須由一個單個的SQL語句組成。你不應該在語句後加上一個終止的分號(“﹔”)或\g。
mysql_query()不能被用於包含二進制數據的查詢﹔相反你應該使用mysql_real_query()。（二進制數據可能包含“\0”字符，而mysql_query()將解釋為查詢字符串的結束。）
如果查詢成功，零。如果出現一個錯誤，非零。
CR_COMMANDS_OUT_OF_SYNC CR_SERVER_GONE_ERROR CR_SERVER_LOST CR_UNKNOWN_ERROR
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)
mysql_real_connect()試圖建立到運行host的一個MySQL資料庫引擎的一個連接。
mysql_real_connect()在你可以執行任何其他API函數之前必須成功地完成，除了mysql_get_client_info()。
參數指定如下：
MYSQL結構的地址。在調用mysql_real_connect()之前，你必須調用mysql_init()初始化MYSQL結構。見下面的例子。
host值可以是一個主機名或一個IP地址。如果host是NULL或字符串"localhost"，假定是到本地主機的一個連接。如果OS支援套接字(Unix)或命名管道(Win32)，使用他們而不是TCP/IP與伺服器連接。user參數包含用戶的MySQL登錄ID。如果user是NULL，假定是當前用戶。在Unix下，它是當前登錄名。在Windows
ODBC下，必須明確地指定當前用戶名字。見16.4 怎樣填寫ODBC管理程式中各種域。
passwd參數為user包含密碼。如果passwd是NULL，只有在user表中對於有一個空白密碼字段的用戶的條目將被檢查一個匹配。這允許資料庫主管設置MySQL權限，使用戶獲得不同的密碼，取決於他們是否已經指定一個密碼。注意：不要試圖在調用mysql_real_connect()前加密密碼﹔密碼加密自動被客戶API處理。db是資料庫名。如果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*連接句柄。如果連接失敗，NULL。對一個成功的連接，返回值與第一個參數值相同，除非你傳遞NULL給該參數。
CR_CONN_HOST_ERROR CR_CONNECTION_ERROR CR_IPSOCK_ERROR CR_OUT_OF_MEMORY CR_SOCKET_CREATE_ERROR CR_UNKNOWN_HOST CR_VERSION_ERROR --old-protocol選項啟動的新伺服器，這就能發生。
CR_NAMEDPIPEOPEN_ERROR; CR_NAMEDPIPEWAIT_ERROR; CR_NAMEDPIPESETSTATE_ERROR; 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));
}
mysql_real_query()int mysql_real_query(MYSQL *mysql, const char *query, unsigned int length)
執行由query指向的SQL查詢，它應該是一個length個字節的字符串。查詢必須由一個單個的SQL語句組成。你不應該在語句後增加一個終止的分號(“;”)或\g。
對於包含二進制數據的查詢，你必須使用mysql_real_query()而不是mysql_query()，因為二進制代碼數據可能包含“\0”字符，而且，mysql_real_query()比mysql_query()更快，因為它對查詢字符串調用strlen()。
如果查詢成功，零。如果發生一個錯誤，非零。
CR_COMMANDS_OUT_OF_SYNC CR_SERVER_GONE_ERROR CR_SERVER_LOST CR_UNKNOWN_ERROR
mysql_reload()int mysql_reload(MYSQL *mysql)
要求MySQL伺服器再次裝載授權表。連接的用戶必須擁有reload權限。
不推薦這個函數。最好使用mysql_query()發出一條SQL
FLUSH PRIVILEGES語句。
成功，零。如果發生一個錯誤，非零。
CR_COMMANDS_OUT_OF_SYNC CR_SERVER_GONE_ERROR CR_SERVER_LOST CR_UNKNOWN_ERROR
mysql_row_seek()MYSQL_ROW_OFFSET mysql_row_seek(MYSQL_RES *result, MYSQL_ROW_OFFSET offset)
設置行光標為在結果集合中的任意行。這要求結果集合結構包含查詢的全部結果，這樣mysql_row_seek()只能與mysql_store_result()一起使用，而不與mysql_use_result()。
偏移量應該是調用mysql_row_tell()或mysql_row_seek()返回的值。這個值不是簡單地一個行號﹔如果你想要在結果集合內用行號來尋找行，使用mysql_data_seek()。
行光標先前的值。該值可以被傳遞給隨後的mysql_row_seek()調用。
無。
mysql_row_tell()MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES *result)
返回為了mysql_fetch_row()的行光標的當前位置。這個值可以作為一個參數用於mysql_row_seek()。
你應該僅在mysql_store_result()後使用mysql_row_tell()，而不是在mysql_use_result()後。
行光標當前的偏移量。
無。
mysql_select_db()int mysql_select_db(MYSQL *mysql, const char *db)
使得由db指定的資料庫成為 在由mysql指定的連接上的內定(當前)資料庫。在隨後的查詢中，這個資料庫對於不包括一個顯式的資料庫指定符的表的引用是內定資料庫。
除非連接的用戶能被認証允許使用資料庫，否則mysql_select_db()失敗。
成功，零。如果發生一個錯誤，非零。
CR_COMMANDS_OUT_OF_SYNC CR_SERVER_GONE_ERROR CR_SERVER_LOST CR_UNKNOWN_ERROR
mysql_shutdown()int mysql_shutdown(MYSQL *mysql)
讓資料庫伺服器關閉。連接的用戶必須有shutdown權限。
成功，零。如果出現一個錯誤，非零
CR_COMMANDS_OUT_OF_SYNC CR_SERVER_GONE_ERROR CR_SERVER_LOST CR_UNKNOWN_ERROR mysql_stat()char *mysql_stat(MYSQL *mysql)
返回包含類似於由mysqladmin status命令提供的資訊的一個字符串。它包括正常運行的秒數和正在運行執行緒、問題、再次裝載和打開的表的數目。
描述伺服器狀態的一個字符串。如果出現一個錯誤，NULL。
CR_COMMANDS_OUT_OF_SYNC CR_SERVER_GONE_ERROR CR_SERVER_LOST CR_UNKNOWN_ERROR
mysql_store_result()MYSQL_RES *mysql_store_result(MYSQL *mysql)
對於成功地檢索數據的每個詢問(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?。
一個保存結果的MYSQL_RES結構。如果出現一個錯誤，NULL。
CR_COMMANDS_OUT_OF_SYNC CR_OUT_OF_MEMORY CR_SERVER_GONE_ERROR CR_SERVER_LOST CR_UNKNOWN_ERROR
mysql_thread_id()unsigned long mysql_thread_id(MYSQL *mysql)
返回當前連接的執行緒ID。這個值可用作mysql_kill()的一個參數以殺死執行緒。
如果失去連接並且你用mysql_ping()重新連接，執行緒ID將改變。這意味著你不應該為以後使用獲得執行緒ID並且儲存它，當你需要它時，你應該獲得它。
當前連接的執行緒 ID 。
無。
mysql_use_result()MYSQL_RES *mysql_use_result(MYSQL *mysql)
對於成功地檢索數據的每個查詢(SELECT、SHOW、DESCRIBE、EXPLAIN)，你必須調用mysql_store_result()或mysql_use_result()。
mysql_use_result()初始化一個結果集合的檢索，但不真正將結果集合讀入客戶，就像mysql_store_result()那樣。相反，必須通過調用mysql_fetch_row()單獨檢索出每一行，這直接從伺服器讀出結果而不在一個臨時表或本地緩衝區中儲存它，它比mysql_store_result()更快一點並且使用較少的內存。客戶將只為當前行和一個可能最大max_allowed_packet字節的通信緩衝區分配內存。
在另一方面，如果你在客戶端對每一行正在做很多的處理，或如果輸出被送到屏幕，用戶可以打一個^S（停止滾動)，你不應該使用mysql_use_result()。這將阻塞伺服器並且阻止另外的執行緒從數據被取出的任何表中更新數據。
當使用mysql_use_result()時，你必須執行mysql_fetch_row()直到返回一個NULL值，否則未取出的行將作為下一個查詢的結果集合一部分被返回。如果你忘記做這個，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()。
一個MYSQL_RES結果結構。 如果發生一個錯誤發生，NULL。
CR_COMMANDS_OUT_OF_SYNC CR_OUT_OF_MEMORY CR_SERVER_GONE_ERROR CR_SERVER_LOST CR_UNKNOWN_ERROR mysql_query()返回成功後，mysql_store_result()有時返回NULL?有可能在一個對mysql_query()成功的調用後，mysql_store_result()返回NULL。當這發生時，它意味著出現了下列條件之一：
malloc()失敗(例如，如果結果集合太大)。 INSERT、UPDATE或DELETE)。
你總是可以通過調用mysql_field_count()檢查語句是否應該產生非空的結果。如果mysql_field_count()返回零，結果是空的並且最後一個查詢是不回值的一條語句(例如，一條INSERT或DELETE)。如果mysql_field_count()返回非零值，語句應該產生非空的結果。見對mysql_field_count()描述的一個例子。
你可以調用mysql_error()或mysql_errno()測試一個錯誤。
除了由查詢返回的結果集合外，你也能得到下列資訊：
INSERT、UPDATE或DELETE時，mysql_affected_rows()返回受到最後一個查詢影響的行數。一個例外是如果使用一條沒有WHERE子句的DELETE，表被截斷，它更快！在這種情況下，mysql_affected_rows()對於影響的記錄數量返回零。mysql_num_rows()返回結果集合中的行數。用mysql_store_result()，一旦mysql_store_result()返回，就可以調用mysql_num_rows()。用mysql_use_result()，只有在你已經用mysql_fetch_row()取出了所有行後，才能調用mysql_num_rows()。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指針。
如果你往包含一個具有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是在一個按連接的基礎上在伺服器上進行維護，它將不被其他客戶改變。如果你更新另外一個有非奇特(non-magic)值(即一個既不是NULL也不是0的值)的AUTO_INCREMENT列，它甚至將不被改變。
如果你想要使用為一張表產生的ID並且把它插入到第2張表，你可以使用像這樣的SQL語句：
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
當與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
如果它發生在你的系統上，你必須通過在編譯/鏈接命令行的最後增加-lm以包括數學庫。
客戶“幾乎”是執行緒安全的。最大的問題是在從套接字讀取的“net.c”中的子程式不是中斷安全的(interruot-safe)。這樣做是這樣考慮的，即你可能想有你自己的報警來中斷一個長時間的讀取伺服器。
標準客戶庫沒有用執行緒選項來編譯。
為了獲得一個執行緒安全的客戶，使用-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”庫現在是執行緒安全的。它的含義是只要2個執行緒不同時查詢mysql_real_connect()返回的同一個連接句柄，客戶代碼是執行緒安全的﹔客戶機/伺服器協議在一個給定的連接上一次只允許一個請求。如果你想在同一個的連接上使用多個執行緒，你必須在mysql_query()和mysql_store_result()調用組合附近有一個mutex鎖定。一旦mysql_store_result()就緒，鎖可以被釋放並且其他執行緒可以查詢同一個連接。（換句話說，不同的執行緒能使用不同被mysql_store_result()創建的MYSQL_RES指針，只要他們使用適當的鎖定協議)
如果你用POSIX執行緒編程，你能使用pthread_mutex_lock()和pthread_mutex_unlock()建立並且釋放一個mutex鎖定。
如果你使用mysql_use_result()而不是mysql_store_result()，鎖定將需要包圍mysql_use_result()和mysql_fetch_row()的調用，然而，它確實對不使用mysql_use_result()執行緒客戶是最好的。
本節記載了Perl DBI介面。以前的介面被稱為mysqlperl。因為DBI/DBD現在是推薦的Perl介面，mysqlperl是過時的並且不在這裡記載。
DBI與DBD::mysqlDBI是對於很多資料庫的一個通用介面。這意味著你能編寫一個腳本，不用改變就能工作於很多資料庫引擎。你需要為每種資料庫類型定義了的一個資料庫驅動程式(DBD)。對於MySQL，該驅動程式稱為DBD::mysql。
有關Perl5 DBI的更多資訊，請訪問DBI網頁並且閱讀文檔：
http://www.symbolstone.org/technology/perl/DBI/index.html
關於在Perl5定義的面向對像的編程(OOP)的更多資訊，參見Perl OOP頁：
http://language.perl.com/info/documentation.html
對於MySQL Perl支援的安裝指令在4.10 Perl安裝說明中給出。
DBI介面可移植的DBI方法
connect |
建立到一個資料庫伺服器的連接 |
disconnect |
斷開資料庫伺服器的連接 |
prepare |
準備執行一個SQL語句 |
execute |
執行準備好的語句 |
do |
準備並執行一個SQL語句 |
quote |
加引號於要插入的字符串或BLOB值 |
fetchrow_array |
作為一個字段數組取出下一行 |
fetchrow_arrayref |
作為一個字段的引用數組取出下一行 |
fetchrow_hashref |
作為一個哈希表的引用取出下一行 |
fetchall_arrayref |
作為一個字段數組取出所有數據 |
finish |
完成一條語句並且讓系統釋放資源 |
rows |
返回受影響的行數 |
data_sources |
返回可在localhost上得到的資料庫的數組 |
ChopBlanks |
控制fetchrow_*方法是否剝去空格 |
NUM_OF_PARAMS |
在準備的語句中的占位（placeholder-參數）的數目 |
NULLABLE |
其列可以是NULL |
trace |
執行調試跟蹤 |
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 |
所有的列類型 |
Perl方法在下一節更詳細地描述。用於方法返回值的變數有這些含義：
$dbh $sth $rc $rv 可移植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)。對Msql-Mysql-modules版本1.2009，$data_source值允許某些修飾詞：
mysql_read_default_file=file_name mysql_read_default_group=group_name [client]組。通過指定mysql_read_default_group選項，內定組變成[group_name]組。mysql_compression=1 mysql_socket=/path/to/socket 可以給出多個修飾詞﹔每一個必須前置一個分號。例如，如果你想要避免在一個DBI腳本中硬編碼用戶名和密碼，你可以從用戶的“~/.my.cnf”選項文件中取出它們，而不是這樣編寫你的connect調用：
$dbh = DBI->connect("DBI:mysql:$database"
. ";mysql_read_default_file=$ENV{HOME}/.my.cnf",
$user, $password);
這個調用將讀取在選項文件中為[client]組而定義的選項。如果你想做同樣的事情，但是也使用未[perl]組指定的選項，你可以使用：
$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) ($sth)，你可以使用它調用execute方法。一般地你借助於prepare和execute來處理SELECT語句(和類SELECT語句，例如SHOW、DESCRIBE和EXPLAIN)。範例：$sth = $dbh->prepare($statement)
or die "Can't prepare $statement: $dbh->errstr\n";
execute execute方法執行一個準備好的語句。對非SELECT語句，execute返回受影響的行數。如果沒有行受影響，execute返回"0E0"，Perl將它視作零而不是真。對於SELECT語句，execute只是在資料庫中啟動SQL查詢﹔你需要使用在下面描述的fetch_*方法之一檢索數據。範例：$rv = $sth->execute
or die "can't execute the query: $sth->errstr;
do($statement) do方法準備並且執行一條SQL語句並且返回受影響的行數。如果沒有行受到影響，do返回"0E0"，Perl將它視為零而不是真。這個方法通常用於事先無法準備好(由於驅動程式的限制)或不需要執行多次(插入、刪除等等)的非SELECT語句。範例：$rv = $dbh->do($statement)
or die "Can't execute $statement: $dbh- >errstr\n";
quote($string) quote方法被用來“轉義”包含在string中的任何特殊字符並增加所需的外部的引號。範例：$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 while($hash_ref = $sth->fetchrow_hashref) {
print qw($hash_ref->{firstname}\t$hash_ref->{lastname}\t\
$hash_ref- > title}\n);
}
fetchall_arrayref 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 SELECT的execute語句之後。範例：$rv = $sth->rows;
NULLABLE NULL值。範例：$null_possible = $sth->{NULLABLE};
NUM_OF_FIELDS SELECT或SHOW FIELDS語句返回的字段數目。你可以用它檢查一條語句是否返回了結果：一個零值表明一個像INSERT、DELETE或UPDATE的非SELECT語句。範例：$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) trace方法開啟或關閉跟蹤。當作為一個DBI類方法調用時，它影響對所有句柄的跟蹤。當作為一個資料庫或語句句柄方法調用時，它影響對給定句柄的跟蹤(和句柄的未來子孫)。設置$trace_level為2以提供詳細的蹤跡資訊，設置$trace_level為0以關閉跟蹤。蹤跡輸出內定地輸出到標準錯誤輸出。如果指定$trace_filename，文件以添加模式打開並且所有跟蹤的句柄的手被寫入該文件。範例：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
你也可以通過設置DBI_TRACE環境變數開啟DBI跟蹤。將它設置為等價於調用DBI->(value)的數字值，將它設置為等價於調用DBI->(2,value)的路徑名。
MySQL特定的方法
下面顯示的方法是MySQL特定的並且不是DBI標準的部分。他們中有幾個現在不建議使用：is_blob、is_key、is_num、is_pri_key、is_not_null、length、max_length和table。這些已有DBI標準的另一種方法存在，他們在下面說明。
insertid AUTO_INCREMENT功能，新的自動加1的值將儲存在這裡。範例：$new_id = $sth->{insertid};
is_blob BLOB。範例：
$keys = $sth->{is_blob};
is_key $keys = $sth->{is_key};
is_num $keys = $sth->{is_key};
is_pri_key pri_keys = $sth->{is_pri_key};
is_not_null NULL值。範例：$not_nulls = $sth->{is_not_null};
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};
的DBI/DBD資訊你可以使用perldoc命令得到更多的關於DBI的資訊。
perldoc DBI perldoc DBI::FAQ perldoc DBD::mysql
你也可以使用pod2man、pod2html等工具轉換到其他格式。
而且你當然可以在DBI網頁中找到最新的DBI資訊：
http://www.symbolstone.org/technology/perl/DBI/index.html
MySQL Contrib目錄包含Michael Ravits編寫的一個Eiffel包裝程式。
你也能在這裡找到：http://www.netpedia.net/hosting/newplayer/
有2個為MySQL支援的JDBC驅動程式(twz和mm驅動程式)。你可以在http://www.mysql.com/Contrib找到這些的一個拷貝。對於文檔，請教任何JDBC文檔和驅動程式本身擁有的針對MySQL特定功能的文檔。
PHP是一個伺服器端、HTML嵌入式腳本語言，可以用來創建動態網頁。它包含對存取若干資料庫的支援，包括MySQL。PHP可以作為一個單獨的程式運行，或編譯為與Apache伺服器一起使用的一個模組。
分發和文檔可在PHP網站得到。
在MySQL Contrib 目錄刈莃得到兩個API。
MySQL Contrib 目錄包含Joseph Skinner編寫的一個Python介面。
你也可以使用對iODBC的Python介面來存取一個MySQL伺服器。mxODBC
TCL at binevolve。Contrib 目錄包含一個基於msqltcl 1.50的一個TCL介面。