jam-db
======

Schema migrations for the jam-db database.  Uses the [pg_migrate tool](https://github.com/sethcall/pg_migrate) tool.  The github page of pg_migrate also has some documentation and rationale behind this approach of migrations.

Overview
--------
am-db defines the migrations that comprise the jam-db database.  It uses pg_migrate to package up the migrations into a gem or (TODO) jar. You can then use those packaged up versions of the schemas in downstream projects.

The main reason the 'pg_migrate' approach is taken is to make to possible to use the database like an interface, freed from any one project or language.

Environment
-----------
* [rvm](https://rvm.io/) with ruby 1.9.3 installed and activated.  rvm needs to be activated in your shell (the installation process does this)
* bash . If on windows, use git bash or cygwin. Bash is used as the build script technology.  (could change very easily)
* Definition of location for your developer workspace. Default is ~/workspace, but if you define an env variable, you can override.
* pg_migrate_ruby - $ cd [workspace] && git clone https://github.com/sethcall/pg_migrate_ruby
* you want it so the current user has access to the 'postgres' database and is a super user.  In other words, you want to make sure your current logged in user can do the following at the command line: 'psql postgres'.  If you can do that, you should be OK.  There are two reasons this may not work for you.  
# Your current user is not a superuser.  If not, do `sudo su postgres -c "createuser YOURUSER"`  and answer 'y' with the first question.
# If your user already is a superuser, then the postgres database may not exist yet. In that case, do `psql` then `create database postgres`
* NOT YET: $IVY defined as path to the [apache ivy jar](http://ant.apache.org/ivy/download.cgi). Download the latest ivy from here, extract somewhere, and create an IVY environment variable with a path to the ivy.jar. For example, in my bash.profile: `export IVY=/Users/seth/workspace/apache-ivy-2.3.0-rc1/ivy-2.3.0-rc1.jar`

Building
--------
# one-time: if you just installed rvm, cd into this project's base directory.  rvm will ask you to trust the .rvmrc.  Do so.
# type:
 ./build # this will clean your 'target' directory, and rebuild from scratch. It takes seconds.

Using
-----

In a ruby project, create in your gemfile something like:
`
https 'https://rubygems.org'

gem 'jam_db', :path => '~/workspace/jam-db/target/ruby_package'
`
Then, to cause a migration, do something like:

# make sure you have the jam_db gem
bundle install

# migrate the database (assumes you've created the 'jam' database already).
bundle exec jam_db --connopts="dbname:jam host:localhost user:postgres password:postgres" --verbose

# you can see if it worked by typing:

psql jam
> select * from pgmigrate.pg_migrate;