【在线五子棋对战】四、MySQL API 使用

Ⅰ. 连接数据库的步骤

​ 众所周知，MySQL 数据库是一个典型的 C/S 结构，即：客户端和服务器端。如果我们部署好了 MySQL 服务器，想要在客户端访问服务器端的数据，在编写程序的时候就可以通过官方提供的 C 语言的 API 来实现，因为我们总不能说在程序中开个子进程去使用 SQL 语句是吧，所以直接通过 API 来调用是最省事的！

​ 在程序中连接 MySQL 服务器，主要分为已经几个步骤：

• 客户端初始化过程：
  1. 初始化 mysql 操作句柄
  2. 连接 mysql 服务器，要提供如下连接数据:
     • 服务器的 IP 地址
     • 服务器监听的端口（默认端口是 3306）
     • 连接服务器使用的用户名（默认是 root），和这个用户对应的密码
     • 要操作的数据库的名字
  3. 设置客户端的字符集
  4. 选择想要的操作的数据库
• 客户端对数据库中数据的操作：
  1. 新增、修改、删除操作：这三个操作都是只要 sql 语句执行成功了，数据库中的数据就发生了改变，不需要反馈结果。
     • 需要对执行的结果进行判断
       • 成功：提交事务
       • 失败：数据回滚
  2. 查询操作：这个操作就不一样了，因为需要首先执行 sql 语句成功，此时查询结果还是服务器上面，我们 要将查询结果保存到本地上进行访问
     • 获取查询结果集中的结果条数
     • 遍历获取结果集 -> 得到了要查询的数据
     • 释放结果集（结果集是动态开辟的，要释放，不然会内存泄露）
• 释放 mysql 操作句柄

Ⅱ. MySQL API介绍

​ 对于以上的操作步骤，在 MySQL 提供的 API 中都有对应的操作函数。

需要的头文件：

#include <mysql/mysql.h>

以上 API 对应的 MySQL 动态库：

• Windows：libmysql.dll

• Linux：libmysqlclient.so

初始化连接环境

// 参数 mysql -> null
// 返回值: 该函数将分配、初始化、并返回新对象
// 			通过返回的这个对象去连接MySQL的服务器
MYSQL *mysql_init(MYSQL *mysql) ;

连接 mysql 服务器

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的默认端口3306const char *unix_socket,	// 本地套接字, 不使用指定为 NULLunsigned long client_flag	// 客户端标志位，通常指定为0
); 
/*
返回值: 成功：返回 MYSQL*连接句柄, 对于成功的连接，返回值与第1个参数的值相同。返回值指向的内存和第一个参数指针指向的内存一样失败：返回 NULL句柄：是 windows 中的一个概念, 句柄可以理解为一个实例(或者对象)
*/ 

字符编码

// 获取api默认使用的字符编码，为当前连接返回默认的字符集
const char *mysql_character_set_name(MYSQL *mysql) 
// 返回值: 默认字符集// 设置api使用的字符集，第二个参数 csname 就是要设置的字符集 -> 支持中文: utf8
int mysql_set_character_set(MYSQL *mysql, char *csname);
// 返回值：成功返回0， 失败返回非0

选择连接的数据库

// 功能：选择操作的数据库
// 参数说明:
// 		mysql--初始化完成的句柄
// 		db-----要切换选择的数据库名称
// 返回值：成功返回0， 失败返回非0
int mysql_select_db(MYSQL *mysql, const char *db)

执行 sql 语句

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

获取结果集到本地

// 将结果集从mysql(参数) 对象中取出
// MYSQL_RES 对应一块内存, 里边保存着这个查询之后得到的结果集，如何将行和列的数据从结果集中取出, 需要使用其他函数
MYSQL_RES *mysql_store_result(MYSQL *mysql);// 返回值: 具有多个结果的MYSQL_RES结果集合。如果出现错误，返回NULL。 

得到结果集的行数和列数

// 获取结果集中的行数
// 参数：result--保存到本地的结果集地址
// 返回值：结果集中数据的条数
uint64_t mysql_num_rows(MYSQL_RES *result);// 获取结果集中的列数
// 参数: 调用 mysql_store_result() 得到的返回值
// 返回值: 结果集中的列数
unsigned int mysql_num_fields(MYSQL_RES *result);

遍历结果集

