en-US/about_Rivet_Configuration.help.txt
|
TOPIC
about_Rivet_Configuration SHORT DESCRIPTION Explains the Rivet configuration file. LONG DESCRIPTION ## Overview Rivet pulls the many settings it needs from a JSON configuration file called `rivet.json`. By default, Rivet will look in the current directory for the `rivet.json` file. The `rivet.ps1` script allows you to pass in the path to your own configuration file. The `rivet.json` file is written in JSON, because I don't like XML. Make sure all `\` (i.e. backspace) characters get escaped (e.g. `\\`). Comments are not allowed. All non-absolute paths in the `rivet.json` file are resolved as relative to the file itself. For example, if a setting's path is `Databases`, and the `rivet.json` file is in the `C:\Projects\Rivet\Test` directory, the setting's value will be resolved to `C:\Projects\Rivet\Test\Databases`. ## Environments You will most likely have many environments where Rivet will run. At a minimum, each environment will have a different SQL Server instance. To support multiple environments, the `rivet.json` file uses a special `Environments` setting, which is a hash of environments, where the key is the environment's name and the value is another hash of settings for that environment. These environment settings override the base/default settings. If an environment doesn't specify a setting, the base/default setting is used. { SqlServerName: '.\Rivet', DatabasesRoot: 'Databases', Environments: { Production: { SqlServerName: 'proddb\Rivet', } } } In this example, we've defined a `Production` environment which overrides the `SqlServerName` setting. ## Settings ### CommandTimeout The amount of time, in seconds, to wait for a command to complete. The default is 30 seconds. ### ConnectionTimeout The amount of time, in seconds, to wait for a database connection to open. The default is 15 seconds. ### DatabaseOrder A list of database names in the order in which Rivet should apply migrations. The default is alphabetical order. If a database is listed here but doesn't exist on the file system, it is ignored. This list doesn't have to list all your databases. Just the ones where order matters. Databases not listed here will continue to have their migrations applied in alphabetical order. ### DatabasesRoot Rivet assumes a database's migration scripts are stored together. in `$DatabasesRoot\$DatabaseName\Migrations`. So, `$DatabasesRoot` should point to the directory which contains the directories for each database. For example, given this directory structure: * rivet.json + Databases + Rivet + Migrations + RivetTest + Migrations You can see directories for the `Rivet` and `RivetTest` databases under the `Databases` directory. So, you'll set the `DatabasesRoot` setting to `Databases`. Rivet assumes there is a one-to-one mapping between the directories under `DatabasesRoot` and a database on the SQL Server. If this is not the case, and you'd like to exclude/ignore a directory under `DatabasesRoot`, use the `IgnoreDatabases` setting. ### Environments A hash of environments, where they key is the environment's name, and the value is another hash of settings for that environment. These environment settings override the base/default settings. If an environment doesn't specify a setting, the base/default setting is used. ### IgnoreDatabases A list of database names to ignore/exclude from the Rivet. This is useful if you have a directory under `DatabasesRoot` that doesn't contain a database's scripts. Wildcards are allowed, e.g. `Shared*` would exclude all directories under `DatabasesRoot` that begin with the word `Shared`. ### PluginModules A list of module names that contain Rivet plug-ins. If the plug-ins aren't loaded when Rivet runs, you'll get an error. ### PluginPaths A list of directories/files to PowerShell modules that export Rivet plugins. Rivet runs `Import-Module -Force` on each of these paths. Each path should be relative to the rivet.json file. Wildcards in the path are allowed. Plugins are loaded in the order defined. If a wildcard matches multiple items, they are loaded in the order returned by PowerShell's `Resolve-Path` cmdlet. These paths *must* exist or you'll get an error. { "PluginPaths": [ "MyRivetExtensions", "SomebodyElsesRivetExtensions" ] } See `about_Rivet_Plugins` for more information on writing Rivet plugins. ### SqlServerName The name of the SQL Server to connect to. ### TargetDatabases This setting maps database names to lists of target databases. Use this setting if you need to deploy the same migrations to multiple databases, but don't want to duplicate the migration. Should be a hashtable whose key is the name of the database's scripts directory on the file system, and whose value is an array of target database names those scripts should be applied to, e.g. { "TargetDatabases": { "Database1": [ "Database1", "Database2" ] } } In the above example, scripts in the `Database1` directory will be applied to the `Database1` *and* `Database2` databases. ## Examples ### Example 1 { SqlServerName: '.\\Rivet', DatabasesRoot: 'Databases' } This example demonstrates the simplest configuration file. This configuration file will cause Rivet to connect to the `.\Rivet` SQL Server, and load database scripts from the `Databases` directory where the `rivet.json` file is located. ### Example 2 { "SqlServerName": ".\Rivet", "DatabasesRoot": "Databases", "ConnectionTimeout": 5, "CommandTimeout": 300, "IgnoreDatabases": [ "Shared" ], "DatabaseOrder": [ "Xanadu", "Q" ] } This example demonstrates how to use all the configuration options. This configuration file will: * connect to the local `.\Rivet` SQL Server instance * load database scripts from the `Databases` directory (which would be in the same directory as the `rivet.json` file) * shorten the connection timeout to 5 seconds * increase the command timeout to 5 minutes * not add the `Shared` database to the list of databases to manage (i.e. it will ignore the `$Databases\Shared` directory) * apply migrations to the "Xanadu" and "Q" databases before any others on the file file system. ### Example 3 { SqlServerName: '.\Rivet', DatabasesRoot: 'Databases', Environments: { UAT: { SqlServerName: 'uatdb\Rivet', IgnoreDatabases: [ 'Preview' ], CommandTimeout: 300 }, Production: { SqlServerName: 'proddb\Rivet', IgnoreDatabases: [ 'Preview' ], CommandTimeout: 600 } } } This example demonstrates how to create and use environment-specific settings. # See Also rivet.ps1 |