Run & Create

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 mirror the Foundry CLI commands:

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)
`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). See Schemas, Import & Export, Drop & Empty, and SQL Generation 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 create

foundry 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 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