Foundry Syntax

This page describes the overall command-line structure that all Foundry commands share, including how to specify database connections, configure logging, and pass global flags.

Command Structure

foundry <command> [subcommand] [arguments] [options]

Commands are organized into two shapes:

• Branch commands — a verb with a noun subcommand, such as foundry build schema or foundry export data
• Flat commands — a single verb with no subcommand, such as foundry import, foundry run, or foundry view

Use --help at any level to see the available subcommands and options:

foundry --help
foundry build --help
foundry build schema --help

Connection Options

Any command that communicates with a database accepts one of two mutually exclusive connection modes.

Mode 1 — Datasource File

foundry <command> --datasource <FILE>

--datasource (or -d) points to a JSON file describing the database connection. This is the recommended approach for project-based workflows because the file can be committed to source control (with sensitive values managed separately) and referenced by name from a project.json run script.

A datasource file for SQL Server looks like this:

{
  "$schema": "schemas/datasource-sqlserver.schema.json",
  "type": "SQLServer",
  "hostname": "localhost",
  "port": 1433,
  "database": "MyDatabase",
  "username": "sa",
  "password": ""
}

Use foundry create <name> <DB-TYPE> to scaffold a ready-to-edit datasource file for any supported database.

Datasource File Reference

Every datasource file is validated against a JSON schema in the schemas/ directory created by foundry create (e.g. datasource-sqlserver.schema.json). Most editors (including VS Code) use the $schema field to provide autocomplete and inline documentation for every field below as you type.

The following fields are common to every networked database (SQL Server, MySQL, Oracle, PostgreSQL, Teradata, DB2):

Field	Type	Default	Description
hostname	string	—	Hostname or IP address of the server
port	integer	engine-specific	TCP port
database	string	—	Target database name (Oracle: service name or SID)
username	string	—	Login username
password	string	—	Login password
pooling	boolean	true	Enable connection pooling
minPoolSize	integer	0	Minimum number of connections held open in the pool
maxPoolSize	integer	100	Maximum number of connections the pool may open
connectTimeout	integer	20	Seconds to wait for a connection before timing out
commandTimeout	integer	30	Seconds to wait for a command to complete. 0 = unlimited
useIntegratedSecurity	boolean	false	Use OS-level/Windows/Kerberos authentication instead of username/password
sslMode	string	engine-specific	One of Disable, Prefer, Require, VerifyCA, VerifyFull
sslCaPath	string	—	Path to a PEM-encoded CA certificate file
sslCertificatePath	string	—	Path to a PEM-encoded client certificate file
sslKeyPath	string	—	Path to the private key file for sslCertificatePath
defaultSrid	integer	4326	Default spatial reference identifier for geometry/geography columns
importBatchSize	integer	10000	Rows sent per batch during a bulk import
importTimeout	integer	120	Seconds to wait for each import batch. 0 = unlimited
importTransaction	boolean	true	Wrap each import in a transaction so a failure rolls back the whole import
advanced	string	—	Semicolon-separated key=value pairs passed directly to the underlying driver

Note

sslMode defaults to Require for SQL Server, Disable for Oracle and DB2, and Prefer for MySQL, PostgreSQL, and Teradata — matching each engine's own client library default. Specify sslMode explicitly rather than relying on the default if your environment depends on a specific mode.

Each engine also exposes its own additional fields:

SQL Server (datasource-sqlserver.schema.json)

Field	Type	Default	Description
authenticationMethod	string	WindowsIntegrated	One of WindowsIntegrated, ActiveDirectoryPassword, ActiveDirectoryIntegrated, ActiveDirectoryInteractive, ActiveDirectoryManagedIdentity, ActiveDirectoryServicePrincipal, ActiveDirectoryDefault, ActiveDirectoryWorkloadIdentity
trustServerCertificate	boolean	true	Trust the server certificate without CA validation. Forced to false once sslMode is VerifyCA or VerifyFull

MySQL (datasource-mysql.schema.json)

Field	Type	Default	Description
lengthUnit	string	metre	Unit used when reporting spatial column lengths
allowLoadLocalInfile	boolean	true	Allow LOAD DATA LOCAL INFILE, used for fast bulk import
allowUserVariables	boolean	true	Allow @variable user-defined variables in SQL

Oracle (datasource-oracle.schema.json)

Field	Type	Default	Description
escapeIdentifiers	boolean	true	Quote-escape object identifiers in generated SQL
tablespace	string	—	Default tablespace for new tables/indexes
tolerance	number	0.01	Spatial tolerance for Oracle Spatial geometry operations
useBooleanDataType	boolean	true	Use Oracle's native BOOLEAN type (23ai+) instead of a NUMBER(1)/CHAR(1) emulation

Teradata (datasource-teradata.schema.json)

Field	Type	Default	Description
authenticationMethod	string	Ldap	One of Ldap, Spnego, Tdnego, Jwt, Bearer
sessionCharacterSet	string	UTF8	Session character set
fullTextSearchEnabled	boolean	false	Enable full-text search support
fullTextSearchClobs	boolean	false	Include CLOB columns in full-text search indexes
permanentSpace	integer	100000000	Permanent space (bytes) allocated for table storage
numberOfStagingTables	integer	4	Staging tables used to parallelize bulk import
varCharCastSize	integer	32000	Size used when casting values to VARCHAR
importCastClob	boolean	true	Cast CLOB columns during import
importCastGeo	boolean	true	Cast geometry/geography columns during import
selectCastClob	boolean	true	Cast CLOB columns when selecting data
sourceSpatialReference	string	WGS 84 (WKT)	Source spatial reference system used when transforming geometry on import
targetSpatialReference	string	NAD27 / California Albers (WKT)	Target spatial reference system used when transforming geometry on import
identityStartValue	integer	0	Starting value for emulated identity/auto-increment columns

