index.md

layout	default
title	Configuration options
permalink	/configuration-options/
nav_order	5
has_children	true

Grate Configuration Options

For the purpose and location of ScriptsRun, Version, and the internal Grate* tables, see Migration tables.

Barebone

The only required argument to pass to grate is a connection string to tell it where to find your database. It will deploy to that database, looking for sql scripts in the current directory.

grate --connectionstring="Server=(localdb)\MSSQLLocalDB;Integrated Security=true;Database=grate_test"

Connection strings by database

Pass the complete connection string as one value to --connectionstring on the CLI or APP_CONNSTRING in Docker. Select the provider with --databasetype on the CLI or DATABASE_TYPE in Docker. Both default to sqlserver.

Database type	Driver connection string reference
sqlserver	Microsoft.Data.SqlClient
postgresql	Npgsql
mariadb	MySqlConnector
oracle	ODP.NET Core
sqlite	Microsoft.Data.Sqlite

For PostgreSQL, use an Npgsql string such as Host=db;Port=5432;Database=grate_example;Username=postgres;Password=your-password. The PostgreSQL Docker Compose example shows how to pass the string at runtime and optionally supply an admin connection.

Full Configuration

Option	Default	Purpose
-c -cs --connectionstring --connstring <connectionstring>	-	REQUIRED You now provide an entire connection string. ServerName and Database are obsolete.
-a -acs -csa --adminconnectionstring --adminconnstring <adminconnectionstring>	The value provided via --connectionstring, with the target database replaced with a database that can be assumed to be present. For example, "master" for SQL Server.	Used when creating a new database, rather than migrating an existing one.
-f --files --sqlfilesdirectory <sqlfilesdirectory>	. (current directory)	The directory where your SQL scripts are located
--folders	Default folders as described in Getting started	Folder configuration, see Folder configuration for details.
-o --output --outputPath <outputPath>	%LOCALAPPDATA%/grate	Directory for migration artifacts such as copies of executed SQL scripts. To save console logs, see Capture console logs.
--accesstoken <token>	-	Specify an access token to use when connecting to SQL Server.
-ct --commandtimeout <commandtimeout>	60	This is the timeout in seconds when commands are run. This is not for admin commands or restore.
-cta --admincommandtimeout <admincommandtimeout>	300	This is the timeout in seconds when administration commands are run (except for restore, which has its own)
--databasetype --dbt --dt <mariadb | oracle | postgresql | sqlite | sqlserver>	sqlserver	Tells grate what type of database it is running on.
-t --transaction --trx	false	Run the migration in a transaction
--sc --schema --schemaname <schemaname>	grate	The schema to use for the migration tables. If you're upgrading from RoundhousE you'll probably want this!
--drop	false	Drop - This instructs grate to remove the target database. Unlike RoundhousE grate will continue to run the migration scripts after the drop.
--env --environment	(empty)	Environment Name - This allows grate to be environment aware and only run scripts that are in a particular environment based on the name of the script. 'something.ENV.LOCAL.sql' would only be run if --env=LOCAL was set.
-w --warnononetimescriptchanges	false	WarnOnOneTimeScriptChanges - Instructs grate to execute changed one time scripts(DDL / DML in Upfolder) that have previously been run against the database instead of failing. A warning is logged for each one time script that is rerun.
--warnandignoreononetimescriptchanges	false	WarnAndIgnoreOnOneTimeScriptChanges - Warns about changed one-time scripts and records their new hashes without executing them. See One-Time Scripts for the history and subsequent-run behavior.
--disabletokenreplacement --disabletokens	false	Tokens - This instructs grate to not perform token replacement ({% raw %}{{DatabaseName}}{% endraw %}).
--usertokens --ut <usertokens>	-	User Tokens - Allows grate to perform token replacement on custom tokens ({% raw %}{{my_token}}{% endraw %}). Set as a key=value pair, eg '--ut=my_token=myvalue'. Can be specified multiple times. ℹ️ NB that while RoundhousE passed multiple tokens as a single parameter, grate requires you to pass each user token separately
--donotstorescriptsruntext	false	DoNotStoreScriptsRunText - This instructs grate to not store the full script text in the database.
--forceanytimescripts --runallanytimescripts	false	RunAllAnyTimeScripts - This instructs grate to run any time scripts every time it is run even if they haven't changed. Defaults to false.
--baseline	-	Baseline - This instructs grate to mark the scripts as run, but not to actually run anything against the database. Use this option if you already have scripts that have been run through other means (and BEFORE you start the new ones).
--dryrun	false	DryRun - This instructs grate to log what would have run, but not to actually run anything against the database. Use this option if you are trying to figure out what grate is going to do.
--restore <backup-path>	-	Restore a SQL Server backup before running migrations. The backup path is on the SQL Server host.
--restore-move <logical-name=destination-path>	-	Map a file in the SQL Server backup to a new path on the SQL Server host. Repeat for each file to move. Requires --restore.
-ni --noninteractive --silent	false	Silent - tells grate not to ask for any input when it runs.
-r --repo --repositorypath	-	Repository Path - RepositoryPath - The repository. A string that can be anything. Used to track versioning along with the version. Defaults to null.
--version	1.0.0.0	Database Version - specify the version of the current migration directly on the command line.
--isuptodate --uptodatecheck	-	Outputs whether the database is up to date or not (whether any non-everytime scripts would be run)
-v --verbosity <Critical| Debug| Error| Information| None| Trace|Warning>	Information	Verbosity level (as defined here: https://docs.microsoft.com/dotnet/api/Microsoft.Extensions.Logging.LogLevel)
--log-format <auto|console|ci|github|azure-devops|teamcity>	auto	Selects how the CLI writes migration logs. See Migration logs in CI.
--createdatabase --create	true	Create - Instructs grate to create the target database if it does not exist. Set to false to emulate the --donotcreatedatabase flag in roundhouse.
-? -h --help	-	Show help and usage information

Move SQL Server files when restoring a backup

Use RESTORE FILELISTONLY FROM DISK = N'path-to-backup.bak' in SQL Server to find the LogicalName for each file you want to move. Quote each mapping as one shell argument. The first = separates the logical name from the destination path.

grate --connectionstring "$CONNECTION_STRING" \
  --restore '/var/opt/mssql/backup/example.bak' \
  --restore-move 'Example Data=/var/opt/mssql/data/New Data.mdf' \
  --restore-move 'Example Log=/var/opt/mssql/data/New Log.ldf'

Specify destination paths that the SQL Server service can write to. SQL Server applies its normal restore rules for any files you leave unmapped.

In .NET, call RestoreFrom(backupPath) and WithRestoreMoves(new RestoreFileMove(logicalName, destinationPath), ...) on the GrateConfigurationBuilder.

Capture console logs

Use shell redirection to save stdout and stderr in the same file. The shell returns grate's exit code for this command.

grate --connectionstring "$APP_CONNSTRING" --silent > grate.log 2>&1

Azure Container Apps Jobs

Use the published Docker image and override the job container's startup command in its template. Keep the existing migration environment variables (including APP_CONNSTRING) and SQL scripts at /db. Mount writable persistent storage such as an Azure Files share at /output so the log is available after the container exits. Azure job template reference

Set these fields on the job's container.

command: ["/bin/sh", "-c"]
args:
  - 'exec /app/entrypoint.sh > /output/grate.log 2>&1'

exec runs the image's usual entrypoint in place of the shell, so the container keeps grate's exit code. The example overwrites grate.log on each start. Use distinct log paths for replicas or attempts that share the mount when you need to keep their logs.

Messages from SQL Server scripts

Use --verbosity=Debug (or Trace) to see SQL Server PRINT output and other informational messages from migration scripts. Grate logs them at Debug with the script name. The default Information level keeps these messages hidden. SQL errors still fail the migration.

Migration logs in CI

--log-format=auto selects a format once when the CLI starts a migration. Set --log-format explicitly to override detection. azure and devops are aliases for azure-devops.

Runner	Signal in auto	Format
GitHub Actions	GITHUB_ACTIONS=true	github: warning and error annotations
Azure Pipelines	TF_BUILD=True	azure-devops: warning and error issues via task.logissue
TeamCity	Nonempty TEAMCITY_VERSION	teamcity: build log messages with WARNING or ERROR status
Jenkins	Nonempty JENKINS_URL or a BUILD_TAG starting with jenkins-	ci: plain text in the standard build console
Other CI, or more than one runner matches	CI=true without a runner match, or multiple runner matches	ci: plain text
Local or unrecognized environment	No active signal	console: interactive colors when available and warnings and errors on stderr

Boolean signals match true regardless of case. Unset, empty and false values do not activate them. All CI formats write migration logs to stdout without colors. Plain output includes severity labels such as [INFO] and [WARNING]; native formats use the runner's own markup for warnings, errors and critical errors. Use --log-format=console to keep the original stdout/stderr split in a CI job. The --isuptodate result line stays Up to date: True or Up to date: False on stdout in every format.

A warning does not change grate's exit code. A failed migration exits nonzero. A runner may also act on native errors independently of the process exit code, for example when TeamCity's fail-on-error-message setting is enabled. Use --log-format=ci if the job needs plain logs and relies on the process exit code.

Docker does not forward runner variables by default. For example, in a GitHub Actions job, forward GITHUB_ACTIONS to let a grate image with this option detect the runner:

mkdir -p output
docker run --rm --env GITHUB_ACTIONS --env DATABASE_TYPE=sqlite \
  --env 'APP_CONNSTRING=Data Source=/output/example.db' \
  --mount "type=bind,src=$PWD/migrations,dst=/db,readonly" \
  --mount "type=bind,src=$PWD/output,dst=/output" \
  gratedevs/grate

For other runners, forward the corresponding variable from the table. You can also pass a flag after the image name, for example gratedevs/grate --log-format=azure-devops, without forwarding any runner variables.