# SQL 文件执行

> 预览并按顺序执行一个或多个 SQL 文件，查看逐文件统计、语句进度和失败结果。

Source: https://dbxio.com/cn/docs/sql-file

Language: zh-CN

Relative links resolve against https://dbxio.com/cn/docs/sql-file.



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

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

## Desktop 和 Docker/Web

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

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

## 执行流程

### 选择一个或多个文件

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

### 检查预览和文件信息

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

### 选择连接和数据库

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

### 配置错误策略并确认

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

### 执行和查看结果

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

## 多文件会话语义

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

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

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

## 语句分割和导入辅助语句

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

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

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

## 错误策略

### 遇错停止

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

### 遇错继续

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

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

## 取消和事务

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

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

## 数据库覆盖范围

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

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

## 执行前检查

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

## 相关功能

### [数据库导出](/cn/docs/database-export)

生成结构、数据和对象 SQL 文件。

### [数据库备份](/cn/docs/database-backup)

为 MySQL 和 PostgreSQL 配置 Desktop 定时备份。

### [生产环境安全](/cn/docs/production-safety)

了解执行前确认、只读保护和权限边界。