TidesDB列族操作详解:创建、删除、重命名与克隆的正确姿势
TidesDB列族操作详解:创建、删除、重命名与克隆的正确姿势
TidesDB 是一款面向 C 语言生态的高性能、写优化且空间优化的事务型存储引擎。它的列族(Column Family)操作——创建、删除、重命名与克隆——是管理数据库内多个独立键空间的四个核心能力。本文面向新手和普通用户,用最直白的方式讲清这 4 个 API 的用途、成本与常见坑,帮你避开错误姿势,安全地完成日常列族管理。
🧩 什么是列族?为什么需要它?
可以把数据库想象成一栋楼,而列族就是互相独立的"房间":
- 独立:每个列族有自己的存储层级、SSTable 文件和压缩(compaction)策略,写入密集的列族不会拖累只读密集的列族;
- 共享:所有列族共用同一份 memtable、预写日志(WAL)、值日志和块缓存——这正是跨列族事务能保持原子性的原因;
- 命名空间隔离:同一个 key 可以在不同列族中存放完全不同的值。
💡 设计建议:用列族隔离"形状或访问模式不同"的数据(比如小热元数据 vs 大冷大对象)。但不要把列族当 key 前缀的替代品——成百上千个列族并不是它的 intended 用法,单个列族内部用前缀划分几乎零成本。
⚡ 列族操作 API 速览
| API | 功能 | 磁盘开销 | 一句话成本 |
|---|---|---|---|
tidesdb_create_column_family |
创建列族 | 仅写一条 manifest 记录 | 极快,不建目录 |
tidesdb_drop_column_family |
删除列族及其全部数据 | 删除其 SSTable 文件 | 会等待进行中的 compaction 结束 |
tidesdb_rename_column_family |
重命名列族 | 零,不移动任何文件 | 微秒级,读写全程无感 |
tidesdb_clone_column_family |
克隆列族为新名字 | 复制全部 SSTable | 需先全库 flush,耗时正比于源体积 |
完整接口声明见 include/db.h,实现位于 src/db.c。
🆕 如何创建列族:默认配置 + 按需微调
创建分两步:先拿一份默认配置,再按需修改,最后调用创建函数。
第一步:获取默认配置
tidesdb_column_family_config_t cfg = tidesdb_default_column_family_config();
第二步:按需调整常用字段
| 配置字段 | 默认值 | 什么时候要改 |
|---|---|---|
enable_bloom_filter / bloom_fpr |
1 / 0.01 | 点查为主的列族保持开启,显著减少无效磁盘读 |
keep_values_inline |
0 | 扫描远多于合并的列族可置 1,值无论多大都完整留在键日志里 |
level_size_ratio |
10 | 相邻层级目标大小比例,一般无需动 |
default_isolation_level |
TDB_ISOLATION_READ_COMMITTED |
该列族上未显式指定隔离级别的事务默认走这个级别 |
l1_file_count_trigger |
4 | L1 文件数达到多少触发 compaction |
第三步:执行创建
int rc = tidesdb_create_column_family(db, "events", &cfg);
if (rc == TDB_ERR_EXISTS)
rc = TDB_SUCCESS; /* 已存在则视为成功 */
几个必须知道的行为细节:
- 名字规则:非空,最多 128 字节(含结尾符),重复名字会返回
TDB_ERR_EXISTS; - 并发安全:多个线程同时"查无则建"是安全的——恰好一个成功,其余拿到
TDB_ERR_EXISTS,此时重新查一次即可; - 配置被"借用":调用返回后你就可以释放自己的
cfg,引擎内部已自行复制。
⚠️ 如果你要在配置里填压缩编码管线(encoding_pipeline),先用 tidesdb_compression_available() 确认当前构建支持该算法,否则创建会返回 TDB_ERR_INVALID_ARGS。
🗑️ 如何删除列族:不可逆,且可能"慢半拍"
int rc = tidesdb_drop_column_family(db, "events");
删除是破坏性操作,数据不可恢复,调用前请确认:
- 它会等待该列族上正在进行中的 compaction 全部结束。列族正处于重度 compaction 时,这个调用可能耗时较久,生产环境请留足操作窗口;
- 句柄立即失效:之前通过
tidesdb_get_column_family拿到的该列族句柄在 drop 返回后全部作废,继续使用是未定义行为; - 找不到该列族时返回
TDB_ERR_NOT_FOUND,可据此判断是否已被别人删掉。
✏️ 如何重命名列族:零文件搬移的"秒改"
int rc = tidesdb_rename_column_family(db, "old_events", "new_events");
这是四个操作里最"轻"的一个,也是新手最容易误解的一个——重命名不移动任何文件:
- 列族的文件是按其不可变 id 命名的,与名字无关。重命名只改注册表索引和持久化配置,磁盘上一个字节都不动;
- 因此无需等待 flush、不阻塞写者,实测在活库上只要几十微秒,期间提交照常进行;
- 唯一可能的失败:若 compaction 长时间(最长约 60 秒窗口)占用该列族,会返回
TDB_ERR_LOCKED,稍后重试即可; - 新名字已存在会返回
TDB_ERR_EXISTS。
💡 心智模型:重命名 = 改索引,克隆 = 拷文件。前者微秒级,后者按数据量计费。
📦 如何克隆列族:带 flush 的时间点快照
int rc = tidesdb_clone_column_family(db, "events", "events_backup");
克隆会把源列族完整复制为一个新列族,但请记住它的三条特性:
- 先 flush 全库 memtable:因为克隆是拷文件,调用前的所有写入必须先落盘。由于全库只有一份 memtable,这次 flush 会带上所有列族的数据,克隆期间 flush 会被短暂挂起;
- 时间点拷贝:克隆返回后对源列族的写入不会出现在目标列族里,它不是实时同步;
- 成本与体积成正比:拷贝量等于源列族的磁盘大小,且需要等量的剩余空间。
继承关系上,目标列族继承源列族的全部配置,但不继承 commit hook——hook 是运行时注册,不随克隆传递。若源列族同样被 compaction 长时间占用,同样会收到 TDB_ERR_LOCKED。
🔍 加分项:查询与运行时改配置
除了增删改克隆,还有两个高频辅助操作:
- 查句柄:
tidesdb_get_column_family(db, "events")返回NULL表示不存在。注意返回的句柄是借用的——归数据库所有,到列族被删或数据库关闭前一直有效,绝不要 free; - 列名单:
tidesdb_list_column_families(db, &names, &count)返回快照,名字数组和数组本身都要用tidesdb_free(而非标准库free)逐层释放; - 改配置:
tidesdb_cf_update_runtime_config()可以在列族打开期间修改任意字段(键按字节序排,不同配置下写出的 SSTable 永远可合并),传persist_to_disk = 1可写入 manifest 持久化。该调用快速失败——若列族正被其他独占操作持有,立即返回TDB_ERR_LOCKED,重试即可。
✅ 列族操作最佳实践清单
- ✅ 按访问模式分列族:热小数据与冷大对象分开,互不干扰读放大;
- ✅ 创建失败收到
TDB_ERR_EXISTS时按"已存在"处理,再查一次句柄; - ✅ 重命名放心在生产时段做;克隆和删除要挑 compaction 空闲的窗口;
- ✅ 克隆前确认磁盘剩余空间 ≥ 源列族体积;
- ❌ 不要 free 列族句柄;不要创建海量列族来替代 key 前缀;
- ❌ 不要把克隆当备份方案长期依赖——它是时间点快照,事后写入不进克隆体。
📚 延伸阅读
- 列族操作完整参考:doc/04-reference/column-family.md
- 数据模型与列族设计原理:doc/02-concepts/data-model.md
- 列族配置结构体定义:include/db.h
- 列族操作实现源码:src/db.c
登录后查看全文
