This guide should get you started using dbversion as quickly as possible. For simplicity, the guide assumes that you are using Microsoft SQL Server. For information about using the tool against different databases, see Documentation:Commands:Connections.

To get dbversion, you can either download the latest version, or you can clone the source from GitHub and build it using Visual Studio.

The files for creating the versions of your database are stored inside the Documentation:Archives. The archive is just a collection of Documentation:DatabaseManifest files along with the scripts used to create each version of the database. Currently a file based archive and a zip based archive are available, but for this tutorial we will use the file based archive.

The following diagram shows the directory structure of the sample project that we will be using:

classic-sample
├── 1
│   ├── data
│   │   ├── authors.sql
│   │   ├── books.sql
│   │   └── users.sql
│   ├── database.xml
│   └── schema
│       └── ddl.sql
└── 2
    ├── database.xml
    ├── ddl.sql
    └── migrateUserEmails.sql

Note: this project can be found in the source code in the samples/classic-sample directory.

The project is arranged into a separate directory for each version. Within each directory is a database manifest file, along with the scripts to create that version. In general the name of the version directory should match the name of the version, but this is just a convention and is not for any technical reason.

Each database manifest contains a version number along with a series of tasks to execute to install that version. Any paths mentioned inside the manifest are relative to the manifest file.

When the tool runs, it compares the current version of the database with the versions available, and then runs all the scripts mentioned in the manifest files in the order they are defined to upgrade the database to the required version. The tool attempts to run the scripts inside a transaction so that the changes can be rolled back if any errors occur. This is not supported by all databases - for example MySQL and Oracle - so you should not rely on this behaviour.

To run the tool you should use the Documentation:Commands:Create command:

Adams-MacBook-Air:Debug adamconnelly$ ./dbversion create -a"/Users/adamconnelly/bzr/dbversion/saved-connection/samples/classic-sample" -c"Server=localhost;Database=library;User Id=adamconnelly;Password=password;"
Starting Database Update
Current Database Version Unknown
Target Version: 2.0
…
Starting Task 7 of 7: Inserting version "2.0"
Finished Task 7 of 7: Inserting version "2.0 - 31/12/2011 14:10:02". Time Taken: 00:00:00.0006720, 100% complete
Finished Database Update. Time Taken: 00:00:00.5241060

Your database is now installed! You can take a look at the Version and VersionTask tables in your database to see what has been installed. You can also use the dbversion history command which will be outlined below.

If you add a new version into the archive, you just need to run the same command again to upgrade the database to the latest version. This time the tool will not run the versions that have already been installed, but will run any new versions.

Sometimes you may need to create a database at a specific version, or upgrade an existing database to a certain version. This can be useful, for example, if you need to investigate a bug that affects a certain version of the database. In this case you would specify your target version using the -v command line switch:

Adams-MacBook-Air:Debug adamconnelly$ ./dbversion create -a"/Users/adamconnelly/bzr/dbversion/saved-connection/samples/classic-sample" -c"Server=localhost;Database=library;User Id=adamconnelly;Password=password;" -v 1.0

The Documentation:Commands:SavedConnection command allows named connection information to be saved. This means that you don't need to type out connection strings each time you run a command.

To create a new saved connection, run the following command:

Adams-MacBook-Air:Debug adamconnelly$ ./dbversion saved-connection -n"my-connection" -c"Data Source=localhost;Initial Catalog=library;Integrated Security=true;" -p NHibernate.Dialect.DriverConnectionProvider -d"NHibernate.Driver.SqlClientDriver" -l "NHibernate.Dialect.MsSql2005Dialect"
Created new saved connection "my-connection":
  Connection String: Data Source=localhost;Initial Catalog=library;Integrated Security=true;
  Driver Class: NHibernate.Driver.SqlClientDriver
  Provider: NHibernate.Dialect.DriverConnectionProvider
  Dialect: NHibernate.Dialect.MsSql2005Dialect
  Default: True

If this is the first saved connection you have specified, it will become the default connection. This means that if you don't specify any connection information when running dbversion, the default connection will be used. You probably want to setup your development database as your default connection so that you don't need to specify it each time.

You can use the Documentation:Commands:History command to get information about the current version of a database, along with historical information about when the versions were installed:

Adams-MacBook-Air:Debug adamconnelly$ ./dbversion history
2.0 Installed - 31/12/2011 14:20:22, Updated - 31/12/2011 14:20:22
1.0 Installed - 31/12/2011 14:18:18, Updated - 31/12/2011 14:18:18