Note

Teradata's defaultSrid defaults to 1619, not the 4326 used by every other engine.

DB2 (datasource-db2.schema.json, Windows/Linux/macOS packages only)

Field	Type	Default	Description
authenticationMethod	string	Kerberos	One of Client, Kerberos, KerberosServerEncrypt, GssPlugin, GssServerEncrypt
updateFrequency	string	d(0,1,2,3,4,5,6) h(0,12) m(0)	RUNSTATS/REORG schedule expression: days d(...), hours h(...), minutes m(...)
updateMinimum	integer	5	Minimum changed rows required before statistics are refreshed

SQLite (datasource-sqlite.schema.json, Windows/Linux/macOS/Raspberry Pi packages only)

SQLite is a local file-based database, so it does not use hostname, port, username, useIntegratedSecurity, or any SSL field. Its full field set is:

Field	Type	Default	Description
database	string	—	Path to the SQLite database file, or :memory: for an in-memory database
password	string	—	Encryption password, for encrypted database files. Leave empty for unencrypted databases
pooling	boolean	true	Enable connection pooling
connectTimeout	integer	20	Seconds to wait for a connection before timing out
commandTimeout	integer	30	Seconds to wait for a command to complete. 0 = unlimited
defaultSrid	integer	4326	Default spatial reference identifier for geometry columns
importBatchSize	integer	10000	Rows inserted per batch during a bulk import
importTimeout	integer	120	Seconds to wait for each import batch. 0 = unlimited
importTransaction	boolean	true	Wrap each import in a transaction so a failure rolls back the whole import
advanced	string	—	Semicolon-separated key=value pairs passed directly to the driver

Mode 2 — Inline Connection String

foundry <command> --conn <CONNECTION_STRING> --db <DB_TYPE>

--conn (or -c) accepts a standard ADO.NET connection string. --db (or -b) identifies the database engine. Both flags are required together and are mutually exclusive with --datasource.

# SQL Server
foundry load schema \
  --conn "Server=localhost;Database=mydb;User Id=sa;Password=pass" \
  --db SQLServer \
  --schema dbo --out dbo.xml

# PostgreSQL
foundry load schema \
  --conn "Host=localhost;Database=mydb;Username=postgres;Password=pass" \
  --db PostgreSQL \
  --schema public --out public.xml

Connection Context

When using the inline connection mode, --context (or -x) passes semicolon-separated Velocity context settings to the connection:

foundry build schema \
  --conn "Server=localhost;Database=mydb;User Id=sa;Password=pass" \
  --db SQLServer \
  --context "CommandTimeout=120;ImportBatchSize=50000" \
  --file schema.xml

--context cannot be combined with --datasource.

Global Options

The following options are available on every connected command:

Option	Short	Description
--datasource <FILE>	-d	Path to a datasource JSON file
--conn <STRING>	-c	ADO.NET connection string
--db <TYPE>	-b	Database engine type (required with --conn)
--context <SETTINGS>	-x	Semicolon-separated Velocity context settings
--log-config <FILE>	-L	Path to a Velocity log configuration file
--verbose	-v	Print each SQL statement as it executes

Logging

Foundry uses the Velocity Framework logging infrastructure, which is built on log4net. You can supply a log configuration file with --log-config.

foundry create writes a velocity.log.config to your project directory as a starting point:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <log4net debug="false" update="Merge" threshold="ALL">
    <appender name="FileAppender" type="log4net.Appender.FileAppender">
      <file value="logs/velocity.log" />
      <appendToFile value="false" />
      <lockingModel type="log4net.Appender.FileAppender+MinimalLock" />
      <layout type="log4net.Layout.PatternLayout">
        <conversionPattern value="%date{yyyy-MM-dd HH:mm:ss.fff zzz} [%-5level] %message%newline" />
      </layout>
    </appender>
    <root>
      <level value="DEBUG" />
      <appender-ref ref="FileAppender" />
    </root>
  </log4net>
</configuration>

Adjust the <level> value to control verbosity (DEBUG, INFO, WARN, ERROR). Set appendToFile to true to append to an existing log rather than overwriting on each run.

When --log-config is omitted, no file logging is performed.

Verbose Mode

Add --verbose to any connected command to have each SQL statement printed to the console as it executes. This is useful for diagnosing unexpected behavior or auditing what Foundry sends to the database.

foundry build schema --datasource connection.json --file schema.xml --verbose

Version, Help, and License

foundry --version     # Print the installed version
foundry --help        # List all commands with descriptions
foundry <cmd> --help  # Show options for a specific command
foundry --license      # Display the Foundry license, paged
foundry -l              # Same as --license

--license (or -l) must be the first argument. It displays the contents of the license file that ships with your installed Foundry package, one screen at a time:

foundry --license

• Press Enter to advance to the next page.
• Press Q to quit before reaching the end.

If output is redirected or piped — for example foundry --license > LICENSE.txt — the full license text is written out directly with no paging or prompts.

Note

--license is recognized before any command is resolved, the same way --version is. It is not listed in the output of foundry --help because of this, but works exactly as shown above.