21.8 MySQL C API

21.8.1 MySQL C API Implementations
21.8.2 Simultaneous MySQL Server and MySQL Connector/C Installations
21.8.3 Example C API Client Programs
21.8.4 Building and Running C API Client Programs
21.8.5 C API Data Structures
21.8.6 C API Function Overview
21.8.7 C API Function Descriptions
21.8.8 C API Prepared Statements
21.8.9 C API Prepared Statement Data Structures
21.8.10 C API Prepared Statement Function Overview
21.8.11 C API Prepared Statement Function Descriptions
21.8.12 C API Threaded Function Descriptions
21.8.13 C API Embedded Server Function Descriptions
21.8.14 Common Questions and Problems When Using the C API
21.8.15 Controlling Automatic Reconnection Behavior
21.8.16 C API Support for Multiple Statement Execution
21.8.17 C API Prepared Statement Problems
21.8.18 C API Prepared Statement Handling of Date and Time Values
21.8.19 C API Support for Prepared CALL Statements

The C API provides low-level access to the MySQL client/server protocol and enables C programs to access database contents. The C API code is distributed with MySQL and implemented in the libmysqlclient library. See Section 21.8.1, “MySQL C API Implementations”.

Most other client APIs use the libmysqlclient library to communicate with the MySQL server. (Exceptions are except Connector/J and Connector/Net.) This means that, for example, you can take advantage of many of the same environment variables that are used by other client programs because they are referenced from the library. For a list of these variables, see Section 4.1, “Overview of MySQL Programs”.

For instructions on building client programs using the C API, see Section 21.8.4.1, “Building C API Client Programs”. For programming with threads, see Section 21.8.4.2, “Writing C API Threaded Client Programs”. To create a standalone application which includes the "server" and "client" in the same program (and does not communicate with an external MySQL server), see Section 21.7, “libmysqld, the Embedded MySQL Server Library”.

Note

If, after an upgrade, you experience problems with compiled client programs, such as Commands out of sync or unexpected core dumps, the programs were probably compiled using old header or library files. In this case, check the date of the mysql.h file and libmysqlclient.a library used for compilation to verify that they are from the new MySQL distribution. If not, recompile the programs with the new headers and libraries. Recompilation might also be necessary for programs compiled against the shared client library if the library major version number has changed (for example, from libmysqlclient.so.17 to libmysqlclient.so.18). For additional compatibility information, see Section 21.8.4.3, “Running C API Client Programs”.

Clients have a maximum communication buffer size. The size of the buffer that is allocated initially (16KB) is automatically increased up to the maximum size (16MB by default). Because buffer sizes are increased only as demand warrants, simply increasing the maximum limit does not in itself cause more resources to be used. This size check is mostly a precaution against erroneous statements and communication packets.

The communication buffer must be large enough to contain a single SQL statement (for client-to-server traffic) and one row of returned data (for server-to-client traffic). Each session's communication buffer is dynamically enlarged to handle any query or row up to the maximum limit. For example, if you have BLOB values that contain up to 16MB of data, you must have a communication buffer limit of at least 16MB (in both server and client). The default maximum built into the client library is 1GB, but the default maximum in the server is 1MB. You can increase this by changing the value of the max_allowed_packet parameter at server startup. See Section 8.9.2, “Tuning Server Parameters”.

The MySQL server shrinks each communication buffer to net_buffer_length bytes after each query. For clients, the size of the buffer associated with a connection is not decreased until the connection is closed, at which time client memory is reclaimed.