DBX

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.

SQL files can create, modify, or remove large amounts of data and schema. The preview is not the complete file and cannot prove a script is safe. Verify the target connection, database, file order, and source before execution.

Desktop and Docker/Web

RuntimeFile location and handling
DesktopSelects one or more local .sql files directly and can display local filename or path information
Docker/WebUploads 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 GO lines split batches
  • MySQL routine DELIMITER workflows 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.

Continue on error changes task control flow only. It does not repair transaction state. Some databases require an explicit rollback after a transaction error, so later statements may continue failing.

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, unqualified UPDATE / 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