Convex 自托管数据清理完全指南：用空快照导入安全重置数据库

数据库后端【免费下载链接】convex-backendThe open-source reactive database for app developers项目地址https://gitcode.com/gh_mirrors/co/convex-backend点击查看免费下载数据清除Clearing Data是自托管 Convex 部署运维中最常被问到的问题之一如何在不销毁 Docker 卷、不重新部署的前提下把数据库里的数据清零本文基于 convex-backend 仓库中 self-hosted/advanced/clearing_data.md 的官方指引结合 CLI 与后端源码系统讲解自托管 Convex 的清库机制——为什么没有一键 reset 命令、如何备份、如何按表/全量/按组件清除数据以及底层快照导入引擎是如何保证这一过程原子且可恢复的。读完本文你将能安全、可复现地完成自托管部署的数据重置并理解每一步背后的实现原理。为什么 Convex 不提供一键重置数据库原文档明确指出Convex 刻意不提供单一破坏性的 reset database 命令。这是一个深思熟虑的设计决策而非功能缺失。原因在于一条reset命令太容易被误执行且往往伴随着删库重来式的不可控副作用例如需要重建 Docker 卷、重新初始化存储、重新部署代码。Convex 采用的替代方案是用一次空快照导入来替换表的数据。这样做有三个关键收益不清除 Docker 卷不需要停止容器、删除卷或重新 provision 部署保留 schema 与函数清的是表里的文档数据表结构schema和你在convex/下编写的查询、变更、action 等函数全部原样保留复用成熟的数据导入通道清除操作与日常的npx convex import走同一条经过充分验证的快照导入链路行为可预期、可审计。从源码看这条链路在 CLI 侧由 npm-packages/convex/src/cli/lib/convexImport.ts 的importIntoDeployment驱动在后端由 crates/application/src/snapshot_import/mod.rs 的导入执行器完成。后文会展开讲这一机制的细节。备份与前置检查不可跳过清除数据是不可逆操作动手之前请完成以下两步第一步先备份原文档要求在执行任何清除操作前先导出备份npx convex export --path backup.zipexport命令会把当前部署的数据打包成 ZIP内部格式为每个表一个目录内含documents.jsonl见下文--format zip的说明。备份文件应存放在安全位置并确认其非空、可重新导入。第二步确认目标部署所有清除命令都作用于CONVEX_SELF_HOSTED_URL所指向的部署。在运行全表清除之前务必确认该环境变量指向你真正想要清空的部署echo $CONVEX_SELF_HOSTED_URL这一点至关重要同一条一行式命令如果误对生产部署执行会摧毁它的全部数据。原文档对此给出了明确的警告。对于自托管部署CONVEX_SELF_HOSTED_URL与CONVEX_SELF_HOSTED_ADMIN_KEY通常一起配置参见 self-hosted/README.md管理命令通过它们认证到目标后端。另外注意文档中--replace -y被反复强调为不可逆因为--replace会替换目标表中的全部现有数据而-y会跳过确认提示。清除单个表清除一张表的数据本质上就是导入一个空文件到这个表并替换其内容npx convex import --table $tableName --replace --format jsonLines /dev/null -y各参数含义如下与 CLI 定义一致见 npm-packages/convex/src/cli/lib/command.ts参数作用--table $tableName目标表名。csv / jsonLines / jsonArray 格式下为必填项zip 格式下不允许使用--replace替换该表中全部现有数据与--append、--replace-all互斥--format jsonLines输入文件格式取值csv、jsonLines、jsonArray、zip之一/dev/null空输入文件读取到的字节数为 0等价于零条记录-y, --yes跳过导入将删除现有文档的确认提示为什么这里必须显式传--format jsonLines因为 CLI 会先尝试从文件扩展名推断格式见 convexImport.ts 的determineFormat.csv→ csv、.jsonl→ jsonLines、.json→ jsonArray、.zip→ zip而/dev/null没有任何扩展名无法推断若不显式指定格式CLI 会直接报错No input file format inferred by the filename extension or specified。关于 /dev/null 的平台差异/dev/null是 Linux 与 macOS 上的空设备文件天然可用作空导入文件。但WindowsPowerShell没有/dev/null此时需要先创建一个真正的空文件再引用它例如New-Item -ItemType File -Name empty.jsonl npx convex import --table $tableName --replace --format jsonLines empty.jsonl -yCLI 侧会调用ctx.fs.exists(filePath)校验文件存在convexImport.ts因此必须确保传入的路径真实存在。清除应用中的全部表清除整个应用所有用户表的数据原文档给出的一行式命令如下for tableName in npx convex data; do npx convex import --table $tableName --replace -y --format jsonLines /dev/null; done这条命令分两步协作枚举表名npx convex data不带表名参数时列出部署中所有表。CLI 侧通过系统函数_system/cli/tables分页查询表清单并排序输出见 npm-packages/convex/src/cli/lib/data.ts每个表名占一行正好作为for循环的迭代项逐表清空对每个表执行一次空文件 --replace导入即前文介绍的清除单个表。这条命令会遍历所有表逐一执行因此对目标部署的数据是破坏性的——这正是为什么原文档要求先确认CONVEX_SELF_HOSTED_URL指向正确且命令后附-y跳过确认。建议在实际执行前先只跑npx convex data观察输出确认表清单符合预期。清除组件Component中的全部表使用 Convex Components 的应用表是挂在组件命名空间下的清除方式需要同时指定组件路径for tableName in npx convex data --component $component; do npx convex import --component $component --table $tableName --replace -y --format jsonLines /dev/null; done与上一节相比有两处变化枚举时限定组件npx convex data --component $component只列出该组件下的表其中$component是组件路径例如workflow或workflow/workpool见 command.ts 对--component的说明导入时同样限定组件npx convex import --component $component ...把空导入定向到对应组件的命名空间。底层原理清除如何通过快照导入实现后端核心实现clear_tables后端为清空表提供了专门的原子实现clear_tables位于 crates/application/src/snapshot_import/mod.rs其文档注释直接揭示了设计本质Clears tables atomically. This is implemented as an import of empty tables in Replace mode.也就是说清空一张表 创建一张同名空表create_empty_table然后以Replace 模式完成导入最终由finalize_import把旧表替换掉。注释还特别提醒了一个边界行为N.B.: This will create components and tables if they dont exist.—— 如果组件或表本身不存在清除操作会顺带创建它们因此目标名务必写对。三种导入模式与互斥关系CLI 在 convexImport.ts 中把模式映射为三类requireEmpty默认目标表必须为空才能导入append把数据追加到现有表replace替换目标表中的全部数据清空命令使用此模式replaceAll全量替换整个部署删除未出现在导入文件或 schema 中的表。CLI 层通过.conflicts(...)强制了--replace、--append、--replace-all三者互斥command.ts避免语义冲突。写入隐藏表原子切换快照导入并非直接把数据写进活动表。根据 mod.rs 的模块注释整个流程是parse_import解析导入文件得到ParsedImport同时保存当前数据库的 schema 副本import_objects把数据写入隐藏表hidden tablesappend模式除外期间用模拟的表映射校验 schema 约束finalize_import在单个事务内删除被替换的表并把隐藏表提升promote为活动表随后再做一轮 schema 检查见 schema_constraints.rs与表号唯一性校验最终通过TableModel::activate_tables完成切换。这套先写隐藏表、后原子切换的设计保证了即使导入中途失败也不会留下半清空的活动表--replace语义对客户端而言是全有或全无。这也是为什么清库可以放心复用导入通道——它本质上是导入引擎的一个特例导入内容为空。后台执行与状态机导入在服务端是异步执行的。后端有独立的SnapshotImportWorkercrates/application/src/snapshot_import/worker.rs它订阅_snapshot_imports表将处于Uploaded状态的导入解析为WaitingForConfirmation将InProgress的导入交给SnapshotImportExecutor执行失败时按 30 秒起步、最长 300 秒的退避策略重试。CLI 侧对应的状态机是uploaded → waiting_for_confirmation → in_progress → completed / failedconvexImport.ts。waiting_for_confirmation状态下 CLI 会打印确认信息只有在传了-y或服务端判定无需人工确认时才自动继续——这也解释了文档命令中-y的用途。上传链路与分块参数CLI 通过三个 REST 端点完成文件上传/api/import/start_upload获取上传令牌、/api/import/upload_part逐块上传、/api/import/finish_upload提交导入参数与分块令牌convexImport.ts。默认分块大小为 5 MiB后端除最后一块外的最小分块要求可通过环境变量CONVEX_IMPORT_CHUNK_SIZE字节覆盖同时后端拒绝 10,000 个及以上的分块CLI 会据此自动放大块大小convexImport.ts。对清库场景而言空文件只有零字节这些参数影响不大但了解它们有助于理解导入链路的健壮性设计。参数速查与注意事项参数说明--table table目标表名csv / jsonLines / jsonArray 格式必填--replace替换目标表全部数据与--append、--replace-all互斥--replace-all用导入文件替换整个部署删除未出现的表、清空 schema 中但未出现在导入文件的表--append追加数据到现有表-y, --yes跳过删除现有文档前的确认提示--format formatcsv/jsonLines/jsonArray/zip文件名无扩展名时必填--component path组件路径如workflow或workflow/workpoolCONVEX_IMPORT_CHUNK_SIZE覆盖上传分块大小字节默认 5 MiB实践要点汇总先备份npx convex export --path backup.zip先核对echo $CONVEX_SELF_HOSTED_URL与npx convex data的输出理解不可逆--replace-y意味着零确认直接清空请仅在确认无误的部署上执行注意平台差异Windows 下用真实空文件替代/dev/null善用验证npx convex import --help可查看当前 CLI 版本的实际 flag 行为本文命令已在convexlatest2026-06 版本验证遗留数据排查清除只针对文档数据若需要彻底清理文件存储等请结合 s3_storage.md、knobs.md 等高级配置文档评估。最后提醒这些命令面向的是自托管部署CONVEX_SELF_HOSTED_URLCONVEX_SELF_HOSTED_ADMIN_KEY认证方式与云托管部署的认证模型不同。若你的自托管后端以 Docker Compose 方式运行可参考 self-hosted/README.md 与 docker/docker-compose.yml 确认环境变量配置无误后再执行清库操作。赞分享数据库后端【免费下载链接】convex-backendThe open-source reactive database for app developers项目地址https://gitcode.com/gh_mirrors/co/convex-backend点击查看免费下载相关推荐Apache Paimon 数据快照管理完全指南Apache Paimon 数据快照管理完全指南 什么是数据快照 在 Apache Paimon 中数据快照 Snapshot 是表在某一时刻完整状态的记录。数据湖湖仓一体大数据流处理TuGraph数据库数据导入完全指南TuGraph数据库数据导入完全指南 引言 TuGraph作为一款高性能的图数据库提供了强大的数据导入功能能够帮助用户快速将各类数据源导入数据库。本文将全面数据库图数据库图计算后端ToolJet 内置数据库ToolJet Database完全指南零配置托管数据库、PostgREST 架构与数据管理实战ToolJet 内置数据库ToolJet Database完全指南零配置托管数据库、PostgREST 架构与数据管理实战 ToolJet Databas低代码后端前端AI 应用MCP 服务创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考