# mydatabase

**Repository Path**: blueLotu/mydatabase

## Basic Information

- **Project Name**: mydatabase
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-15
- **Last Updated**: 2026-07-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# database — 数据库公共接口模块

统一的、可扩展的 C++ 数据库访问中间件，基于 Qt 5.15.2 构建，零第三方依赖。

## 特性

- **跨平台**: Windows / Linux，**x86_64 + ARM64 (aarch64)**，适配银河麒麟桌面/服务器
- **多数据库**: SQLite (Qt QSQLITE)，达梦/金仓/神威 (Qt QODBC)
- **QxOrm ORM**: QX_REGISTER 编译期注册 + qx::dao CRUD + QxSqlQuery 条件查询
- **批量操作**: qx::dao::insert(batch) / update(batch) 批量写入
- **DDL 迁移**: Flyway 风格版本化 SQL 脚本，支持外部目录热加载（免编译）
- **连接池**: 进程全局池，QMutex 线程安全，空闲回收，超时控制，IPoolSync 协程模式预留
- **自动维护**: 定时清理 (DbMaintenanceScheduler) + 容量守护 (CapacityGuard)
- **离线工具**: CLI 导入导出 `db_tool` (JSON/CSV)
- **分片预留**: HashShard / RangeShard 策略接口 + ShardingRouter
- **编码**: 端到端 UTF-8，NVARCHAR2 Unicode 存储

## 快速开始

### 构建

#### qmake（传统方式）

```bash
# 静态库 (默认)
qmake
make -j$(nproc)        # Linux
mingw32-make -j8       # Windows MinGW

# 动态库
qmake "CONFIG+=shared_lib"
make -j$(nproc)
```

#### CMake（推荐，所有平台）

```bash
# 静态库 (默认)
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel

# 动态库
cmake -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=ON
cmake --build build --parallel

# 包含测试
cmake -B build -DBUILD_TESTS=ON
cmake --build build --parallel
ctest --test-dir build

# 仅构建库 (不含 tools/tests/examples)
cmake -B build -DBUILD_TOOLS=OFF -DBUILD_TESTS=OFF -DBUILD_EXAMPLES=OFF
cmake --build build --parallel
```

#### Windows (x86_64, MinGW / MSVC)

```bash
# CMake 方式 (推荐)
cmake -B build -G "MinGW Makefiles" -DCMAKE_PREFIX_PATH=C:/Qt/5.15.2/mingw81_64
cmake --build build --parallel

# 或设置环境变量
set CMAKE_PREFIX_PATH=C:\Qt\5.15.2\msvc2019_64
cmake -B build
cmake --build build --parallel
```

#### Linux ARM64 / 银河麒麟 (aarch64)

```bash
# Qt 5.15.2 ARM64 交叉编译或原生编译
cmake -B build -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_TOOLCHAIN_FILE=cmake/toolchain-arm64.cmake
cmake --build build --parallel

# 达梦/金仓/神威需提供 ARM64 版本的 ODBC 驱动
```

> **注意**: ARM64 下 Qt 需编译为 `-platform linux-aarch64-gnu-g++`。Windows 使用 CMake 需设置 `CMAKE_PREFIX_PATH` 指向 Qt5 安装路径。

### 使用

```cpp
#include "database.h"
using namespace db;

// ========== 1. 定义实体 (Entity<T> CRTP + Q_GADGET) ==========
class MyEntity : public Entity<MyEntity> {
    Q_GADGET
    Q_PROPERTY(qint64 id MEMBER m_id)
    Q_PROPERTY(QString name MEMBER m_name)
public:
    static QString tableName()  { return "t_my"; }
    static QString primaryKey() { return "id"; }
    qint64  m_id = 0;
    QString m_name;
};
Q_DECLARE_METATYPE(MyEntity)

// ========== 2. 打开数据库 (Database 门面, 推荐) ==========
auto dbResult = Database::open(DbConfig::sqlite("app.db"));
auto db = dbResult.takeValue();
// *db 隐式转换为 IDatabase&，db->transaction() 直接可用

// ========== 3. Entity<T> CRUD 操作 ==========
MyEntity e;
e.m_name = "hello";
e.save(*db);                              // INSERT (自动填充 id + 时间戳)

auto found = MyEntity::find(*db, 1);      // SELECT BY PK
if (found && found.value().has_value()) {
    auto& f = *found.value();
    f.m_name = "world";
    f.save(*db);                          // UPDATE (仅更新脏字段)
}

e.remove(*db);                             // DELETE BY PK
```

### 批量操作

