Import & Export

Foundry provides commands for importing CSV data into database tables and exporting table data or schema definitions back to files.

foundry import has two subcommands:

foundry import table [options]    # one CSV file into an existing table
foundry import schema [options]   # a whole .csvx package into a new schema

Import

foundry import table reads a CSV file and inserts its rows into a target table that already exists.

foundry import table [options]

Required Options

Option	Short	Description
--datasource <FILE>	-d	Datasource JSON file
--conn <STRING>	-c	ADO.NET connection string
--db <TYPE>	-b	Database engine type
--schema <NAME>	-s	Target schema name
--table <NAME>	-t	Target table name
--file <FILE>	-f	Path to the CSV file to import

CSV Format Options

Option	Short	Default	Description
--delimiter <CHAR>	-D	,	Field delimiter character
--quote-char <CHAR>	-q	"	Quote character for fields containing the delimiter
--escape-char <CHAR>	-E	unset	Character escaping a quote inside a quoted field. Unset reads a doubled quote as one
--line-terminator <STRING>	-n	unset	Row terminator. Unset ends a row at either line ending
--encoding <NAME>	-C	unset	Encoding the file is read as. Unset reads it as UTF-8
--number-separator <STRING>	-S	none	Thousands separator stripped from numeric values before parsing
--no-headers	-H		CSV has no header row

Data Options

Option	Short	Description
--keep-identity	-k	Insert identity/auto-increment values from the file as-is
--no-full-text-update	-u	Skip full-text index update after import
--import-config <FILE>	-i	JSON file with detailed import settings (overrides CSV format flags)
--stream	-r	Stream the import instead of loading the whole file into memory first

Date & Time Format Options

Option	Short	Default	Description
--date-format <FORMAT>	-a	yyyy-MM-dd	Date format string
--time-format <FORMAT>	-m	HH:mm:ss	Time format string
--interval-format <FORMAT>	-N	c	Interval/TimeSpan format string
--datetime-format <FORMAT>	-y	yyyy-MM-dd HH:mm:ss	DateTime format string
--timestamp-format <FORMAT>	-Y	yyyy-MM-dd HH:mm:ss zzz	DateTimeOffset format string

Examples

# Basic import
foundry import table \
  --datasource connection.json \
  --schema dbo --table customers \
  --file data/customers.csv

# Semicolon-delimited file with European date format
foundry import table \
  --datasource MySql_8.4.json \
  --schema sales --table orders \
  --file data/orders.csv \
  --delimiter ";" \
  --date-format "dd/MM/yyyy"

# Using an import configuration file
foundry import table \
  --datasource PostgreSQL_17.6.json \
  --schema public --table events \
  --file data/events.csv \
  --import-config import-config.json

# Inline connection with identity preservation
foundry import table \
  --conn "Server=localhost;Database=mydb;User Id=sa;Password=pass" \
  --db SQLServer \
  --schema dbo --table products \
  --file data/products.csv \
  --keep-identity

# Numbers written with thousands separators (e.g. 1,450)
foundry import table \
  --datasource connection.json \
  --schema dbo --table sales \
  --file data/sales.csv \
  --delimiter ";" \
  --number-separator ","

# Streaming a large file instead of loading it into memory first
foundry import table \
  --datasource connection.json \
  --schema dbo --table events \
  --file data/events_10m_rows.csv \
  --stream

Note

When --import-config is specified, it takes full precedence over all CSV format flags (--delimiter, --quote-char, etc.).

Numbers With Thousands Separators

By default, numeric values in the CSV must parse as-is — a value like 1,450 fails, because the comma isn't part of a valid number. --number-separator supplies a string that is stripped from numeric columns before parsing, so 1,450 is read as 1450:

foundry import table --datasource connection.json --schema dbo --table sales \
  --file data/sales.csv --number-separator ","

Stripping applies only to numeric columns (byte, short, integer, long, float, double, decimal) — text columns are left untouched, so a comma inside a varchar value is preserved. The separator is a string rather than a single character, and may be a space for locales that format numbers as 1 450:

foundry import table --datasource connection.json --schema dbo --table sales \
  --file data/sales.csv --number-separator " "

Note

If your separator is also your field delimiter (a comma in a comma-delimited file), the numeric fields must be quoted in the CSV — otherwise 1,450 is parsed as two separate fields before the separator is ever considered. Using a different --delimiter (e.g. ;) avoids the ambiguity entirely.

Streaming Large Files

