Table of Contents

Getting Started

This guide walks you through installing Foundry, setting up a NuGet source, creating your first project, and running your first commands.

Prerequisites

Installing Foundry

Foundry is distributed as a .NET global tool on the YndigoBlue NuGet server. You need to add this source before installing.

Step 1 — Add the YndigoBlue NuGet source:

The YndigoBlue feed always requires authentication. Supply your username and password when adding the source:

dotnet nuget add source https://yndigoblue.com/nuget/v3/index.json \
  --name YndigoBlue \
  --username <YOUR_USERNAME> \
  --password <YOUR_PASSWORD>
Important

By default, dotnet nuget encrypts the stored password using a platform-specific mechanism (DPAPI on Windows). This encrypted format is not portable across operating systems — a NuGet.Config created on Windows with an encrypted password cannot be used on Linux or macOS, and vice versa.

On Linux and macOS, password encryption is not supported at all. You must add --store-password-in-clear-text:

dotnet nuget add source https://yndigoblue.com/nuget/v3/index.json \
  --name YndigoBlue \
  --username <YOUR_USERNAME> \
  --password <YOUR_PASSWORD> \
  --store-password-in-clear-text

This also applies to CI/CD agents — if your build runs on a non-Windows agent, --store-password-in-clear-text is required, or the credentials should be supplied via the NuGet Authenticate task / environment variables instead of a committed NuGet.Config.

Warning

Storing a clear-text password writes it as plain text into your NuGet.Config. Avoid committing this file to source control with real credentials — use environment-specific config files, secret variables in your pipeline, or dotnet nuget update source to inject credentials at build time instead.

Step 2 — Install Foundry:

Choose the package for your platform (see Platform Selection for the full breakdown):

# Cross-platform (MySQL, Oracle, PostgreSQL, SQLServer, Teradata)
dotnet tool install -g YndigoBlue.Foundry

# Windows — full support including DB2 and SQLite
dotnet tool install -g YndigoBlue.Foundry.Windows

# Linux — full support including DB2 and SQLite
dotnet tool install -g YndigoBlue.Foundry.Linux

# macOS (Apple Silicon) — full support including DB2 and SQLite
dotnet tool install -g YndigoBlue.Foundry.MacOS

# Raspberry Pi (Arm64) — includes SQLite, excludes DB2
dotnet tool install -g YndigoBlue.Foundry.RaspberryPi

Step 3 — Verify the installation:

foundry --version
Note

After installation the foundry command is available in any new terminal. If your current session does not find it, add ~/.dotnet/tools (Linux/macOS) or %USERPROFILE%\.dotnet\tools (Windows) to your PATH.

Updating Foundry

dotnet tool update -g YndigoBlue.Foundry

Replace the package name with the platform-specific name if you installed a platform package.

Creating Your First Project

foundry create scaffolds a new project directory. Providing a database type writes a ready-to-edit connection.json alongside the project.

foundry create my-database SQLServer

The command creates the following structure:

my-database/
├── project.json          ← batch run script entry point
├── connection.json       ← database connection (edit before running)
├── velocity.log.config   ← log4net configuration
├── logs/                 ← log output written here at runtime
└── schemas/              ← Velocity schema template files
    ├── datasource-sqlserver.schema.json
    ├── ...
    └── run-script.schema.json

Open connection.json and fill in your database connection details:

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

This is a minimal connection — every database engine supports many more optional fields (SSL, pooling, authentication method, and engine-specific tuning options). See the Datasource File Reference for the full field list per engine.

Running Your First Commands

With the project set up, the most common first steps are to either build a schema from a definition file or load an existing schema from a live database.

Load an existing schema from a database:

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

This reads the dbo schema from your SQL Server instance and writes the definition to schemas/dbo.xml.

Build a schema into the database from a definition file:

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

Import data from CSV:

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

Understanding Connection Options

Every command that talks to a database accepts two mutually exclusive ways to specify the connection:

Mode Options When to use
Datasource file --datasource <file> Projects with a connection.json file
Inline connection --conn <string> --db <type> One-off commands, scripts, CI/CD pipelines 
# Using a datasource file
foundry load schema --datasource connection.json --schema dbo --out dbo.xml

# Using an inline connection string
foundry load schema --conn "Server=localhost;Database=mydb;User Id=sa;Password=pass" --db SQLServer --schema dbo --out dbo.xml

See Foundry Syntax for the full set of global options and logging configuration.

Next Steps