# sqlite3cj

**Repository Path**: longkicode/sqlite3cj

## Basic Information

- **Project Name**: sqlite3cj
- **Description**: 基于仓颉 FFI（`foreign`）对 SQLite3 C API 的封装，提供版本查询、打开/关闭、建表、增删改查、参数绑定、事务、错误处理、文件持久化等能力。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-10
- **Last Updated**: 2026-09-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# sqlite3cj — 仓颉 (Cangjie) 语言的 SQLite3 FFI 封装库

基于仓颉 FFI（`foreign`）对 SQLite3 C API 的封装，提供版本查询、打开/关闭、建表、增删改查、参数绑定、事务、错误处理、文件持久化等能力。

- 语言：仓颉 Cangjie 1.0.4（`cjc` / `cjpm`）
- 平台：Windows x64（本仓库演示环境为 `x86_64-w64-mingw32`）
- SQLite3：随库分发 `sqlite3.dll`（动态链接，见下方「依赖说明」）

## 目录结构

```
sqlite3cj/
├── cjpm.toml          # 库包配置（output-type = static，ffi.c 声明 sqlite3）
├── src/
│   ├── main.cj        # 占位文件（cjpm 扫描 src 根需要）
│   └── c/
│       └── sqlite3.cj # FFI 声明（包 sqlite3cj.c）
├── lib/
│   ├── sqlite3.dll    # SQLite3 运行时 DLL
│   └── libsqlite3.dll # 链接用（cjpm 的 ffi.c 在 Windows 上检查 lib<name>.dll）
└── examples/          # 完整调用示例（独立项目，从 Gitee 引用本库）
```

## 快速开始

### 1. 作为 git 依赖引用（发布到 Gitee 后）

在你项目的 `cjpm.toml` 中：

```toml
[dependencies]
sqlite3cj = { git = "https://gitee.com/longkicode/sqlite3cj.git", branch = "master" }
```

然后：

```bash
cjpm update   # 拉取依赖
cjpm build    # 编译
```

代码中引入：

```cangjie
import sqlite3cj.c as ffi
```

### 2. 本地 path 依赖（开发调试）

```toml
[dependencies]
sqlite3cj = { path = ".." }   # 指向本仓库根目录
```

### 3. 运行 examples（示例项目）

examples 是一个独立项目，它的 `cjpm.toml` 已配置为从 Gitee 引用本库（`git = "https://gitee.com/longkicode/sqlite3cj.git"`），可直接验证真实引用流程：

```bash
cd examples
cjpm update   # 从 Gitee 拉取 sqlite3cj
cjpm build
# 运行前把拉取到的 sqlite3cj/lib 和仓颉运行时目录加入 PATH
# 拉取位置：%USERPROFILE%\.cjpm\git\sqlite3cj\<commit>\lib
set PATH=%USERPROFILE%\.cjpm\git\sqlite3cj\<commit>\lib;%CANGJIE_HOME%\runtime\lib\windows_x86_64_llvm;%PATH%
target\release\bin\main.exe
```

## 调用示例（examples/src/main.cj 已覆盖）

| 实例 | 说明 |
|---|---|
| 版本信息 | `sqlite3_libversion()` |
| 内存库 + 建表 | `:memory:` + `CREATE TABLE` |
| INSERT 参数绑定 | `sqlite3_bind_int/int64/double/text/blob/null` |
| SELECT 查询 | 按列类型取 `int/int64/double/text/blob` |
| UPDATE / DELETE | `sqlite3_changes()` |
| 事务 | `BEGIN / COMMIT / ROLLBACK` |
| 错误处理 | `sqlite3_errcode() / sqlite3_errmsg()` |
| 文件库持久化 | 写文件库 → 重开读取验证 |

```cangjie
// 典型用法
import sqlite3cj.c as ffi
import std.core.*

unsafe main(): Unit {
    println("sqlite version: ${ffi.sqlite3_libversion_cjbindwrapper()}")

    try (path = LibC.mallocCString(":memory:").asResource()) {
        let ppDb = LibC.malloc<CPointer<ffi.sqlite3>>(count: 8)
        let rc = ffi.sqlite3_open_v2_cjbindwrapper(path.value, ppDb,
            ffi.SQLITE_OPEN_READWRITE | ffi.SQLITE_OPEN_CREATE, CString(CPointer<UInt8>()))
        if (rc == ffi.SQLITE_OK) {
            let db = ppDb.read()
            ffi.sqlite3_close_v2_cjbindwrapper(db)
        }
    }
}
```

> 注意：公开 API 均为 `sqlite3_xxx_cjbindwrapper` 包装名（FFI 声明是 `foreign`，需经包装才能在 `unsafe` 块外调用）。完整可运行示例见 `demo/src/main.cj`。

## 依赖与运行说明（重要）

1. **SQLite3 动态链接**：库通过 `[ffi.c] sqlite3 = { path = "lib" }` 声明，cjpm 会在最终链接时自动追加 `-L <仓库>/lib -lsqlite3`。Windows 下链接器直接绑定 `sqlite3.dll`，因此**运行 exe 时需要 `sqlite3.dll`（或 `libsqlite3.dll`）在 PATH 中或 exe 同目录**。
2. **仓颉运行时**：exe 依赖 `libcangjie-runtime.dll`，需将 `%CANGJIE_HOME%\runtime\lib\windows_x86_64_llvm` 加入 PATH（仓颉 SDK 自带）。
3. **git 依赖前置**：`cjpm` 通过 `git ls-remote` + `git fetch <commit>` 拉取依赖，需要 **Git ≥ 2.17**（老版本不支持按 commit hash fetch）。Windows 用户确保 `git` 在 PATH 中。
4. **跨包引用姿势**：依赖场景下必须 `import sqlite3cj.c as ffi` 后用 `ffi.xxx()`；不能直接 `import sqlite3cj.c.*` 后写 `c.xxx()`（模块短名限定在依赖场景不可用）。
5. **String → CString**：仓颉 `String` 没有 `toCString()`，用 `LibC.mallocCString(str).asResource()`；空串用 `CString(CPointer<UInt8>())`。

## 发布到 Gitee

```bash
# 1. 在 Gitee 新建空仓库（如 gitee.com/<你的账号>/sqlite3cj）
# 2. 本地初始化并推送
git init
git add .
git commit -m "init: sqlite3cj Cangjie FFI wrapper for SQLite3"
git remote add origin https://gitee.com/longkicode/sqlite3cj.git
git push -u origin master
```

推送后，任何项目的 `cjpm.toml` 写 `sqlite3cj = { git = "https://gitee.com/longkicode/sqlite3cj.git", branch = "master" }` 即可引用；更新发布时重新 `git push`，使用者 `cjpm update` 拉取最新提交。

## License

Apache-2.0（SQLite3 为 Public Domain，详见其官方许可）。