MySQL C API

This is article is extracted from the MySQL 5.7 Reference Manual.

The MySQL C API is a C-based API that client applications written in C can use to communicate with MySQL Server. Client programs refer to C API header files at compile time and link to a C API library file at link time. The library comes in two versions, depending on how the applicaton is intended to communicate with the server:

• libmysqlclient

  : The client version of the library, used for applications that communicate over a network connection as a client of a standalone server process.

• libmysqld

  : The embedded server version of the library, used for applications intended to include an embedded MySQL server within the application itself. The application communicates with its own private server instance.

Both libraries have the same interface. In terms of C API calls, an application communicates with a standalone server the same way it communicates with an embedded server. A given client can be built to communicate with a standalone or embedded server, depending on whether it is linked against

libmysqlclient

or

libmysqld

at build time.

C API Function Descriptions

MYSQL_RES *mysql_use_result(MYSQL *mysql)

Description

After invoking

mysql_query()

or

mysql_real_query()

, you must call

mysql_store_result

or

mysql_use_result()

for every statement that successfully produces a result set (

SELECT

,

SHOW

,

DESCRIBE

,

EXPLAIN

,

CHECK TABLE

, and so forth). You must also call

mysql_free_result()

after you are done with the result set.

mysql_use_result()

intiates a result set retrieval but does not actually read the result set into the client like

mysql_store_result()

does. Instead, each row must be retrieved individually by making calls to

mysql_fetch_row()

. This reads the result of a query directly from the server with storing it in a temporary table or local buffer, which is somewhat faster and uses much less memory than

mysql_store_result()

. The client allocates memory only for the current row and a communication buffer* that may grow up to

max_allowed_packet

bytes.

On the other hand, you should not use

mysql_use_result()

for locking reads if you are doing a lot of processing for each row on the client side, or if the output is sent to a screen on which the user may type a

^S

(stop scroll). This ties up the server and prevent other threads from updating any tables from which the data is being fetched.

When using

mysql_use_result()

, you must execute

mysql_fetch_row()

until a

NULL

value is returned, otherwise, the unfetched rows are returned as part of the result set for your next query. The C API gives the error

Commands out of sync; you can't run this command now

if you forget to do this!

You may not use

mysql_data_seek()

,

mysql_row_seek()

,

mysql_row_tell()

,

mysql_num_rows()

, or

mysql_affected_rows()

with a result returned from

mysql_use_result()

, nor may you issue other queries until

mysql_use_result()

has finished. (However, after you have fetched all the rows,

mysql_num_rows()

accurately returns the number of rows fetched.)

You must call

mysql_free_result()

once you are done with the result set.

When using the

libmysqld

embedded server, the memory benefits are essentially lost because memory usage incrementally increases with each row retrieved until

mysql_free_result()

is called.