typedef char** MYSQL_ROW;
// 遍历结果集的下一行，并且这个接口会保存当前读取结果位置，每次获取的都是下一条数据，如果想遍历整个结果集, 需要对该函数进行循环调用// 返回值MYSQL_ROW是二级指针，也就是说char**，将每⼀条数据做成了字符串指针数组
// 比如 row[0]就是第0列，row[1]就是第1列 ...
MYSQL_ROW mysql_fetch_row(MYSQL_RES *result);/*
参数: - result: 通过查询得到的结果集
返回值: - 成功: 得到了当前记录中每个字段的值- 失败: NULL, 说明数据已经读完了
*/

资源回收

// 释放结果集
// 参数说明：result是保存到本地的结果集地址
void mysql_free_result(MYSQL_RES *result);// 关闭mysql实例
// 参数说明：mysql是初始化完成的句柄
void mysql_close(MYSQL *mysql);

打印错误信息

// 返回错误的描述
const char *mysql_error(MYSQL *mysql);// 返回错误的编号
unsigned int mysql_errno(MYSQL *mysql);

获取表头 -> 列名 (字段名)

// 参数: 调用 mysql_store_result() 得到的返回值
// 返回值: MYSQL_FIELD* 指向一个结构体
// 通过查询官方文档, 返回是一个结构体的数组
// 通过这个函数得到结果集中所有列的名字
MYSQL_FIELD *mysql_fetch_fields(MYSQL_RES *result);

​ 返回值 MYSQL_FIELD 对应的是一个结构体，在 mysql.h 中定义如下:

// mysql.h
// 结果集中的每一个列对应一个 MYSQL_FIELD
typedef struct st_mysql_field {char *name;                 /* 列名-> 字段的名字 */char *org_name;             /* Original column name, if an alias */char *table;                /* Table of column if column was a field */char *org_table;            /* Org table name, if table was an alias */char *db;                   /* Database for table */char *catalog;              /* Catalog for table */char *def;                  /* Default value (set by mysql_list_fields) */unsigned long length;       /* Width of column (create length) */unsigned long max_length;   /* Max width for selected set */unsigned int name_length;unsigned int org_name_length;                                                                                        unsigned int table_length;unsigned int org_table_length;unsigned int db_length;unsigned int catalog_length;unsigned int def_length;unsigned int flags;         /* Div flags */unsigned int decimals;      /* Number of decimals in field */unsigned int charsetnr;     /* Character set */enum enum_field_types type; /* Type of field. See mysql_com.h for types */void *extension;
} MYSQL_FIELD;

​ 函数的使用举例：

// 得到存储头信息的数组的地址
MYSQL_FIELD* fields = mysql_fetch_fields(res);
// 得到列数
int num = mysql_num_fields(res);
// 遍历得到每一列的列名
for(int i=0; i<num; ++i)
{printf("当前列的名字: %s\n", fields[i].name);
}

得到结果集中字段的长度

/* 
返回结果集内当前行的列的长度:1. 如果打算复制字段值，使用该函数能避免调用strlen()。2. 如果结果集包含二进制数据，必须使用该函数来确定数据的大小，原因在于，对于包含Null字符的任何字段，strlen()将返回错误的结果。
*/
unsigned long *mysql_fetch_lengths(MYSQL_RES *result);/*
参数: - result: 通过查询得到的结果集
返回值:- 无符号长整数的数组表示各列的大小。如果出现错误，返回NULL。
*/

事务操作

// mysql中默认会进行事务的提交
// 因为自动提交事务, 会对我们的操作造成影响
// 如果我们操作的步骤比较多, 集合的开始和结束需要用户自己去设置, 需要改为手动方式提交事务
my_bool mysql_autocommit(MYSQL *mysql, my_bool mode) 
/*
参数:如果模式为“1”，启用autocommit模式；如果模式为“0”，禁止autocommit模式。
返回值如果成功，返回0，如果出现错误，返回非0值。
*/// 事务提交
my_bool mysql_commit(MYSQL *mysql);
// 返回值: 成功: 0, 失败: 非0// 数据回滚
my_bool mysql_rollback(MYSQL *mysql) 
// 返回值: 成功: 0, 失败: 非0

Ⅲ. MySQL API使用

​ 首先创建测试数据库：

