Brazil is a tool to track schema changes to database instances. It is implemented in Ruby on Rails and support deployment of changes to Ruby DBI supported databases (currently MySQL, Oracle and PostgreSQL).
New features or bugs can be reported to Brazil's issue tracker on github.
To setup Brazil you need to follow these steps:
- Copy config/database.example to config/database.yml
- Setup version control configuration in config/config.yml, by following the Version Control section.
Brazil requires Ruby on Rails 2.2.2, Ruby DBI, RIO and Subversion binding for Ruby. Ruby DBI DBD drivers and their dependencies are required for any deploy database you want to use.
Module sqlite3-ruby is required to use the default database configuration.
Mongrel is recommended for local development and Phusion Passenger is recommended for production deployment.
Brazil is a standard Ruby on Rails application. After following the installation steps, start it by running, for example, the server script:
Schema Version Table
Brazil requires a
schema_versions table as specified below to function correctly. If it does not exist, it will try to create it when deploying a version for the first time.
CREATE TABLE schema_versions ( major int NOT NULL, minor int NOT NULL, patch int NOT NULL, created int NOT NULL, description varchar(255), PRIMARY KEY (major, minor, patch) );
You can setup a example database with some example Database Instances, Apps, Activities, Changes and Versions. This will reset the database, so please make a copy of db/development.sqlite3 if there is something you want to keep. Run
rake brazil:reset to setup the example db.
Brazil enables you to check in the generated update and rollback SQL for each Version you make. There are three configuration values in config/config.yml that need to be setup for this to work:
- vc_type needs to be set to your version control of choice, currently only Subversion is supported, with the value set to
- vc_uri needs to be set your version control repository root. In the case of subversion, something like http://example.com/svn.
- vc_dir needs to be a, writable by brazil, directory that is used to checkout working copies.
Each App created in Brazil then needs to define its own version control path, which is relative to
vc_uri. To allow brazil to check it out and commit to it when a Version is deployed.
Brazil allows for Changes to be tracked in each App by a named Activity. Changes can be executed on a designated development database instance / schema pair when created or only saved to track existing Changes.
The collected Changes to an Activity can then be turned into Versions and deployed to one or several test database instance / schema pairs. A Version can be marked as deployed when it's been confirmed to have been deployed to the production system.
Example: App FooBar
You have an application called
FooBar which is in the subversion module
http://example.com/svn/foobar/trunk, that you want to do some database schema changes to.
First you need change your config.yml to contain the config value
vc_uri set to
http://example.com/svn. Any changes to this file requires that you restart brazil to take effect.
In brazil, create an application named
FooBar, with the
Version Control Path set to
Since your database changes for
FooBar are connected to a
Change Request numbered 4711 and related to the database schema
baz, you create a new Activity in
CR4711, which uses a
Development Database and will update the
baz database schema.
You can then start to enter the SQL updates, by creating new Changes in the
CR4711 Activity. Each Change should (preferably) contain one database (SQL) statement each.
When you've entered all your Changes into an Activity, you must create a version of that Activity, to be able to deploy them to your test database and later on, you production database.
Brazil includes the following third party libraries:
- Blueprint CSS
- jQuery, jQuery UI, jQuery Scroll Follow, jQuery Form
- Twotiny Icon Set
The following people have made contributions to Brazil. Please let me know if I've missed anyone.
- Conny Dahlgren
- Mattias Hising
- Christer Utterberg
- Urban Edlund
Copyright (c) 2008, 2009 Joakim Bodin, MIT License.