jam-cloud/README

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
--------
jam-db defines the migrations that comprise the jam-db database.  It uses pg_migrate to package up the migrations iinto 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.

Environmenti
-----------
* [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)
* 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;