By default, Foundry parses the whole CSV into memory before sending any of it to the database, so peak memory use scales with the size of the file. --stream reads the file in chunks instead, sending each one as it's read, so peak memory follows the chunk size rather than the file size — the rows that end up in the table, their order, and every ImportConfig setting (mappings, formats, --keep-identity, etc.) are unaffected.

foundry import table --datasource connection.json --schema dbo --table events \
  --file data/events_10m_rows.csv --stream

The chunk size is the datasource's importBatchSize setting (rows, not bytes) — see foundry-syntax.md, or override it per-connection via --context "ImportBatchSize=500" for files with wide rows (e.g. large geometry or text columns). Use --stream for files large enough that holding them in memory matters — as a rule of thumb, anything above a few tens of megabytes, or any file whose size you don't control; for small files the non-streamed default is marginally faster.

Character encoding

Files are read as UTF-8 and written as UTF-8 without a byte order mark unless encoding specifies otherwise.

On import, a byte order mark takes precedence over encoding. A file beginning with a UTF-8, UTF-16 or UTF-32 mark is read as that encoding regardless of the configured value.

encoding is required for files that are not UTF-8 and contain no byte order mark, typically legacy single-byte code pages. Such files carry no indication of their encoding. Read as UTF-8, every byte above 127 is decoded as U+FFFD and the import completes without error.

# Read as UTF-8. Accented characters are replaced.
foundry import table --datasource ds.json --schema sales --table city --file legacy.csv

# Read as Windows-1252.
foundry import table --datasource ds.json --schema sales --table city --file legacy.csv --encoding windows-1252

On export, encoding determines both the character set and whether a byte order mark is written. Spreadsheet applications that open a CSV file directly assume the local code page unless the file begins with a mark.

foundry export data --datasource ds.json --schema sales --table city --out city.csv --encoding utf-8-bom

Accepted values

Value	Byte order mark	Notes
utf-8	No	Equivalent to unset
utf-8-bom	Yes	Required by spreadsheet applications opening the file directly
utf-16, utf-16le	Yes	Little-endian
utf-16be	Yes	Big-endian
utf-32, utf-32le, utf-32be	Yes
windows-1252	No	Western European code page
iso-8859-1	No	Latin-1. Not equivalent to windows-1252
ascii	No
Code page number, for example 1252	Per code page	Any code page installed on the host

utf-8 and utf-8-bom are separate values because the byte order mark is the only difference between them on export.

iso-8859-1 and windows-1252 differ in the range 0x80 to 0x9F, which encodes curly quotes, en dashes and ellipses. Use windows-1252 for files produced by Windows applications.

An unrecognized value is rejected before the operation begins. The error lists the accepted values.

Import Config File Reference

An import config file (validated against schemas/import-config.schema.json) covers everything the CSV format flags cover, plus two capabilities with no CLI flag equivalent: explicit column mappings and per-column blob handling.

Field	Type	Default	Description
delimiter	string (1 char)	,	Field delimiter
quoteChar	string (1 char)	"	Quote character for fields containing the delimiter
escapeChar	string (1 char)	unset	Character escaping a quote inside a quoted field. Unset reads a doubled quote as one.
lineTerminator	string	unset	Row terminator. Unset ends a row at either line ending.
encoding	string	unset	Encoding the file is read as. Unset reads it as UTF-8.
numberSeparator	string	""	Thousands separator stripped from numeric values before parsing (e.g. "," for 1,450)
useColumnHeaders	boolean	true	The first CSV row contains column header names
keepIdentity	boolean	false	Insert identity/auto-increment values from the CSV as-is
updateFullTextIndex	boolean	true	Rebuild full-text indexes on the target table after import
dateFormat	string	yyyy-MM-dd	.NET format string for date-only columns
timeFormat	string	HH:mm:ss	.NET format string for time-only columns
intervalFormat	string	c	.NET format string for interval/TimeSpan columns
dateTimeFormat	string	yyyy-MM-dd HH:mm:ss	.NET format string for DateTime columns
timestampFormat	string	yyyy-MM-dd HH:mm:ss zzz	.NET format string for DateTimeOffset/timestamp columns
blobs	array	—	Per-column blob handling rules (see below)
mappings	array	auto-generated	Explicit CSV-header-to-table-column mappings (see below)

Blob handling. Each entry in blobs needs a column and a handling of base64 (decode the CSV field from Base64) or file (treat the CSV field as a file path and read the blob from disk, using a pattern with {column_name} token substitution):

