C中Mysql的基本api接口

一、初始化

创建MYSQL* 对象，使用mysql_init函数

MYSQL * mysql;
mysql_init(mysql);

参数

• mysql：指向一个 MYSQL 结构的指针。通常传递 NULL，系统将自动为您分配和初始化一个新的 MYSQL 对象。

返回值

• 成功：返回一个指向 MYSQL 结构的指针。
• 失败：返回 NULL。

二、链接服务器

使用函数mysql_real_connect（）；

MYSQL *mysql_real_connect(
    MYSQL *mysql,           // mysql_init() 函数的返回值
    const char *host,       // mysql服务器的主机地址, 写IP地址即可
                            // localhost, null -> 代表本地连接
    const char *user,       // 连接mysql服务器的用户名, 默认: root 
    const char *passwd,     // 连接mysql服务器用户对应的密码, root用户的密码
    const char *db,         // 要使用的数据库的名字
    unsigned int port,      // 连接的mysql服务器监听的端口
                            // 如果==0, 使用mysql的默认端口3306, !=0, 使用指定的这个端口
    const char *unix_socket,// 本地套接字, 通常在 Windows 上使用命名管道，而在 Unix/Linux 系统上使用 Unix 套接字。如果不使用这类连接方式，此参数应设为 NULL。
    unsigned long client_flag); //连接时使用的特定客户端标志 通常指定为0
）

返回值:

• 成功：返回一个指向 MYSQL 结构的指针（通常是传入的那个指针）。
• 失败：返回 NULL，并且可以通过 mysql_error 函数来获取错误信息。

三、执行SQL语句

// 执行一个sql语句, 添删查改的sql语句都可以
int mysql_query(MYSQL *mysql, const char *query);
参数:
    - mysql: mysql_real_connect() 的返回值
    - query: 一个可以执行的sql语句, 结尾的位置不需要加 ;
返回值: 
    - 如果查询成功，返回0。如果是查询, 结果集在mysql 对象中
    - 如果出现错误，返回非0值。 

注意事项

1. 资源管理：使用 mysql_query 后，如果查询是 SELECT 类型的，你通常需要调用 mysql_store_result 或 mysql_use_result 来处理返回的数据。记得在不需要结果集时使用 mysql_free_result 来释放内存。
2. 错误处理：在生产环境中，每次调用 mysql_query 后都应检查返回值，并适当处理错误。这样可以避免程序在错误状态下继续执行，导致更复杂的问题。
3. 安全性：避免将未经验证的用户输入直接用于 SQL 语句，以防止 SQL 注入攻击。考虑使用预处理语句和参数化查询来提高安全性。

这些基本的使用方式和注意事项可以帮助你有效地使用 mysql_query 来执行数据库操作。

值得注意的是在 MySQL 中，SQL 语句的关键字（如 SELECT, INSERT, UPDATE, DELETE 等）通常是不区分大小写的，这意味着 “select” 和 “SELECT” 在 MySQL 解释器看来是相同的。然而，数据库名称、表名、列名的大小写敏感性则取决于操作系统的文件系统和 MySQL 的配置。在 Unix、Linux 系统中，它们默认是大小写敏感的，而在 Windows 系统中默认是不敏感的。

mysql_query 实质上是在客户端和 MySQL 服务器之间进行网络通信的一个接口。在使用 TCP/IP 协议的情况下，客户端通过网络向服务器发送请求，并接收服务器的响应。这个过程涉及到网络数据的发送和接收，是基于客户端-服务器模型的典型应用。

要注意的是标准 SQL 查询：如果你的查询是简单的文本，不包含二进制数据，且不需要在 SQL 语句中嵌入 null 字符，使用 mysql_query 就足够了。

而当数据中有二进制数据就需要使用mysql_real_query

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

• 灵活性：可以执行包含 null 字符的查询，因为它要求用户明确提供查询的长度。
• 手动指定长度：用户必须指定查询字符串的长度，这允许函数处理二进制数据或包含 null 字符的数据。
• 适用场景：非常适合执行包含 BLOB 类型数据的 SQL 语句。

四、获取结果集

4.1mysql_affected_rows和mysql_num_rows

uint64_t mysql_affected_rows(MYSQL *mysql)

mysql_affected_rows（） 可能是 在使用 mysql_real_query（） 或 mysql_query（） 执行语句后立即调用。它返回 上一个更改、删除或插入的行数 语句（如果是 UPDATE、DELETE 或 INSERT）。对于 SELECT 语mysql_affected_rows（） 有效 像 mysql_num_rows（）。

对于 UPDATE 语句， 默认情况下，affected-rows 值是实际的行数 改变。如果在以下情况下指定 mysql_real_connect（） 的标志 连接到 mysqld，受影响的行 value 是“找到”的行数;那是 与子句匹配。CLIENT_FOUND_ROWSWHERE