```cpp
// 批量插入 (事务内)
QVector<MyEntity> batch;
for (int i = 0; i < 1000; i++) {
    MyEntity e; e.m_name = QString("item-%1").arg(i); batch.append(e);
}
MyEntity::insertMany(*db, batch, 500);   // 每 500 条一批

// 条件查询
auto cond = Expression::eq("name", "hello")
            .AND(Expression::gt("id", 10));
auto list = MyEntity::where(*db, cond);
auto count = MyEntity::count(*db, cond);

// 条件删除
auto delResult = MyEntity::deleteWhere(*db, cond);

// 写入缓冲 (高频写入)
WriteBuffer<MyEntity> buffer(*db, 1000, 5000);  // 1000条 / 5秒自动刷入
buffer.setConflictStrategy(WriteBuffer<MyEntity>::Upsert);
buffer.push(entity);
buffer.flush();  // 手动刷新
```

### Lambda 事务

```cpp
auto txResult = db->transaction([&]() {
    MyEntity e1, e2;
    e1.m_name = "A"; e2.m_name = "B";
    e1.save(*db); e2.save(*db);
});
// 正常执行 → 自动 commit；异常 → 自动 rollback
```

### 自动维护

```cpp
// 每天凌晨 3:00 清理 90 天前的数据
auto sched = new DbMaintenanceScheduler(*db);
CleanupPolicy policy;
policy.olderThanDays = 90;
policy.maxRowsPerTable = 1000000;
sched->scheduleDaily(policy, 3, 0);
sched->start();

// 容量守护: 超过 500 万行自动裁剪
auto guard = new CapacityGuard(*db);
guard->watchAll(5000000);
guard->setCheckInterval(200);  // 每 200 次写入检查一次
db->setCapacityGuard(guard);
```

## 新数据库适配指南

### 1. 确定方言

- **Oracle 兼容** (达梦/金仓/神威): 直接使用 `OracleCompatDialect(type)`
- **其他 SQL 方言** (MySQL/PostgreSQL 等): 实现 `ISqlDialect` 子类

### 2. 实现 ISqlDialect

```cpp
class MyDialect : public ISqlDialect {
    QString quoteIdentifier(const QString& name) override;
    QString placeholder(int index) override;
    QString limitOffset(int limit, int offset) override;
    QString autoIncrementPK(const QString& col) override;
    QString lastInsertIdSql(const QString& table, const QString& pkCol) override;
    QString mapType(int qtMetaTypeId, int length) override;
    QString encodingPragma() override;
    QString upsertClause(const QStringList& conflictColumns) override;
};
```

### 3. 实现 IDatabase

```cpp
class MyDatabase : public IDatabase {
    // 实现全部纯虚方法
    // 使用 DbConnectionPool 管理连接
    // 使用自定义方言
};
```

### 4. 注册后端

```cpp
DbFactory::registerType(MyDbType, [](DbType t) {
    return std::make_unique<MyDatabase>();
});
```

## 连接配置

### SQLite

```cpp
auto cfg = DbConfig::sqlite("mydata.db");
cfg.poolMaxSize = 4;
cfg.slowQueryThresholdMs = 200;
```

### 达梦 (ODBC)

```cpp
// DSN 模式
auto cfg = DbConfig::dameng("192.168.1.100", 5236, "MYDB", "user", "pwd");

// DSN-less 模式
cfg.dsn = "";  // 留空 → DRIVER={DM ODBC};SERVER=...;DATABASE=...
cfg.encoding = "UTF-8";
```

## 迁移脚本

### 命名规范

```
resources/migrations/
└── sqlite/V001__initial_schema.sql
```

### 外部目录 (运维免编译)

```
./migrations/sqlite/V003__hotfix.sql   ← DBA直接放置, 重启自动执行
```

## 项目结构

```
database/
├── CMakeLists.txt          # CMake 构建 (推荐)
├── database.pro            # qmake 构建
├── lib/                    # 核心库
│   ├── CMakeLists.txt
│   ├── lib.pro
│   ├── core/               # 接口/工厂/门面/连接池/维护
│   ├── dialect/            # SQL 方言 (SQLite + Oracle兼容)
│   ├── orm/                # QxOrm 实体注册 (QX_REGISTER_HPP/CPP)
│   ├── ddl/                # 迁移系统
│   ├── sharding/           # 分片策略/路由
│   └── impl/               # 数据库后端 (SQLite + ODBC)
├── resources/              # Qt 资源 (DDL 脚本)
├── tools/                  # CLI 导入导出工具 db_tool
│   ├── CMakeLists.txt
│   └── tools.pro
├── tests/                  # 单元测试 (Qt Test)
│   ├── CMakeLists.txt
│   └── tests.pro
├── examples/               # 使用示例
│   ├── CMakeLists.txt
│   └── examples.pro
└── doc/                    # 文档
    ├── 需求规格说明书.md
    └── 详细设计说明书.md
```

## 文档

- [database_design.md](database_design.md) — 系统设计方案
- [doc/需求规格说明书.md](doc/需求规格说明书.md) — 需求规格说明书 (GB/T 9385)
- [doc/详细设计说明书.md](doc/详细设计说明书.md) — 详细设计说明书

## 许可

内部项目