en-US/about_Rivet.help.txt
|
TOPIC
about_Rivet SHORT DESCRIPTION Rivet is a database migration/change management/versioning tool inspired by Ruby on Rails' Migrations. You write PowerShell migration scripts that describe the changes you want to make to a SQL Server database, e.g. add a table, add a column, drop an index, etc. Rivet applies those scripts to a database, bringing its schema up-to-date. To get started, download Rivet from the PowerShell gallery: > Save-Module -Name 'Rivet' -Path '.' This will save Rivet into a `Rivet` directory in your current directory. (If you're running PowerShell 4, you'll need to download and install [PowerShell Package Management Modules Preview](https://www.microsoft.com/en-us/download/details.aspx?id=51451).) You can also [download a ZIP file from the Rivet project's GitHub page](https://github.com/webmd-health-services/Rivet/releases). Unzip the file, and drag the `Rivet` directory where you'd like it. Next, you'll need to create a `rivet.json` file that contains a connection string to your database and the path where you want to keep your migration scripts. The simplest configuration file looks like this: { SqlServerName: '.\Rivet', DatabasesRoot: 'Databases' } With this configuration file, Rivet will connect to the SQL Server at `.\Rivet` and will look for migration scripts in `Databases\DATABASE_NAME\Migrations`. Now you can create your first migration. Run: > .\Rivet\rivet.ps1 -New -Database DATABASE_NAME -Name 'MyFirstMigration' Rivet will create a migration at `Databases\DATABASE_NAME\Migrations\20170625132040_MyFirstMigration.ps1`. The migration's filename has two parts: an ID (e.g. `20170625132040` followed by the migration's name. Rivet uses the ID to track what migrations have been applied to a database. Open the migration in your favorite PowerShell text editor. We recommend the PowerShell ISE, because of its intellisense and debugging capabilities. (To get Intellisense as you type, import Rivet first: `Import-Module '.\Rivet'`.) You'll see two functions: `Push-Migration` and `Pop-Migration`. In the `Push-Migration` function, you'll add Rivet operations that modify your database. In the `Pop-Migration` function, you'll add operations that reverse/rollback the changes made in `Push-Migration`. Let's create a table: function Push-Migration { Add-Table -Name 'MyFirstTable' -Column { int 'id' -Identity } } function Pop-Migration { Remove-Table -Name 'MyFirstTable' } To apply your migration to your database, run `rivet.ps1` with its `-Push` switch: > .\Rivet\rivet.ps1 -Push Look in your database and it will contain the `MyFirstTable` table. By default, pushing migrations pushes them to *all* your databases. If you only want to push to a single or specific databases, use Rivet's `Database` parameter: > .\Rivet\rivet.ps1 -Push -Database 'DATABASE_NAME' To reverse/rolllback your migration run `rivet.ps1` with the `Pop` switch: > .\Rivet\rivet.ps1 -Pop This will pop the newest migration in each database's `Migrations` directory. (Use the `Database` parameter to pop the newest migration from specific databases.) Look in your database, and the `MyFirstTable` database is gone. Next, let's add another column to our table: function Push-Migration { Add-Table -Name 'MyFirstTable' -Column { int 'id' -Identity nvarchar 'name' 50 -NotNull } } You didn't have to modify the `Pop-Migration` function because it removes the table, so you don't need to remove each column. As you work on your migration, you'll be changing your `Push-Migration` function to get it just right. You'll have to do a lot of pushing and popping. Rivet has a special `Redo` switch that does a pop followed by a push: > .\Rivet\rivet.ps1 -Redo After you run this command, look in your database and you'll see that the `MyFirstTable` table now has a `name` column. Once your migration is done, commit it to your source control repository. Once you make your migration available to others, ***it is immutable and should never be changed***. Rivet applies migration scripts as an entire unit. It uses each migration's ID to determine if that migration has been applied to a database. If it has been applied, Rivet skips it and moves on to the next migration. So, if you modify a migration after it's public, that change will never get applied anywhere. If you need to change a public migration, create a new migration that makes the changes you need. Rivet wraps all pushes and pops in a transaction. If any part of a migration fails, the entire transaction is rolled back. Your database will never be left in a state where part of a migration is applied. To see a full list of operations, run this command: > Get-Command -Module 'Rivet' Or, [visit the Documentation page at the https://get-rivet.org website](http://get-rivet.org/documentation.html). See the `about_Rivet_Configuration` topic for details on configuring Rivet in the `rivet.json` file. The `about_Rivet_Plugins` topic explains how to write your own Rivet operations. SEE ALSO about_Rivet_Configuration about_Rivet_Intellisense about_Rivet_Migrations about_Rivet_Plugins |