对于 REPLACE 语句， 如果新行替换了旧行，则 affected-rows 值为 2， 因为在这种情况下，在重复项之后插入了一行 已删除。

uint64_t mysql_num_rows(MYSQL_RES *result)

返回结果集中的行数。

4.2mysql_store_result与mysql_free_result

MYSQL_RES *mysql_store_result(MYSQL *mysql);
参数说明
mysql: 指向 MYSQL 结构的指针，该结构体应已通过 mysql_real_connect 函数建立了与 MySQL 服务器的连接，并已成功执行了一个查询（如通过 mysql_query）。
返回值
成功: 返回一个指向 MYSQL_RES 结构的指针，这个结构包含了从服务器返回的所有结果数据。
失败 或 查询没有产生结果集（例如执行的是 UPDATE 或 DELETE 语句）: 返回 NULL。
如何将行和列的数据从结果集中取出, 需要使用其他函数

注：mysql_store_result 函数只会返回与最近一次通过 mysql_query （或其他发送 SQL 语句的函数）执行的查询相关的结果。它不会存储或回溯到之前的查询结果，而是专注于最后执行的查询。

注意事项

1. 内存管理：使用 mysql_store_result 后，必须在不再需要结果集时调用 mysql_free_result 来释放内存。
2. 性能考量：由于 mysql_store_result 会将所有结果数据存储在客户端内存中，对于返回大量数据的查询，这可能会消耗大量内存和网络资源。如果处理大型数据集，可能需要考虑使用 mysql_use_result，该函数允许逐行检索数据，从而减少内存占用。
3. 错误处理：始终检查 mysql_store_result 的返回值，并使用 mysql_error 函数来诊断错误。

通过 mysql_store_result，你可以方便地在客户端处理来自 MySQL 服务器的数据，但务必注意资源管理和错误处理，以确保应用程序的稳定性和效率。

void mysql_free_result(MYSQL_RES *result);
参数说明
result: 指向 MYSQL_RES 结构的指针，该结构包含了之前查询的结果集。

mysql_free_result 函数是 MySQL C API 中用来释放由 mysql_store_result 或 mysql_use_result 函数分配的结果集内存的函数。这是清理和资源管理的重要一步，确保在查询处理完成后不会造成内存泄漏。

当使用 mysql_store_result 或 mysql_use_result 从 MySQL 服务器获取查询结果后，相关的数据会被存储在 MYSQL_RES 结构中。这个结构占用一定的内存空间，当数据处理完毕后，应该使用 mysql_free_result 来释放这些内存。如果不这样做，每次查询后未释放的内存会累积，最终可能导致内存不足或程序崩溃。

实际使用

#include <mysql.h>
#include <iostream>

int main() {
    MYSQL *conn;
    MYSQL_RES *res;
    MYSQL_ROW row;

    conn = mysql_init(NULL);
    if (!conn) {
        std::cerr << "MySQL initialization failed." << std::endl;
        return 1;
    }

    if (!mysql_real_connect(conn, "localhost", "user", "password", "database", 0, NULL, 0)) {
        std::cerr << "Failed to connect to database: " << mysql_error(conn) << std::endl;
        mysql_close(conn);
        return 1;
    }

    if (mysql_query(conn, "SELECT id, name FROM users")) {
        std::cerr << "Query failed: " << mysql_error(conn) << std::endl;
        mysql_close(conn);
        return 1;
    }

    res = mysql_store_result(conn);
    if (!res) {
        std::cerr << "Failed to retrieve result set: " << mysql_error(conn) << std::endl;
        mysql_close(conn);
        return 1;
    }

    while ((row = mysql_fetch_row(res))) {
        std::cout << "ID: " << row[0] << ", Name: " << row[1] << std::endl;
    }

    // After processing the results, free the memory.
    mysql_free_result(res);

    mysql_close(conn);
    return 0;
}

注意事项

1. 只释放一次：确保对每个 MYSQL_RES 结构只调用一次 mysql_free_result。重复释放可能会导致未定义行为或程序崩溃。
2. 适时释放：尽可能在数据处理完毕后立即释放结果集，特别是在处理多个查询的情况下，避免不必要的内存占用。
3. 检查 NULL：如果 mysql_store_result 或 mysql_use_result 返回 NULL，表明没有结果集需要处理，因此不应该调用 mysql_free_result

整体的工作流程

1. 执行查询：首先使用 mysql_query 执行一个 SQL 查询。
2. 检索结果：使用 mysql_store_result 检索查询结果并存储在 MYSQL_RES * 结构中。
3. 处理数据：通过循环等方式处理这些结果。
4. 释放资源：使用 mysql_free_result 释放 MYSQL_RES * 结构占用的内存。
5. 重复操作：如果需要再次查询，回到第一步，执行新的 mysql_query，然后使用 mysql_store_result 检索新的结果。

