capistrano-pg

Capistrano-Pg

Capistrano tasks for basic configuration and management of PostgreSQL database.

Provides capistrano tasks to:

• create database.yml in shared folder and symlink into config
• create user and database in postgres

Provides several capistrano variables for easy customization. Also, for full customization, template of database.yml file can be copied to the application using generator.

Installation

Add this line to your application's Gemfile:

gem 'capistrano-pg', require: false, group: :development

And then execute:

$ bundle

Or install it yourself as:

$ gem install capistrano-pg

Usage

Add this line to your deploy.rb

require 'capistrano-pg'

Next, add role pg to the server which has running instance of PostgreSQL. Address of this server will be automatically used as pg_host (see below), create_user and create_database tasks will be executed on this server:

# for dedicated database server it could look like this:
server "192.168.33.12", :db, :pg, no_release: true

# for all-in-one server it could look like this:
server "192.168.33.11", :web, :app, :db, :pg, primary: true

Note, that following capistrano variables should be defined in the deploy.rb file:

application
current_path
shared_path
user

You can check that new tasks are available (cap -T):

# create database user for the application
cap pg:create_user

# create database for the application
cap pg:create_database

# generates `database.yml` file in the `shared/config` folder
cap pg:setup

# symlinks `database.yml` from the `shared/config` folder to `current/config` folder
cap pg:symlink

There is no need to execute any of these tasks manually. They will be called automatically on different deploy stages:

• pg:create_user, pg:create_database and pg:setup are hooked to deploy:setup
• pg:symlink is hooked to deploy:finalize_update

This means that if you run cap deploy:setup, user and database will be created and database.yml file will be generated. And on each deploy, database.yml will be automatically linked to current version.

However, if you changed variables or customized templates, you can run any of these tasks to update configuration.

Customization

Using variables

You can customize database.yml using capistrano variables:

# path to customized templates (see below for details)
# default value: "config/deploy/templates"
set :templates_path, "config/deploy/templates"

# `host` value in `database.yml`
# default value: address of the server, marked with `pg` role
set :pg_host, "localhost"

# `port` value in `database.yml`
# default value: 5432
set :pg_port, "5432"

# `database` value in `database.yml`
# default value: application variable value
set :pg_database, "myapp_production"

# `pool` value in `database.yml`
# default value: 5
set :pg_pool, "5"

# `username` value in `database.yml`
# default value: application variable value
set :pg_user, application

# `password` value in `database.yml`
# default value: will be asked if not set
# setting this value in config file is not recommended
set :pg_password, application

# indicates, it new database should be created on `deploy:setup` or not
# default value: true
set :pg_create_db, true

Template Customization

If you want to change default template, you can generate it using rails generator

rails g capistrano:pg:config

This will copy default template to config/deploy/templates directory, so you can customize them as you like, and capistrano tasks will use this templates instead of default.

You can also provide path, where to generate template:

rails g capistrano:nginx_unicorn:config config/templates

TODO:

• add tests

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request