DBX

SQL 文件执行

SQL 文件执行用于运行初始化脚本、数据库导出、数据补丁和迁移脚本。DBX 会先展示截断预览,再按文件选择顺序和语句顺序执行。

SQL 文件可以创建、修改或删除大量对象和数据。预览不是完整文件,不能用于证明脚本安全。执行前确认目标连接、数据库、文件顺序和脚本来源。

Desktop 和 Docker/Web

运行方式文件位置和处理
Desktop直接选择本机一个或多个 .sql 文件,并显示本地文件名或路径信息
Docker/Web浏览器选择文件后上传到 DBX 服务器临时目录;界面只展示用户选择的文件名,不暴露服务器临时路径

Docker/Web 中,脚本读取和执行发生在服务器端,文件完成或释放后会清理临时资源。它不能直接访问浏览器所在电脑上的任意路径。

执行流程

选择一个或多个文件

文件按照选择顺序排列。多文件模式左侧显示文件列表,点击可以切换右侧预览。

检查预览和文件信息

每个文件显示名称、大小、预览行数和截断状态。大文件只读取有限字符用于预览,完整内容仍会在执行时流式读取。

选择连接和数据库

一般需要选择目标数据库。如果脚本自身建立数据库上下文,例如前面的文件包含可识别的 USE,DBX 可以在支持的路径中允许不预选数据库。

配置错误策略并确认

默认遇到失败语句即停止;开启“遇错继续”后会记录失败并继续后续语句和文件。生产保护范围内会在执行前要求新的确认。

执行和查看结果

进度显示当前文件、语句序号、成功数、失败数、受影响行数、耗时、语句摘要和错误。多文件完成后会显示逐文件统计和总计。

引用其他 SQL 文件(桌面端)

执行本地 .sql 文件时,开启“解析 SQL 文件引用”,可以在完整语句之间插入单独一行引用:

CREATE TABLE example (id INTEGER PRIMARY KEY, name TEXT);
-- @include "shared/seed.sql"
INSERT INTO example VALUES (2, 'after include');

shared/seed.sql 在该行的位置执行,然后继续入口文件。被引用文件也可以引用其自身目录下的文件;多次引用同一文件会重复执行,而不是自动去重。只选择入口文件,不要额外选择已被引用的文件。引用边界使用与执行相同的分句器:SQL Server 以独立行 GO 结束批次,其他数据库使用对应的语句分隔符;被引用文件也必须结束完整语句或批次。

路径相对于包含该引用的文件,可以使用 / 或 \,含空格时使用单引号或双引号。只允许入口脚本目录及子目录中的 .sql 文件;绝对路径、..、非 SQL 文件、指向目录外的符号链接、循环引用均会被拒绝。字符串、带引号标识符和块注释中的引用文本不会展开,也不会执行 shell 命令。

DBX 在发送任何 SQL 前,流式解码并展开本批次全部引用到私有临时文件,结束、失败或取消后自动删除。每个文件分别识别 BOM;没有 BOM 时使用本次选择的编码或自动探测。总计最多 16 层、256 次文件读取、1 GiB 展开内容,单行最多 16 MiB。缺失文件或超限会中止整批执行;这不等于执行阶段自动回滚,事务和遇错继续仍遵循原有选项。

该选项默认关闭,不支持压缩文件、ZIP 分卷包、选表恢复及普通查询编辑器的“执行 SQL”。Docker/Web 不提供本地引用,并拒绝启用了引用的执行请求,防止脚本读取服务器上的其他文件。预览仍展示入口脚本,逐文件统计归属入口文件;当前语句、失败明细和返回错误以 [shared/seed.sql] 这样的相对来源路径标识实际脚本,失败日志也保留该信息。引用模式保留各语句的来源和错误边界,不合并相邻 INSERT。

多文件会话语义

多个文件属于同一个执行任务,按列表顺序运行。MySQL 兼容路径会在整个批次中复用同一条固定连接,因此前一个文件中的以下状态可以影响后续文件:

  • USE database
  • 临时表
  • Session 变量和设置
  • 显式事务

这使拆分的初始化或恢复脚本可以保持上下文,但也意味着文件顺序非常重要。不要把相互独立的脚本随意放入同一个批次。

语句分割和导入辅助语句

DBX 流式读取文件,并使用数据库感知的分割逻辑,而不是简单按每个分号拆分:

  • 字符串、行注释和块注释中的分号不会结束语句
  • PostgreSQL dollar-quoted 函数体会保持完整
  • SQL Server 的独立 GO 行作为批次边界
  • MySQL 例程使用的 DELIMITER 流程会被识别
  • MySQL executable comments 会按目标连接处理:MySQL 兼容路径展开可执行内容,其他连接跳过
  • ENABLE/DISABLE KEYS、LOCK/UNLOCK TABLES 和部分 session 恢复等导入辅助指令会按执行器策略处理或跳过

对于 MySQL 兼容目标,单条扩展 INSERT ... VALUES (...), (...) 超过 256 KiB 时会在行边界拆分后再执行:每个分片重复原始 INSERT INTO ... 前缀,并保持源文件中的行顺序。失败日志为控制占用,每条失败语句最多保存 4 MiB 文本(单次运行 200 MiB);该上限只作用于日志,DBX 始终把完整语句发送给数据库。

数据库方言和脚本生成工具差异很大。复杂脚本仍应先在测试环境验证,尤其是自定义分隔符、客户端专属命令和数据库管理工具生成的元命令。

错误策略

遇错停止

默认模式在第一条失败语句后结束整个任务。界面保留已经完成的统计、失败语句摘要和数据库错误。

遇错继续

开启后,DBX 记录失败并继续后续语句。多文件模式也会继续下一个文件,并在结束时给出每个文件的成功数、失败数、受影响行数和耗时。

“遇错继续”只改变任务控制流,不会修复事务状态。某些数据库在事务内发生错误后要求显式回滚,后续语句仍可能连续失败。

取消和事务

取消会停止后续语句,但已经发送或提交到数据库的语句不会自动撤销。如果脚本需要整体原子性,应由脚本显式控制事务,并确认目标数据库、DDL 和导入语句都具备所需事务语义。

多文件共享会话时,未提交事务可能跨文件延续。确保脚本包含清晰的 BEGIN、COMMIT 或 ROLLBACK,不要依赖关闭对话框自动提交或回滚。

数据库覆盖范围

该入口按驱动的 sqlFileExecution 能力显示。大多数 SQL 型驱动启用;Redis、MongoDB、搜索、向量、HBase、配置中心和消息队列等专用工作区不会执行关系型 SQL 文件。

能够运行查询不一定表示所有客户端脚本语法都受支持。psql、mysql、sqlcmd 或其他工具特有的元命令可能需要先转换成数据库服务器可以直接执行的 SQL。

执行前检查

  • 文件顺序和数据库上下文是否正确
  • 预览是否被截断,是否已用编辑器审阅完整文件
  • 是否包含 DROP、TRUNCATE、无条件 UPDATE / DELETE、用户权限或配置变更
  • “遇错继续”是否会掩盖关键失败
  • 目标连接是否开启只读或生产保护
  • 是否需要先做 数据库导出 或 数据库备份

相关功能