# async_mysql

**Repository Path**: ccjabc/async_mysql

## Basic Information

- **Project Name**: async_mysql
- **Description**: async_mysql是header-only的高性能的 C++ MySQL 客户端库，提供同步和异步操作接口，支持连接池管理和自动重连机制。基于 ASIO 实现异步操作，适用于高并发数据库访问场景。除了asio以外，无其它依赖，直接引入async_mysql.hpp即可。尤其适合在asio框架下的高并发场景
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-08-04
- **Last Updated**: 2025-08-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# async_mysql - 异步MySQL客户端库

`async_mysql` 是header-only的高性能的 C++ MySQL 客户端库，提供同步和异步操作接口，支持连接池管理和自动重连机制。基于 ASIO 实现异步操作，适用于高并发数据库访问场景。除了asio以外，无其它依赖，直接引入async_mysql.hpp即可。尤其适合在asio框架下的高并发场景

## 设计思路

`async_mysql` 的核心设计目标是提供高效、易用且安全的数据库访问接口：

1. **双模式操作**：

   - 同步 API：简单直接的阻塞式操作
   - 异步 API：基于 ASIO 的非阻塞操作，适合高并发场景

2. **连接池管理**：

   - 自动维护连接生命周期
   - 支持连接复用和自动扩容
   - 健康检查和连接重建机制

3. **资源安全**：

   - 智能代理自动归还连接
   - RAII 机制防止资源泄漏
   - 异常安全保证

4. **灵活性**：

   - 支持 Boost.Asio 或独立 ASIO
   - 可选的自动归还控制
   - 可扩展的连接池配置

## 功能特性

- 同步/异步连接管理
- 同步/异步查询执行
- 结果集处理（行和字段访问）
- 连接池管理（同步和异步）
- 自动重连和健康检查
- 线程安全的 API 设计
- 灵活的 ASIO 实现选择

## 快速开始

async_mysql.hpp是独立文件，只需要引入此文件即可

但要注意如果你的asio是boost库里面的，请预定义`ASYNC_MYSQL_USE_BOOST_ASIO` 宏

### 通过cmake集成

你可以直接包含cmake文件来集成，也可以安装后通过find_package引入

```cmake
find_package(async_mysql)
# 链接库
target_link_libraries(your_project
    PRIVATE 
        async_mysql::async_mysql
)
```

## 使用示例



### 同步操作示例

```cpp
// 创建同步连接
async_mysql::connection conn(config);
conn.connect_throw(); // 连接数据库

// 执行查询
auto [ec, rs] = conn.query("SELECT * FROM users");
if (!ec) {
    async_mysql::row r;
    while (rs.next(r)) {
        std::cout << "User: " << r["name"] << ", Email: " << r["email"] << "\n";
    }
}

// 执行更新
conn.execute_throw("UPDATE users SET active = 1 WHERE id = 42");
```

### 异步操作示例

```cpp
#include "async_mysql.hpp"
#include <asio.hpp>

int main() {
    asio::io_context io;
    
    // 创建异步连接
    auto conn = std::make_shared<async_mysql::async_connection>(io, config);
    
    conn->async_connect([](std::error_code ec) {
        if (ec) {
            std::cerr << "Connection failed: " << ec.message() << "\n";
            return;
        }
        
        conn->async_query("SELECT * FROM products", [](auto ec, auto rs) {
            if (!ec) {
                // 处理结果集
            }
        });
    });
    
    io.run();
    return 0;
}
```

### 同步连接池使用

```cpp
async_mysql::connection_pool pool(config, 5); // 5个连接

{
    // 获取连接代理（自动归还）
    auto proxy = pool.get_connection_proxy();
    
    // 执行查询
    auto [ec, rs] = proxy->query("SELECT * FROM orders");
    if (!ec) {
        // 处理结果
    }
    
    // 代理离开作用域时自动归还连接
}

// 手动控制归还
{
    auto proxy = pool.get_connection_proxy();
    proxy.disable_auto_release(); // 禁用自动归还
    
    // 执行多个操作...
    proxy->execute("BEGIN");
    proxy->execute("UPDATE inventory SET quantity = quantity - 1");
    proxy->execute("COMMIT");
    
    proxy.release(); // 手动归还
}
```

### 异步连接池使用

```cpp
asio::io_context io;
auto pool = std::make_shared<async_mysql::async_connection_pool>(io, config, 5);

// 获取连接代理
pool->get_connection_proxy([](auto proxy) {
    if (!proxy || !*proxy) {
        std::cerr << "Failed to get connection\n";
        return;
    }
    
    // 执行异步查询
    proxy->async_query("SELECT * FROM transactions", [](auto ec, auto rs) {
        if (!ec) {
            // 处理结果
        }
        // 代理在回调结束后自动归还连接
    });
});

io.run();
```

### 使用内部 IO 线程池

```cpp
// 创建内部管理IO的连接池（4个工作线程）
auto pool = std::make_shared<async_mysql::async_connection_pool>(4, config, 5);

pool->get_connection_proxy([](auto proxy) {
    if (!proxy) return;
    
    proxy->async_query("SELECT COUNT(*) FROM logs", [](auto ec, auto rs) {
        // 处理结果
    });
});

// 无需手动运行io_context
```

## 事务处理示例

```cpp
pool->get_connection_proxy([](auto proxy) {
    if (!proxy) return;
    
    // 禁用自动归还
    proxy->disable_auto_release();
    
    // 开始事务
    proxy->async_query("START TRANSACTION", [proxy](auto ec, auto) {
        if (ec) {
            proxy->release();
            return;
        }
        
        // 更新操作1
        proxy->async_query("UPDATE accounts SET balance = balance - 100 WHERE id = 1", 
            [proxy](auto ec, auto) {
                if (ec) goto rollback;
                
                // 更新操作2
                proxy->async_query("UPDATE accounts SET balance = balance + 100 WHERE id = 2", 
                    [proxy](auto ec, auto) {
                        if (ec) goto rollback;
                        
                        // 提交事务
                        proxy->async_query("COMMIT", [proxy](auto ec, auto) {
                            proxy->release();
                        });
                        return;
                        
                    rollback:
                        // 回滚事务
                        proxy->async_query("ROLLBACK", [proxy](auto, auto) {
                            proxy->release();
                        });
                    });
            });
    });
});
```

## 错误处理

```cpp
try {
    // 同步异常处理
    async_mysql::connection conn(config);
    conn.connect_throw();
    conn.query_throw("SELECT * FROM invalid_table");
} catch (const std::system_error& e) {
    std::cerr << "Database error: " << e.what() 
              << " (code: " << e.code() << ")\n";
}

// 异步错误处理
proxy->async_query("INVALID SQL", [](auto ec, auto) {
    if (ec) {
        std::cerr << "Query failed: " << ec.message() << "\n";
        if (ec == async_mysql::error::query_failed) {
            // 处理特定错误
        }
    }
});
```

## 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。