{
  "blobs": [
    { "column": "photo", "handling": "base64" },
    { "column": "document", "handling": "file", "pattern": "blobs/{document}" }
  ]
}

Column mappings. When mappings is omitted, Foundry auto-generates a mapping from the table definition, assuming the CSV header names match the column names exactly. Use mappings to map differently-named CSV headers to table columns; header defaults to column when omitted:

{
  "mappings": [
    { "header": "Customer Name", "column": "customer_name" },
    { "header": "Order Total", "column": "total" }
  ]
}

Full example:

{
  "$schema": "schemas/import-config.schema.json",
  "delimiter": ";",
  "dateFormat": "dd/MM/yyyy",
  "blobs": [
    { "column": "photo", "handling": "base64" }
  ],
  "mappings": [
    { "header": "Customer Name", "column": "customer_name" }
  ]
}

---

Import Schema

foundry import schema loads a .csvx package, as written by foundry generate dataset, from start to finish: it extracts the package to a temporary folder, builds the schema the package describes, imports every table's CSV into it, and deletes the extracted files afterwards, whether or not the import succeeded.

foundry import schema [options]

A .csvx package is a ZIP holding a manifest.json, a Velocity schema file (schema.json, schema.xml, or schema.yaml), and one CSV per table under tables/. The schema carries each table's columns, primary key, and the foreign keys between tables, so nothing needs to exist in the database beforehand.

Options

Option	Short	Description
--datasource <FILE>	-d	Datasource JSON file
--conn <STRING>	-c	ADO.NET connection string
--db <TYPE>	-b	Database engine type
--file <FILE>	-f	Path to the .csvx package (required)
--drop	-D	Drop and recreate schema objects that already exist
--ignore	-i	Ignore warnings while building the schema
--transaction	-T	Wrap the schema build in a transaction
--stream	-r	Stream each table's import instead of loading its whole file into memory first
--log-config <FILE>	-L	Log configuration file
--verbose	-v	Print SQL as it executes

Examples

# Build the package's schema and import every table
foundry import schema --datasource connection.json --file dataset.csvx

# Replace a schema imported earlier, streaming the larger tables
foundry import schema --datasource connection.json --file dataset.csvx --drop --stream

How It Works

The package's manifest.json records the CSV format its tables were written in — delimiter, quote and escape characters, line terminator, date and time formats, and encoding — resolved to Alchemy's defaults wherever the payload's csvFormat set nothing. Foundry reads every table with exactly those settings, so a package generated with a custom csvFormat (a pipe delimiter, UTF-16, and so on) imports with no extra options.

The schema is created under the name the payload's schemaName gave it (dataset if it set none). Tables are imported in the order the package lists them, which Alchemy guarantees puts every referenced table before the tables that reference it, so foreign keys are satisfied as each table loads.

If the schema's tables already exist, the build stops with an error before any data is imported. Pass --drop to replace them, or use foundry drop schema first.

---

Export

Foundry provides three export commands: exporting raw table data to CSV, exporting a single schema definition to files, and exporting the full database definition to files.

foundry export data

Exports table data to a CSV file.

foundry export data [options]

Required Options

Option	Short	Description
--datasource <FILE>	-d	Datasource JSON file
--conn <STRING>	-c	ADO.NET connection string
--db <TYPE>	-b	Database engine type
--schema <NAME>	-s	Source schema name
--table <NAME>	-t	Source table name
--out <FILE>	-o	Output CSV file path

CSV Format Options

Option	Short	Default	Description
--delimiter <CHAR>	-D	,	Field delimiter character
--quote-char <CHAR>	-q	"	Quote character
--escape-char <CHAR>	-E	unset	Character written before a quote inside a quoted field. Unset writes the quote twice
--line-terminator <STRING>	-n	unset	Row terminator. Unset writes the line ending of the platform the export runs on
--encoding <NAME>	-C	unset	Encoding the file is written in. Unset writes UTF-8 with no byte order mark
--force-qualifier	-Q		Always quote all field values
--no-headers	-H		Omit column header row
--no-trim	-T		Preserve leading and trailing whitespace
--export-config <FILE>	-e		JSON file with export format settings

Date & Time Format Options

Option	Short	Default	Description
--date-format <FORMAT>	-a	yyyy-MM-dd	Date format string
--time-format <FORMAT>	-m	HH:mm:ss	Time format string
--interval-format <FORMAT>	-N	c	Interval/TimeSpan format string
--datetime-format <FORMAT>	-y	yyyy-MM-dd HH:mm:ss	DateTime format string
--timestamp-format <FORMAT>	-Y	yyyy-MM-dd HH:mm:ss zzz	DateTimeOffset format string

