Run & Project

foundry run

foundry run executes a sequence of Foundry commands defined in a JSON project file. It is the primary mechanism for running multi-step database workflows — deployments, migrations, test data loads, or any other repeatable sequence of operations.

foundry run [FILE] [options]

Argument / Option	Short	Description
`[FILE]`		Path to the run script JSON file (default: `project.json`)
`--continue-on-error`	`-C`	Continue executing remaining steps even if a step fails

Examples:

# Run project.json in the current directory
foundry run

# Run a named script
foundry run deploy.json

# Run and continue past failures
foundry run migrate.json --continue-on-error

project.json

A project file is a JSON document that defines a name, an optional default connection, optional logging, and an ordered list of steps.

Top-Level Properties

Property	Type	Description
`$schema`	string	JSON schema path — use `schemas/run-script.schema.json` for IntelliSense
`name`	string	Display name printed at the start of the run
`description`	string	Optional description printed below the name
`logConfig`	string	Path to a Velocity log config file (inherited by all steps)
`datasource`	string	Default datasource file path (inherited by steps that omit their own)
`conn`	string	Default ADO.NET connection string
`db`	string	Default database engine type
`context`	string	Default Velocity context settings
`continueOnError`	boolean	Script-level default for step error handling
`steps`	array	Ordered list of step objects

Minimal Example

{
  "$schema": "schemas/run-script.schema.json",
  "name": "MyDatabase Deployment",
  "logConfig": "velocity.log.config",
  "datasource": "connection.json",
  "steps": [
    {
      "name": "Build schema",
      "build-schema": {
        "file": "schemas/dbo.xml",
        "drop": true
      }
    },
    {
      "name": "Load seed data",
      "import": {
        "schema": "dbo",
        "table": "reference_data",
        "file": "data/reference_data.csv"
      }
    }
  ]
}

Step Properties

Each step object has the following common properties:

Property	Type	Description
`name`	string	Step label shown in the run output
`description`	string	Optional description printed before the step runs
`continueOnError`	boolean	Override the script-level `continueOnError` for this step

Each step must contain exactly one command property. The available command properties below mirror most Foundry CLI commands — but not all of them: foundry view, foundry spatial view, foundry project create, and foundry project update have no run-script equivalent and cannot be used as a step.

Command Property	Equivalent CLI Command
`build-schema`	`foundry build schema`
`build-database`	`foundry build database`
`definition-schema-read`	`foundry definition schema read`
`definition-schema-convert`	`foundry definition schema convert`
`definition-schema-compare`	`foundry definition schema compare`
`definition-schema-validate`	`foundry definition schema validate`
`definition-database-read`	`foundry definition database read`
`definition-database-convert`	`foundry definition database convert`
`definition-database-compare`	`foundry definition database compare`
`definition-database-validate`	`foundry definition database validate`
`drop-schema`	`foundry drop schema`
`drop-table`	`foundry drop table`
`drop-view`	`foundry drop view`
`drop-index`	`foundry drop index`
`drop-full-text-index`	`foundry drop full-text-index`
`drop-spatial-index`	`foundry drop spatial-index`
`empty-schema`	`foundry empty schema`
`empty-table`	`foundry empty table`
`export-schema`	`foundry export schema`
`export-database`	`foundry export database`
`export-data`	`foundry export data`
`import`	`foundry import`
`load-schema`	`foundry load schema`
`load-database`	`foundry load database`
`run`	`foundry run` (nested)
`spatial-export`	`foundry spatial export`
`sql-schema`	`foundry sql schema`
`sql-database`	`foundry sql database`
`update-schema`	`foundry update schema`

Each step's available fields are the same options documented for its equivalent CLI command (with the leading -- dropped and the flag name camelCased — e.g. --no-full-text-update becomes noFullTextUpdate, --geo-column becomes geoColumn). See Schemas, Import & Export, Drop & Empty, SQL Generation, and Spatial for the full field reference per command, and schemas/run-script.schema.json for editor autocomplete.

Connection Inheritance

Connection settings defined at the script level (datasource, conn, db, context, logConfig) are inherited by all steps. A step can override any of these by specifying its own value:

{
  "name": "my-project",
  "datasource": "connection.json",
  "logConfig": "velocity.log.config",
  "steps": [
    {
      "name": "Build dbo schema",
      "build-schema": {
        "file": "schemas/dbo.xml"
      }
    },
    {
      "name": "Import from staging server",
      "import": {
        "datasource": "staging-connection.json",
        "schema": "dbo",
        "table": "products",
        "file": "data/products.csv"
      }
    }
  ]
}

