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.
 
    ### Databases
 
    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" ],
            "Databases": [ "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