Examples

# Export a table to CSV
foundry export data \
  --datasource connection.json \
  --schema public --table orders \
  --out exports/orders.csv

# Semicolon delimiter
foundry export data \
  --datasource MySql_8.4.json \
  --schema sales --table orders \
  --out exports/orders.csv \
  --delimiter ";"

# Inline connection string
foundry export data \
  --conn "Server=localhost;Database=mydb;User Id=sa;Password=pass" \
  --db SQLServer \
  --schema dbo --table customers \
  --out exports/customers.csv

Export Config File Reference

An export config file (validated against schemas/export-config.schema.json) covers everything the CSV format flags cover, plus per-column blob handling with no CLI flag equivalent.

Field	Type	Default	Description
delimiter	string (1 char)	,	Field delimiter
quoteChar	string (1 char)	"	Quote character for fields containing the delimiter
escapeChar	string (1 char)	unset	Character written before a quote inside a quoted field. Unset writes the quote twice.
lineTerminator	string	unset	Row terminator. Unset writes the line ending of the platform the export runs on.
encoding	string	unset	Encoding the file is written in. Unset writes UTF-8 with no byte order mark.
forceQualifier	boolean	false	Always quote every field value, even when not strictly required
writeHeaders	boolean	true	Write a column header row as the first output line
trimChars	boolean	true	Trim leading and trailing whitespace from string values
dateFormat	string	yyyy-MM-dd	.NET format string for date-only columns
timeFormat	string	HH:mm:ss	.NET format string for time-only columns
intervalFormat	string	c	.NET format string for interval/TimeSpan columns
dateTimeFormat	string	yyyy-MM-dd HH:mm:ss	.NET format string for DateTime columns
timestampFormat	string	yyyy-MM-dd HH:mm:ss zzz	.NET format string for DateTimeOffset/timestamp columns
blobs	array	—	Per-column blob handling rules (see below)

Blob handling. Each entry needs a column and a handling of base64 (encode the blob as Base64 inline in the CSV) or file (write the blob to an external file and emit the file path, using a pattern with {column_name} token substitution). Rules can be scoped globally, to a table, or to a schema + table, and are evaluated in that order — the first match wins:

{
  "blobs": [
    { "column": "thumbnail", "handling": "base64" },
    { "column": "document", "handling": "file", "pattern": "exports/blobs/{document}", "table": "contracts" },
    { "column": "scan", "handling": "file", "pattern": "exports/blobs/{scan}", "schema": "archive", "table": "records" }
  ]
}

Full example:

{
  "$schema": "schemas/export-config.schema.json",
  "delimiter": ";",
  "forceQualifier": true,
  "blobs": [
    { "column": "thumbnail", "handling": "base64" }
  ]
}

---

foundry export schema

Exports a schema definition, along with each table's data as a CSV file, from a connected database to a directory.

foundry export schema [options]

Option	Short	Description
--datasource <FILE>	-d	Datasource JSON file
--conn <STRING>	-c	ADO.NET connection string
--db <TYPE>	-b	Database engine type
--target <SCHEMA>	-t	Name of the schema to export (required)
--out <PATH>	-o	Output directory path (required)
--format <FORMAT>	-F	Output format: Xml, Json, Yaml (default: Xml)

foundry export schema \
  --datasource connection.json \
  --target dbo --out exports/ --format Json

foundry export schema \
  --datasource PostgreSQL_17.6.json \
  --target public --out exports/ --format Yaml

---

foundry export database

Exports the full database definition, along with every table's data as CSV files, from a connected database. Optionally scoped to specific schemas.

foundry export database [options]

Option	Short	Description
--datasource <FILE>	-d	Datasource JSON file
--conn <STRING>	-c	ADO.NET connection string
--db <TYPE>	-b	Database engine type
--target <SCHEMAS>	-t	Comma-separated schema names to include (all if omitted)
--out <PATH>	-o	Output directory path (required)
--format <FORMAT>	-F	Output format: Xml, Json, Yaml (default: Xml)

foundry export database \
  --datasource connection.json \
  --out exports/

# Export only specific schemas in YAML format
foundry export database \
  --datasource SqlServer_17.0.json \
  --target dbo,audit --out exports/ --format Yaml