TidesDB列族操作详解:创建、删除、重命名与克隆的正确姿势

原创2026-11-19 13:51:451,098 阅读

TidesDB列族操作详解:创建、删除、重命名与克隆的正确姿势

TidesDB 是一款面向 C 语言生态的高性能、写优化且空间优化的事务型存储引擎。它的列族(Column Family)操作——创建、删除、重命名与克隆——是管理数据库内多个独立键空间的四个核心能力。本文面向新手和普通用户,用最直白的方式讲清这 4 个 API 的用途、成本与常见坑,帮你避开错误姿势,安全地完成日常列族管理。

TidesDB 高性能事务型存储引擎 Logo(列族操作指南)

🧩 什么是列族?为什么需要它?

可以把数据库想象成一栋楼,而列族就是互相独立的"房间":

  • 独立:每个列族有自己的存储层级、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");

删除是破坏性操作,数据不可恢复,调用前请确认:

  1. 它会等待该列族上正在进行中的 compaction 全部结束。列族正处于重度 compaction 时,这个调用可能耗时较久,生产环境请留足操作窗口;
  2. 句柄立即失效:之前通过 tidesdb_get_column_family 拿到的该列族句柄在 drop 返回后全部作废,继续使用是未定义行为;
  3. 找不到该列族时返回 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");

克隆会把源列族完整复制为一个新列族,但请记住它的三条特性:

  1. 先 flush 全库 memtable:因为克隆是拷文件,调用前的所有写入必须先落盘。由于全库只有一份 memtable,这次 flush 会带上所有列族的数据,克隆期间 flush 会被短暂挂起;
  2. 时间点拷贝:克隆返回后对源列族的写入不会出现在目标列族里,它不是实时同步;
  3. 成本与体积成正比:拷贝量等于源列族的磁盘大小,且需要等量的剩余空间。

继承关系上,目标列族继承源列族的全部配置,但不继承 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 前缀;
  • ❌ 不要把克隆当备份方案长期依赖——它是时间点快照,事后写入不进克隆体。

📚 延伸阅读

登录后查看全文
tidesdb