# 数据库仿navicat客户端-backend

**Repository Path**: libq/db-backend-ffi

## Basic Information

- **Project Name**: 数据库仿navicat客户端-backend
- **Description**: 目前市面上最好用的客户端为navicat，但是比较强大功能为收费功能，基于这个出发点，发起一项开发数据库的公益项目。 基于大家的力量一起开发一个免费，好用，功能全的数据库客户端，目前是开发的雏形，希望抛砖引玉，大家一起贡献自己的力量。 客户端支持windows,linux,macOS等跨平台 系统架构：客户端使用flutter技术 数据库驱动：go语言开发（未来使用rust）
- **Primary Language**: Unknown
- **License**: BSD-3-Clause
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-31
- **Last Updated**: 2026-06-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DB Backend FFI

数据库客户端 FFI 动态库 - Go实现

## 项目说明

这是一个专门为 Flutter FFI 调用设计的 Go 动态库，提供数据库连接和查询功能。

## 功能特性

### 已实现功能

1. **连接管理**
   - 创建数据库连接
   - 测试连接
   - 断开连接
   - 连接状态查询
   - 获取所有连接

2. **查询执行**
   - 执行SQL查询
   - 执行更新操作
   - 返回JSON格式结果

3. **支持的数据库**
   - MySQL
   - PostgreSQL

4. **其他特性**
   - 线程安全（使用mutex）
   - 连接池管理
   - JSON结果格式化
   - 内存管理（提供释放函数）

## 导出函数

### 连接管理

#### CreateConnection
```c
int CreateConnection(
    char* id,          // 连接ID
    char* dbType,      // 数据库类型: "mysql" 或 "postgresql"
    char* host,        // 主机地址
    int port,          // 端口号
    char* username,    // 用户名
    char* password,    // 密码
    char* database     // 数据库名
);
```

返回值：
- 0: 成功
- -1: 连接ID已存在
- -2: 不支持的数据库类型
- -3: 连接打开失败
- -4: 连接测试失败

#### TestConnection
```c
int TestConnection(
    char* dbType,
    char* host,
    int port,
    char* username,
    char* password,
    char* database
);
```

返回值：
- 0: 测试成功
- -2: 不支持的数据库类型
- -3: 连接打开失败
- -4: 连接测试失败

#### Disconnect
```c
int Disconnect(char* connectionID);
```

返回值：
- 0: 成功
- -1: 连接不存在
- -2: 关闭失败

#### GetConnectionStatus
```c
int GetConnectionStatus(
    char* connectionID,
    char** resultPtr    // JSON结果指针
);
```

返回JSON格式：
```json
{
    "id": "connection_id",
    "connected": true,
    "message": "Connected"
}
```

#### GetAllConnections
```c
int GetAllConnections(char** resultPtr);
```

返回JSON数组：
```json
["connection_id_1", "connection_id_2"]
```

### 查询操作

#### ExecuteQuery
```c
int ExecuteQuery(
    char* connectionID,
    char* query,
    char** resultPtr    // JSON结果指针
);
```

返回JSON格式：
```json
{
    "columns": ["col1", "col2"],
    "rows": [
        {"col1": "value1", "col2": "value2"}
    ],
    "row_count": 1,
    "execution_time": 0.001,
    "message": ""
}
```

#### ExecuteUpdate
```c
int ExecuteUpdate(
    char* connectionID,
    char* query,
    char** resultPtr
);
```

返回JSON格式：
```json
{
    "affected": 10,
    "execution_time": 0.002,
    "message": "10 rows affected"
}
```

### 工具函数

#### GetVersion
```c
char* GetVersion();
```

返回版本号字符串："1.0.0"

#### FreeCString
```c
void FreeCString(char* s);
```

释放由Go分配的C字符串内存。

## 编译方法

### Windows

#### 使用批处理脚本
```bash
build_windows.bat
```

#### 使用Make
```bash
make windows
```

#### 手动编译
```bash
go build -buildmode=c-shared -o db_library_windows_x64.dll db_library.go
```

### Linux

#### 使用shell脚本
```bash
chmod +x build_linux.sh
./build_linux.sh
```

#### 使用Make
```bash
make linux
```

#### 手动编译
```bash
go build -buildmode=c-shared -o db_library_linux_x64.so db_library.go
```

### macOS

#### 使用shell脚本
```bash
chmod +x build_macos.sh
./build_macos.sh
```

#### 使用Make
```bash
make macos
```

#### 手动编译
```bash
# x64架构
go build -buildmode=c-shared -o db_library_macos_x64.dylib db_library.go

# arm64架构
GOARCH=arm64 go build -buildmode=c-shared -o db_library_macos_arm64.dylib db_library.go
```

## 编译前准备

### 1. 设置Go代理（中国用户）
```bash
go env -w GOPROXY=https://goproxy.cn,direct
```

### 2. 下载依赖
```bash
go mod tidy
```

## 生成的文件

编译后会生成以下文件：

### Windows
- `db_library_windows_x64.dll` - 动态链接库
- `db_library_windows_x64.h` - C头文件

### Linux
- `db_library_linux_x64.so` - 共享对象
- `db_library_linux_x64.h` - C头文件

### macOS
- `db_library_macos_x64.dylib` - 动态库（Intel）
- `db_library_macos_x64.h` - C头文件（Intel）
- `db_library_macos_arm64.dylib` - 动态库（Apple Silicon）
- `db_library_macos_arm64.h` - C头文件（Apple Silicon）

## 与Flutter集成

### 1. 复制动态库

将编译好的动态库复制到Flutter项目：