mysql> create database if not exists gobang;
Query OK, 1 row affected (0.03 sec)mysql> show databases;
+--------------------+
| Database           |
+--------------------+
| information_schema |
| gobang             |
| mysql              |
| performance_schema |
| sys                |
+--------------------+
5 rows in set (0.00 sec)mysql> use gobang;
Database changed
mysql> create table if not exists stu(-> stu_num int primary key auto_increment,   # 学号-> name varchar(32),						 # 姓名-> age int,									 # 年龄-> chinese decimal(5,2),					 # 成绩-> english decimal(5,2),-> math decimal(5,2));
Query OK, 0 rows affected (0.30 sec)mysql> show tables-> ;
+------------------+
| Tables_in_gobang |
+------------------+
| stu              |
+------------------+
1 row in set (0.00 sec)mysql> desc stu;
+---------+--------------+------+-----+---------+----------------+
| Field   | Type         | Null | Key | Default | Extra          |
+---------+--------------+------+-----+---------+----------------+
| stu_num | int(11)      | NO   | PRI | NULL    | auto_increment |
| name    | varchar(32)  | YES  |     | NULL    |                |
| age     | int(11)      | YES  |     | NULL    |                |
| chinese | decimal(5,2) | YES  |     | NULL    |                |
| english | decimal(5,2) | YES  |     | NULL    |                |
| math    | decimal(5,2) | YES  |     | NULL    |                |
+---------+--------------+------+-----+---------+----------------+
6 rows in set (0.02 sec)

​ 然后再编写一下 Makefile 文件：

mysql:mysql.cgcc -o $@ $^ -L/usr/lib64/mysql/ -lmysqlclient  #-L后面跟的是动态库的路径，-l后面跟的是动态库名称

​ 最后再来实现一下增删改查操作：

#include <stdio.h>
#include <string.h>
#include <mysql/mysql.h>#define HOST "127.0.0.1"  // 不允许使用公网地址，所以用本地换回
#define USER "root"
#define PASSWD ""
#define DBNAME "gobang"
#define PORT 3306int main()
{// 1.初始化mysql句柄MYSQL* mysql = mysql_init(NULL);if(mysql == NULL){printf("mysql init fail!\n");return -1;}// 2.连接mysql服务器if(mysql_real_connect(mysql, HOST, USER, PASSWD, DBNAME, PORT, NULL, 0) == NULL){printf("mysql connect fail：%s\n", mysql_errno(mysql)); // 打印错误信息mysql_close(mysql); // 记得关闭句柄return -1;}// 3.设置客户端字符集if(mysql_set_character_set(mysql, "utf8") != 0){printf("client set character fail：%s\n", mysql_errno(mysql)); // 打印错误信息mysql_close(mysql); // 记得关闭句柄return -1;}// 4.选择要操作的数据库（其实也可以不用，因为在初始化的时候已经指定了要选择的数据库）if(mysql_select_db(mysql, DBNAME) != 0){printf("select database fail：%s\n", mysql_errno(mysql)); // 打印错误信息mysql_close(mysql); // 记得关闭句柄return -1;}// 5.执行sql语句// char* sql = "insert stu value(null, '利刃', 1314, 100, 150, 149)"; // 增// char* sql = "update stu set math=math-40 where stu_num=1;";       // 改// char* sql = "delete from stu where stu_num=1;";                   // 删char* sql = "select * from stu;"; // 查，需要配合下面的第6、7、8步int n = mysql_query(mysql, sql);if(n != 0){printf("%s: sql query fail：%s\n", sql, mysql_errno(mysql)); // 打印错误信息mysql_close(mysql); // 记得关闭句柄return -1;}// 6.如果sql语句是查询语句，需要保存结果到本地MYSQL_RES* res = mysql_store_result(mysql);if(res == NULL){mysql_close(mysql); // 记得关闭句柄return -1;}// 7.获取结果集中的结果条数：行数和列数int num_row = mysql_num_rows(res);int num_field = mysql_num_fields(res);// 8.遍历保存到本地的结果集for(int i = 0; i < num_row; ++i){MYSQL_ROW row = mysql_fetch_row(res);for(int j = 0; j < num_field; ++j){printf("%s\t", row[j]);}printf("\n");}// 9.释放结果集mysql_free_result(res);// 10.关闭连接，释放mysql句柄mysql_close(mysql);return 0;
}