Schemas

Foundry's schema commands cover the full Velocity schema lifecycle: building objects in a database, loading existing structures from a database, applying incremental updates, and working with schema and database definition files.

Note

This page covers the Foundry CLI commands only. For the schema/database definition file format itself — column types, constraints, indexes, spatial and full-text indexes, and the schemaupdate attribute — see the Velocity schema definition reference.

Build

The foundry build command creates schema objects (tables, views, indexes) in a connected database from a definition file.

`foundry build schema`

Builds all objects defined in a schema definition file into the target database schema.

foundry build schema [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 schema definition file (XML, JSON, or YAML)
`--drop`		Drop existing objects before building
`--ignore`		Continue if an object already exists
`--transaction`		Wrap all DDL in a transaction (rolls back on error) — see warning below
`--log-config <FILE>`	`-L`	Log configuration file
`--verbose`	`-v`	Print SQL as it executes

Examples:

# Build from an XML definition using a datasource file
foundry build schema --datasource connection.json --file schemas/customers.xml

# Drop and rebuild with a transaction
foundry build schema \
  --datasource PostgreSQL_17.6.json \
  --file schemas/public.json \
  --drop --ignore --transaction

# Using an inline connection string
foundry build schema \
  --conn "Server=localhost;Database=mydb;User Id=sa;Password=pass" \
  --db SQLServer \
  --file schemas/dbo.xml

`foundry build database`

Builds all schemas defined in a database definition file.

foundry build database [options]

Accepts the same options as foundry build schema. The --file argument should point to a database-level definition file that references multiple schemas.

Examples:

foundry build database --datasource connection.json --file mydb.xml --drop

foundry build database \
  --conn "Server=localhost;Database=mydb;User Id=sa;Password=pass" \
  --db SQLServer \
  --file mydb.xml --drop --ignore --transaction

Warning

--transaction is not equally reliable across engines when a schema includes a full-text index. Dropping and recreating a full-text index as part of a transactional rebuild has been observed to hang/fail on PostgreSQL, and full-text search implementations on other engines rely on similar multi-statement DDL that transactional wrapping doesn't handle cleanly. If a schema has full-text indexes, prefer --drop --ignore without --transaction.

More generally, several database engines don't support DDL inside a transaction at all — DDL statements commit implicitly regardless of an open transaction (this is a long-standing behavior on engines such as MySQL and Oracle, not something Foundry or Velocity controls). On those engines --transaction cannot provide real all-or-nothing rollback for schema changes; test rollback behavior against your specific engine and schema before relying on it.

Load

foundry load reads the structure of a live database and writes it as a Velocity definition file. Use this to capture the current state of a database as a baseline, or after making manual schema changes.

`foundry load schema`

Reads a named schema from the database and writes its definition to a file.

foundry load schema [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`	Name of the schema to load
`--out <FILE>`	`-o`	Output file path
`--format <FORMAT>`	`-F`	Output format: `Xml`, `Json`, `Yaml` (default: `Xml`)

Examples:

foundry load schema --datasource connection.json --schema dbo --out schemas/dbo.xml

foundry load schema \
  --datasource PostgreSQL_17.6.json \
  --schema public --out schemas/public.json

`foundry load database`

Reads the full database structure and writes a database-level definition file. You can scope the load to specific schemas using --schema.

foundry load database [options]

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

Examples:

foundry load database --datasource connection.json --out mydb.xml

# Load only specific schemas
foundry load database \
  --datasource SqlServer_16.0.json \
  --schema dbo,audit --out mydb.yaml

Update

foundry update schema is not a diff tool — it does not compare the definition file to the live schema. It only creates the specific tables, columns, constraints, indexes, and views in the file that are explicitly marked schemaupdate="true". Everything else in the file is left alone, including anything present in the live database but absent from the file: update schema never drops a column, drops a table, or alters an existing column's type, with or without --force.

This makes update schema a one-shot operation, not an idempotent one: running it again with the same file after its schemaupdate="true" objects have already been created will fail (e.g. "relation already exists"), since it always attempts to create them rather than checking whether they're already there. Typical usage is to mark only the new additions for a given release in the file, run the update once, then clear those markers (or move to the next version's file) before the next update.

foundry update schema [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 schema definition file
`--force`		Skip an object the target engine can't create (see below) instead of aborting the update
`--log-config <FILE>`	`-L`	Log configuration file
`--verbose`	`-v`	Print SQL as it executes

Note

--force does not enable destructive changes — update schema has no code path that drops or alters existing objects, so there is nothing for --force to authorize there. What it actually does: creating a new constraint, index, full-text index, or spatial index can fail with an "unsupported operation" error on engines that don't support that particular construct (for example, a CHECK constraint using a non-deterministic function is rejected by MySQL, Oracle, DB2, and SQLite). Without --force, that error aborts the update. With --force, that one object is skipped and the update continues with the rest. This is the same mechanism as --ignore on foundry build schema/foundry build database, just under a different flag name here.

Examples:

foundry update schema --datasource connection.json --file schemas/dbo.xml

foundry update schema \
  --datasource PostgreSQL_18.1.json \
  --file schemas/public.json --force

Definition

The foundry definition command works with schema and database definition files without requiring a live database connection — except for the validate subcommand.

All definition operations work on either schema or database scope:

foundry definition schema  <subcommand> [options]
foundry definition database <subcommand> [options]

read

Reads a definition file and prints a summary to the console.

Option	Short	Description
`--file <FILE>`	`-f`	Path to the definition file
`--format <FORMAT>`	`-F`	File format hint: `Xml`, `Json`, `Yaml`
`--verbose`	`-v`	Print full detail rather than a summary

foundry definition schema read --file schemas/dbo.xml
foundry definition database read --file mydb.json --verbose

convert

Converts a definition file from one format to another (XML ↔ JSON ↔ YAML).

Option	Short	Description
`--file <FILE>`	`-f`	Source file
`--format <FORMAT>`	`-F`	Source format hint
`--out <FILE>`	`-o`	Output file path
`--out-format <FORMAT>`	`-O`	Output format (inferred from `--out` extension if omitted)

foundry definition schema convert --file schemas/dbo.xml --out schemas/dbo.json
foundry definition database convert --file mydb.yaml --out mydb.xml

compare

Compares two definition files and reports differences.

Option	Short	Description
`--file1 <FILE>`	`-f`	First definition file
`--format1 <FORMAT>`	`-F`	Format hint for file 1
`--file2 <FILE>`	`-g`	Second definition file
`--format2 <FORMAT>`	`-G`	Format hint for file 2

foundry definition schema compare --file1 schemas/dbo_v1.xml --file2 schemas/dbo_v2.xml
foundry definition database compare --file1 mydb_v1.xml --file2 mydb_v2.xml

validate

Validates a definition file against a live database, checking that all objects in the file match what exists in the database.

Accepts all connection options in addition to:

Option	Short	Description
`--file <FILE>`	`-f`	Path to the definition file
`--format <FORMAT>`	`-F`	File format hint

foundry definition schema validate --datasource connection.json --file schemas/dbo.xml

foundry definition database validate \
  --conn "Server=localhost;Database=mydb;User Id=sa;Password=pass" \
  --db SQLServer \
  --file mydb.xml

Table of Contents

Schemas

Note

Build

foundry build schema

foundry build database

Warning

Load

foundry load schema

foundry load database

Update

Note

Definition

read

convert

compare

validate

`foundry build schema`

`foundry build database`

`foundry load schema`

`foundry load database`