SQL File Execution
SQL File Execution runs initialization scripts, database exports, data patches, and migrations. DBX shows a truncated preview first, then executes files in selection order and statements in script order.
Desktop and Docker/Web
| Runtime | File location and handling |
|---|---|
| Desktop | Selects one or more local .sql files directly and can display local filename or path information |
| Docker/Web | Uploads browser-selected files into temporary DBX server storage; the UI shows the selected names instead of server UUID paths |
In Docker/Web, reading and execution happen on the server. Temporary resources are released after the operation. The server cannot directly open arbitrary paths from the computer running the browser.
Workflow
Select One or More Files
Files remain in selection order. Multi-file mode shows a side list; select an item to switch the preview pane.
Review Preview and File Details
Each file reports its name, size, preview lines, and truncation state. Large files read only a limited preview, while execution still streams the complete content.
Select Connection and Database
A target database is normally required. When the script establishes database context itself, such as an earlier recognizable USE, DBX can allow execution without a preselected database on supported paths.
Choose Error Policy and Confirm
Execution stops on the first failure by default. Continue on error records failures and proceeds to later statements and files. Protected production contexts require a fresh confirmation before execution.
Run and Inspect Results
Progress includes the current file, statement index, success and failure counts, affected rows, elapsed time, statement summary, and error. Multi-file runs finish with per-file statistics and totals.
Include Other SQL Files (Desktop)
For local .sql execution, enable Resolve SQL file includes and place a directive on its own line between complete statements:
CREATE TABLE example (id INTEGER PRIMARY KEY, name TEXT);
-- @include "shared/seed.sql"
INSERT INTO example VALUES (2, 'after include');The referenced script runs at the directive's position, then execution resumes in its caller. Nested paths resolve relative to the containing file. Repeated references execute repeatedly; select only entry files, not their dependencies. Include boundaries use the same splitter as execution: SQL Server batches end with a standalone GO line, while other databases use their own statement delimiters. Included files must end a complete statement or batch.
Paths accept / or \; quote paths containing spaces with single or double quotes. Only .sql files beneath the entry script directory are allowed. Absolute paths, .., non-SQL files, symlinks escaping that directory, and cycles are rejected. Include-looking text inside strings, quoted identifiers, or block comments stays literal. No shell commands are executed.
Before sending SQL, DBX streams and decodes every reference in the batch into private temporary files, automatically removed after completion, failure, or cancellation. Each file's BOM takes precedence; otherwise the selected encoding or automatic detection applies. Limits are 16 levels, 256 file visits, 1 GiB expanded text, and 16 MiB per line. Missing files or exceeded limits stop preparation before execution; execution errors still follow the existing transaction and continue-on-error options, not an implicit batch rollback.
Includes are off by default and unavailable for compressed files, split ZIP packages, selected-table restore, or ordinary query-editor execution. Docker/Web hides the option and rejects include-enabled requests to prevent access to other server files. Preview shows the entry script and per-file statistics stay under that entry file. Current statements, failure details, returned errors, and failure logs identify the actual relative source with a prefix such as [shared/seed.sql]. Include mode preserves individual source/error boundaries instead of merging adjacent INSERT statements.
Multi-File Session Semantics
Selected files form one execution task and run in list order. MySQL-compatible paths reuse one pinned connection across the complete batch, so state established by an earlier file can affect later files, including:
USE database- Temporary tables
- Session variables and settings
- Explicit transactions
This supports split initialization and restore scripts, but makes ordering significant. Do not batch unrelated scripts when session state could leak between them.
Statement Splitting and Import Helpers
DBX reads files as a stream and uses database-aware splitting instead of breaking at every semicolon:
- Semicolons inside strings, line comments, and block comments do not terminate a statement
- PostgreSQL dollar-quoted function bodies remain intact
- Standalone SQL Server
GOlines split batches - MySQL routine
DELIMITERworkflows are recognized - MySQL executable comments are unwrapped for compatible targets and skipped for other targets
- Import helpers such as
ENABLE/DISABLE KEYS,LOCK/UNLOCK TABLES, and selected session-state restoration directives are handled or skipped by executor policy
For MySQL-compatible targets, a single extended INSERT ... VALUES (...), (...) larger than 256 KiB is split at row boundaries before execution. Each part repeats the original INSERT INTO ... prefix and keeps the source row order. The failure log captures at most 4 MiB of text per failed statement (200 MiB per run) for storage; that cap applies to the log only — DBX always sends the complete statement to the database.
Database dialects and script generators vary widely. Test complex scripts first, especially those containing custom delimiters, client-only commands, or meta-commands generated by administration tools.
Error Policy
Stop on Error
The default ends the task after the first failed statement. DBX retains completed statistics, the failed statement summary, and the database error.
Continue on Error
When enabled, DBX records a failure and proceeds. Multi-file tasks also move to the next file and report success count, failure count, affected rows, and elapsed time for each file.
Cancellation and Transactions
Cancellation stops later statements, but statements already submitted or committed are not reverted automatically. If the script must be atomic, control transactions explicitly and verify that the target engine, DDL, and import statements provide the required semantics.
With a shared multi-file session, an open transaction can continue across file boundaries. Use clear BEGIN, COMMIT, or ROLLBACK statements instead of relying on closing the dialog to commit or roll back.
Database Coverage
The action follows the driver's sqlFileExecution capability. Most SQL-oriented drivers enable it. Specialized Redis, MongoDB, search, vector, HBase, configuration-center, and message-queue workspaces do not execute relational SQL files.
Query execution support does not guarantee compatibility with every client script language. Meta-commands specific to psql, mysql, sqlcmd, or another client may need conversion into SQL the database server accepts directly.
Before Running
- Verify file order and database context
- Check whether previews are truncated and review the complete files in an editor
- Look for
DROP,TRUNCATE, unqualifiedUPDATE/DELETE, privilege changes, or configuration changes - Decide whether continue-on-error could hide a critical failure
- Check read-only and production protection on the target
- Create a Database Export or Database Backup first when appropriate
Related Features
Table Import
Use a guided workflow to import CSV, TSV, text, JSON, Excel, SQL, or DuckDB Parquet data into an existing table or create new tables in batches, and restore Navicat .nb3 backups into a database.
Database Export
Stream structure, data, and readable database objects from one or more databases into SQL files.