piisalie / nomadize

Some utilities for managing migrations with PostgreSQL

Nomadize

Nomadize is a collection of rake tasks for managing migrations using a PostgreSQL database. It does not import an entire ORM and aims to be a small / simple utility.

Installation

Add this line to your application's Gemfile:

gem 'nomadize'

And then execute:

$ bundle

Or install it yourself as:

$ gem install nomadize

Usage

Nomadize supports two different methods for configuring the connection to Postgres. Nomadize will also provide access to the underlying PG connection wrapper (using your defined config) by using the Nomadize::Config.db method. This wrapper responds to exec in the same way that the underlying PG connection object does.

Config File

You may use a config file config/database.yml. This file can be generated with either the rake task: db:generate_template_config or the CLI: $ nomadize generate_template_config. You can also choose to create the file for yourself. config/database.yml should look something like:

development:
  :dbname: lol_dev
test:
  :dbname: lol_test
production:
  :dbname: lol_production

The test/development/production keys define environment dependent options for the PG.connection based on the environment set via RACK_ENV. These key/value pairs are handed directly to the PG.connect method, documentation for what options can be passed can be found here.

ENV['DATABASE_URL']

As of 0.4.0 Nomadize will also respect the DATABASE_URL environment variable. If DATABASE_URL is set it will override the connection information in the config file config/database.yml. eg postgres://user1:supersecure@somehost:1337/database-name will result in the following configuration hash being passed to the underlying PG.connection object.

{
  dbname:   'database-name',
  port:     1337,
  user:     'user1',
  password: 'supersecure',
  host:     'somehost'
}

Migrations

After a config file is in place add require 'nomadize/tasks' to your rake file, and enjoy helpful new rake tasks such as:

• rake db:create - creates a database and a schema_migrations table
• rake db:drop - dumps your poor poor database
• rake db:new_migration[migration_name] - creates a timestamped migration file in db/migrations/ just fill in the details.
• rake db:migrate - runs migrations found in db/migrations that have not been run yet
• rake db:status - see which migrations have or have not been run
• rake db:rollback[count] - rollback migrations (default count: 1)
• rake db:generate_template_config - generate a config file in config/database.yml

Alternatively you can use the commandline tool nomadize:

• nomadize create - creates a database and a schema_migrations table
• nomadize drop - dumps your poor poor database
• nomadize new_migration $migration_name - creates a timestamped migration file in db/migrations/ just fill in the details.
• nomadize migrate - runs migrations found in db/migrations that have not been run yet
• nomadize status - see which migrations have or have not been run
• nomadize rollback $count - rollback migrations (default count: 1)
• nomadize generate_template_config - generate a config file in config/database.yml

Migrations are written in SQL in the generated YAML files:

---
:up:   'CREATE TABLE testing (field TEXT);'
:down: 'DROP TABLE testing;'

Development

todo:

• an actual config setup / object
• sql cleaning (getting rid of the interpolation)
• to display migration status
• migration rollbacks
• transactions / error handling
• maybe some kind of logging idk
• possibly wrap pg
• template config file generator
• maybe set a default migrations path (so the key isn't required in the config file)

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/piisalie/nomadize. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Changelog

0.4.2

• Make migrations path hard coded (this fixes an issue with heroku overwriting the database.yml file)

0.4.1

• Fix a bug with command line utility using and incorrect method name.

0.4.0

• support DATABASE_URL env variable
• Add template_config generator to command line tool
• Update the README
• Added some basic logging
• Fix an issue with rollback count not actually working :'(

0.3.0

• Include a command line interface for Nomadize commands (THANKS @moonglum)

0.2.0

• migration_path setting now has a default instead of being a required option in config/database.yml
• Reworded some of the README.md
• Added a rake task to generate a template config file in config/database.yml

0.1.0 - Initial Release

nomadize's Issues

Checksum columns

Noah Gibbs suggested a checksum column for schema_migrations. https://twitter.com/codefolio/status/664209688691523584

Maybe support separate .sql files?

Just a thought - large chunks SQL in YAML could get awkward. It might be nice to be able to break them out into .sql files.

Feel free to ignore my random bikeshedding. 😄