Batch Operations

A common pattern is to run a series of import steps for multiple tables:

{
  "$schema": "schemas/run-script.schema.json",
  "name": "Seed Data Load",
  "datasource": "connection.json",
  "logConfig": "velocity.log.config",
  "steps": [
    {
      "name": "Empty all tables",
      "empty-schema": { "schema": "dbo", "ignoreFailures": true }
    },
    {
      "name": "Load customers",
      "import": {
        "schema": "dbo", "table": "customers",
        "file": "data/customers.csv"
      }
    },
    {
      "name": "Load orders",
      "import": {
        "schema": "dbo", "table": "orders",
        "file": "data/orders.csv"
      }
    },
    {
      "name": "Load order lines",
      "import": {
        "schema": "dbo", "table": "order_lines",
        "file": "data/order_lines.csv"
      }
    }
  ]
}

Nested Run Scripts

A step can itself call another run script, enabling modular composition of multi-file workflows:

{
  "name": "Full Deployment",
  "steps": [
    {
      "name": "Build schemas",
      "run": { "file": "build.json" }
    },
    {
      "name": "Load seed data",
      "run": { "file": "seed.json" }
    }
  ]
}

foundry project create

foundry project create scaffolds a new Foundry project directory. It creates the directory structure, copies schema template files from the Foundry installation, writes a starter project.json, and optionally generates a ready-to-edit connection.json for the specified database type.

foundry project create <PROJECT-NAME> [DB-TYPE]

Argument	Description
`<PROJECT-NAME>`	Name of the project (becomes a subdirectory of the current directory)
`[DB-TYPE]`	Optional database type for connection scaffolding

Examples:

# Create a project with no connection file
foundry project create my-project

# Create a project with a PostgreSQL connection file
foundry project create my-project PostgreSQL

# Create a project with a SQL Server connection file
foundry project create my-project SQLServer

Created Files

<PROJECT-NAME>/
├── project.json          ← entry point for foundry run
├── connection.json       ← database connection (only if DB-TYPE given)
├── velocity.log.config   ← log4net configuration
├── logs/                 ← log output directory
└── schemas/              ← Foundry and Velocity schema/config files
    ├── datasource-*.schema.json   ← Foundry: datasource connection files
    ├── import-config.schema.json  ← Foundry: import config files
    ├── export-config.schema.json  ← Foundry: export config files
    ├── run-script.schema.json     ← Foundry: project.json / run scripts
    ├── velocity.xsd / velocity.json               ← Velocity: schema/database definition files
    ├── velocity-schema.xsd / velocity-schema.json ← Velocity: schema definition files
    └── velocity-database.xsd / velocity-database.json ← Velocity: database definition files

After creation, edit connection.json with your actual connection details before running any commands.

Note

The [DB-TYPE] argument accepts the same identifiers as --db on other commands. See Platform Selection for the full list of accepted values.

foundry project update

foundry project update refreshes the bundled schema files in an existing project's schemas/ folder, without touching anything else in the project (project.json, connection.json, velocity.log.config, and logs/ are left untouched). Use this after upgrading Foundry to pick up schema changes shipped in the new version, without having to recreate the whole project.

foundry project update <PROJECT-PATH>

Argument	Description
`<PROJECT-PATH>`	Path to an existing Foundry project directory

Examples:

# Refresh schemas in a project in the current directory
foundry project update my-project

# Refresh schemas using a relative or absolute path
foundry project update ./projects/my-project
foundry project update /opt/projects/my-project

Every bundled schema/config file is copied from the Foundry installation into <PROJECT-PATH>/schemas/, overwriting any file already there — both Foundry's own files (datasource-*.schema.json, import-config.schema.json, export-config.schema.json, run-script.schema.json) and the Velocity Framework's own schema/config files (velocity.xsd, velocity.json, velocity-schema.xsd, velocity-schema.json, velocity-database.xsd, velocity-database.json). The command reports which files were newly added versus updated:

✓ Schema files refreshed in my-project\schemas:
schemas/
├── + datasource-sqlite.schema.json
├── ~ datasource-sqlserver.schema.json
├── ~ run-script.schema.json
└── ...

1 added, 9 updated.

Note

If <PROJECT-PATH> doesn't have a schemas/ folder yet, it's created automatically — foundry project update works equally well as a way to add the schema folder to a project that was set up manually rather than via foundry project create.

Table of Contents

Run & Project

foundry run

project.json

Top-Level Properties

Minimal Example

Step Properties

Connection Inheritance

Batch Operations

Nested Run Scripts

foundry project create

Created Files

Note

foundry project update

Note