值得注意的是如果你在调用 mysql_store_result 之后没有使用 mysql_free_result 来释放结果集的内存，然后再次进行查询并调用 mysql_store_result，这将导致内存泄漏。这是因为每次调用 mysql_store_result 都会从 MySQL 服务器获取新的结果数据，并在客户端为这些数据分配新的内存。如果旧的结果集没有被适当释放，那么这部分内存仍然被占用，尽管你已经无法再访问到这部分数据。

4.3mysql_use_result（）

MYSQL_RES *mysql_use_result(MYSQL *mysql)
参数说明
mysql: 指向 MYSQL 结构的指针，该结构表示一个已连接的 MySQL 数据库。
返回值
成功：返回一个指向 MYSQL_RES 结构的指针，该结构代表结果集。
失败：返回 NULL，并且可以通过 mysql_error 函数获取错误信息。

while ((row = mysql_fetch_row(res))) {
        std::cout << "ID: " << row[0] << ", Name: " << row[1] << std::endl;
}

1. 逐行处理：mysql_use_result 逐行读取结果集，这意味着你不能在获取完整结果集之前执行其他查询，否则会导致未定义行为。
2. 资源释放：使用 mysql_use_result 后，一定要调用 mysql_free_result 释放结果集，确保内存资源被适当管理。
3. 网络延迟：因为 mysql_use_result 逐行读取数据，受网络延迟的影响可能会比 mysql_store_result 慢，但对于大结果集它能显著降低内存占用。

mysql_use_result 与 mysql_store_result 都是用来处理查询结果集的函数，但它们在处理方式上有以下区别：

• mysql_store_result：一次性将整个结果集从服务器读取到客户端内存中，适用于结果集较小的情况，因为它会在客户端占用较多内存。
• mysql_use_result：逐行从服务器读取结果集，适用于结果集较大的情况，因为它不会将整个结果集一次性加载到内存中，节省了内存占用。

4.4mysql_field_count（）

在第三部分我们看到mysql_query不仅可以使用SELECT SQL语句还可以使用INSERT语句，我们对于查询语句的列数和是否是查询语句是有一定的判断需求的

unsigned int mysql_field_count(MYSQL *mysql)

• 返回一个 unsigned int 值，表示最近执行的查询返回的列数。如果没有活动的查询或查询没有返回任何结果，则返回 0。

注意事项

1. 正确的上下文：mysql_field_count 应该在成功执行查询之后调用，以确保它返回正确的列数。如果在没有活动查询的情况下调用它，返回值将是 0。
2. 结果集处理：当你使用 mysql_store_result 或 mysql_use_result 来获取结果集时，使用 mysql_field_count 可以帮助你动态地处理结果集中的数据。
3. 查询类型：对于不返回结果集的查询（如 INSERT、UPDATE、DELETE），mysql_field_count 返回 0。

五、关闭MySQL

void mysql_close(MYSQL *mysql)

当你完成了数据库操作并不再需要与数据库的连接时，应该调用 mysql_close 来关闭连接。这个调用确保所有的客户端资源被适当清理，包括内部缓冲区和连接句柄。如果不关闭连接，可能会导致资源泄漏。

void mysql_library_end(void);

在所有数据库连接都已通过 mysql_close 关闭后，应调用 mysql_library_end 来清理 MySQL 客户端库使用的所有资源。这个函数主要用于多线程环境中，在所有线程都完成数据库操作并关闭连接后，由主线程调用以确保所有的客户端库资源被正确释放。

使用和区别

使用场景：mysql_close 用于关闭单个数据库连接；mysql_library_end 用于在程序结束前清理客户端库。 调用时机： mysql_close：每个数据库连接在不再需要时应该被关闭。 mysql_library_end：在程序结束，所有数据库连接都已关闭后调用。

值得注意的是即使在单线程应用程序中，依然推荐在程序结束时调用 mysql_library_end。这个函数的作用不仅限于多线程环境，它负责清理 MySQL 客户端库使用的全局资源，确保所有初始化时分配的资源被适当释放，这包括内部数据结构、缓冲区等。

六、错误处理

mysql_errno()和mysql_error()

mysql_errno() 返回最近一次 MySQL 函数调用所产生的错误代码。这个错误代码是一个整数值，表示特定类型的错误。

unsigned int mysql_errno(MYSQL *mysql);
返回一个 `unsigned int` 类型的错误代码。如果没有错误发生，返回值为 `0`。

mysql_error() 返回最近一次 MySQL 函数调用所产生的错误信息字符串。这个字符串描述了具体的错误情况，通常比错误代码更易读和理解。

const char *mysql_error(MYSQL *mysql);
返回一个指向描述错误的字符串的指针。如果没有错误发生，返回一个空字符串。

通过使用 mysql_errno() 和 mysql_error()，你可以更详细地了解数据库操作中的错误，帮助调试和改进程序的错误处理能力。这两个函数在处理复杂数据库交互时尤为重要，因为它们可以提供具体的错误信息和错误代码，有助于定位和解决问题。