**Windows:**
```
db_library_windows_x64.dll -> db_client_pc/windows/
```

**Linux:**
```
db_library_linux_x64.so -> db_client_pc/linux/
```

**macOS:**
```
db_library_macos_x64.dylib -> db_client_pc/macos/
或
db_library_macos_arm64.dylib -> db_client_pc/macos/
```

### 2. 配置CMakeLists.txt (Windows)

在 `db_client_pc/windows/CMakeLists.txt` 中添加：

```cmake
# 添加DLL路径
set(DB_LIBRARY_PATH "${CMAKE_CURRENT_SOURCE_DIR}/../db_library_windows_x64.dll")

# 复制DLL到输出目录
install(FILES "${DB_LIBRARY_PATH}" DESTINATION "${CMAKE_INSTALL_PREFIX}")
```

### 3. Flutter FFI调用

在Flutter中调用动态库：

```dart
import 'dart:ffi';
import 'dart:io';
import 'package:ffi/ffi.dart';

// 加载动态库
final lib = DynamicLibrary.open('db_library_windows_x64.dll');

// 获取函数
final createConnection = lib.lookupFunction<
    Int32 Function(Pointer<Utf8>, Pointer<Utf8>, Pointer<Utf8>, Int32, Pointer<Utf8>, Pointer<Utf8>, Pointer<Utf8>),
    int Function(Pointer<Utf8>, Pointer<Utf8>, Pointer<Utf8>, int, Pointer<Utf8>, Pointer<Utf8>, Pointer<Utf8>)
>('CreateConnection');

// 调用函数
final idPtr = 'my_connection'.toNativeUtf8();
final typePtr = 'mysql'.toNativeUtf8();
final hostPtr = 'localhost'.toNativeUtf8();
final usernamePtr = 'root'.toNativeUtf8();
final passwordPtr = 'password'.toNativeUtf8();
final databasePtr = 'test_db'.toNativeUtf8();

final result = createConnection(
    idPtr, typePtr, hostPtr, 3306, usernamePtr, passwordPtr, databasePtr
);

// 释放内存
calloc.free(idPtr);
calloc.free(typePtr);
calloc.free(hostPtr);
calloc.free(usernamePtr);
calloc.free(passwordPtr);
calloc.free(databasePtr);
```

## 错误码说明

| 错误码 | 说明 |
|-------|------|
| 0 | 成功 |
| -1 | 连接不存在/已存在 |
| -2 | 不支持的数据库类型/查询执行失败 |
| -3 | 连接打开失败/获取影响行数失败 |
| -4 | 连接测试失败/JSON序列化失败 |
| -5 | JSON序列化失败 |

## 性能特点

- **直接调用**: FFI调用比HTTP API快10-50倍
- **内存高效**: Go的内存管理优化
- **并发安全**: 使用mutex保护共享资源
- **连接池**: 自动管理连接池

## 内存管理

**重要**: 必须手动管理内存！

1. Go返回的字符串需要调用 `FreeCString` 释放
2. Dart分配的字符串需要调用 `calloc.free` 释放
3. 指针参数在使用后必须释放

示例：
```dart
// Go返回的字符串
final resultPtr = calloc<Pointer<Utf8>>();
executeQuery(connectionIdPtr, queryPtr, resultPtr);

final resultJson = resultPtr.value.toDartString();
freeCString(resultPtr.value);  // 释放Go分配的内存
calloc.free(resultPtr);        // 释放Dart分配的指针

// Dart分配的字符串
final strPtr = 'hello'.toNativeUtf8();
// 使用strPtr...
calloc.free(strPtr);  // 必须释放
```

## 调试技巧

### 查看导出函数
```bash
# Windows
dumpbin /exports db_library_windows_x64.dll

# Linux
nm -D db_library_linux_x64.so

# macOS
nm -gU db_library_macos_x64.dylib
```

### 测试动态库
可以使用C程序测试：
```c
#include <stdio.h>
#include <stdlib.h>
#include "db_library_windows_x64.h"

int main() {
    int result = TestConnection(
        "mysql",
        "localhost",
        3306,
        "root",
        "password",
        "test_db"
    );
    
    printf("Test result: %d\n", result);
    return 0;
}
```

## 技术栈

- **语言**: Go 1.21+
- **数据库驱动**:
  - MySQL: go-sql-driver/mysql
  - PostgreSQL: lib/pq
- **编译模式**: c-shared

## 项目结构

```
db_backend_ffi/
├── db_library.go          # 主要源码
├── go.mod                 # Go模块定义
├── build_windows.bat      # Windows编译脚本
├── build_linux.sh         # Linux编译脚本
├── build_macos.sh         # macOS编译脚本
├── Makefile               # Make构建文件
└── README.md              # 项目说明
```

## 常见问题

### 1. 编译失败
- 检查Go版本（需要1.21+）
- 检查依赖是否下载成功
- 使用Go代理：`go env -w GOPROXY=https://goproxy.cn,direct`

### 2. 动态库加载失败
- 检查动态库路径是否正确
- 检查动态库是否与平台匹配
- Windows: 确保.dll文件在正确位置
- Linux/macOS: 检查文件权限

### 3. 内存泄漏
- 确保调用 `FreeCString` 释放Go返回的字符串
- 确保调用 `calloc.free` 释放Dart分配的内存
- 使用内存分析工具检查

### 4. 连接失败
- 检查数据库服务器是否运行
- 检查连接参数是否正确
- 检查防火墙设置
- 检查数据库用户权限

## 许可证

私有项目，仅供内部使用