Import

Use LOAD to insert records from a UTF-8 CSV file into an existing table on the current connection. Start with a preview, review the target and converted values, then authorize the import. LOAD does not create tables, update existing rows, or perform an upsert.

See the LOAD command reference for exact arguments and examples, and Export for moving query results into files or local H2 databases.

Basic workflow

Connect to the intended database and inspect the target table with DESCR. Prepare a CSV file whose first row names the columns to insert. For example, for an existing CUSTOMER table with integer ID, text NAME, and decimal CREDIT columns, save this as customer.csv in DefaultFolder:

ID;NAME;CREDIT
101;Alice;12.50
102;"O'Brien; Ltd";NULL
103;"The ""Corner"" Shop";0

Preview without writing:

LOAD CUSTOMER customer.csv PREVIEW;

Check the connection, qualified target table, source file, column types, and valid/rejected row counts in the preview. Correct every reported problem. Then run the plain command for an interactive confirmation:

LOAD CUSTOMER customer.csv;

The default answer to Load N rows into TABLE? [y/N] is No. Answer y or yes to insert. To explicitly authorize execution without a prompt:

LOAD CUSTOMER customer.csv EXECUTE;

Each invocation reads and validates the file again. A preview does not freeze a file for a later execution. Successful execution reports the inserted row count and that the transaction committed. Running the import again attempts another insert of the same rows; there is no automatic deduplication.

CSV input and file paths

The input is CSV, including CSV saved from Excel or LibreOffice Calc. LOAD does not read XLSX or ODS files directly. Use UTF-8 encoding and a mandatory header row.

• The delimiter is CsvSeparator in BroadSQL.ini, a semicolon by default. It is independent of FieldsSeparator and SET SEPARATOR. Match the file's delimiter to this setting.
• Double quotes delimit fields containing the separator or embedded line breaks. Double an embedded quote, as in "The ""Corner"" Shop". Apostrophes need no SQL escaping.
• Surrounding spaces outside quoted fields are ignored. A leading BOM on the first header is removed before column matching. Duplicate header names are rejected by the CSV parser.
• Keep exactly one field per header in each record. The current validator treats missing trailing fields like empty values and ignores fields beyond the header count; preview does not reject those row-width differences.
• A bare file name is resolved under DefaultFolder. A path containing the operating system's directory separator is used as supplied. For example, on Windows:

LOAD CRM.CUSTOMER c:\temp\customer.csv PREVIEW;

The source must already exist. See Application settings for the folder and separator.

Target table and column matching

Use TABLE or SCHEMA.TABLE. BroadSQL resolves the name against the connected database's metadata, requiring a case-insensitive exact match. An unqualified name uses the connection's current schema when available. A missing or ambiguous table is refused; qualify it with the schema when needed.

Header names select target columns by name, not by table column position. An exact case-sensitive match wins; otherwise a unique case-insensitive match is accepted. Unknown or ambiguous headers refuse the entire import. Reordering CSV columns is fine when each value stays under its header. Do not use different spellings of the same column as separate headers.

A target column absent from the header is omitted from the INSERT, allowing a database default or generated value to apply. This does not guarantee that an omitted required column is acceptable: the database still enforces its constraints during execution.

Validation and type conversion

PREVIEW checks column mapping and converts values using target JDBC column types. Any unmapped header or conversion failure prevents the entire load, including otherwise valid rows. The summary shows row counts and up to 25 conversion diagnostics, with source row, column, target type, offending value and reason.

Prefer numeric ISO-style dates (2026-09-12) to avoid locale-dependent month names. Date parsing is not a strict calendar-validity check. Preview also does not simulate primary keys, foreign keys, uniqueness, length limits, permissions, triggers, or every database constraint.

NULL, empty and omitted values

• The whole token NULL, case-insensitively and after trimming, binds SQL NULL for every type. Quoting "NULL" in the CSV does not preserve it as literal text.
• An empty field becomes an empty string for supported character types and SQL NULL for other types. The database may apply its own empty-string semantics.
• Omitting a column from the header differs from supplying an empty field: omission lets the database apply a default, while an empty field supplies the value described above.

Execution, transactions and failure

LOAD binds values through JDBC parameters. It uses metadata-resolved table and column names and does not concatenate imported values into SQL. JDBC batching is an internal execution detail: there is one commit after all batches succeed, with no commit at batch boundaries.

On a SQL execution failure, LOAD attempts to roll back the import. With a working transactional connection, earlier successful batches are rolled back too. Database constraint failures are reported during execution even when preview passed. Batch errors identify the source-row range; an individual failure location can be approximate because JDBC drivers report different details.

Finish unrelated transaction work before loading. LOAD uses the active JDBC connection and explicitly commits or rolls it back even when autocommit was already off. It does not use an isolated connection or savepoint, so pending work on that connection participates in the same commit or rollback. It attempts to restore the prior autocommit setting afterward. Rollback and restoration cannot be guaranteed if the database or connection fails.

Using LOAD in scripts

In @<file> and SCRIPT RUN scripts, use PREVIEW for validation only or EXECUTE to authorize insertion. Plain LOAD refuses to write inside these scripts rather than waiting for confirmation. This refusal does not itself guarantee that subsequent script lines stop running.

LOAD CRM.CUSTOMER customer.csv PREVIEW;
LOAD CRM.CUSTOMER customer.csv EXECUTE;

The second line validates again; it is not conditional on a human reviewing the first line. For a manual review step, run preview separately before starting the execution script.

Migration from older versions

BATCHLOAD is deprecated; use LOAD for new imports. The compatibility adapter routes to the same INSERT engine and prints a deprecation notice. LOAD CREATE <table> <file> remains accepted as an insert into an existing table, but LOAD UPDATE is rejected. Old scripts must explicitly use EXECUTE to authorize a write.

Limits

LOAD reads and validates the complete file in memory before execution; internal JDBC batching does not make it a streaming file reader. Use files sized for the available memory. Updates, upserts, automatic duplicate resolution, resumable imports, direct spreadsheet loading, and vendor-specific bulk loaders are not part of this command.