postgression

A PostgreSQL database for every test case.

What is postgression?

Testing can be a pain. As passionate programmers, we strive to write good code, good tests, and do as little as possible to make things work.

Unfortunately, when testing applications that involve databases, testing isn't very simple. To write good integration tests that exercise your application's functionality fully, you need to run your tests against the same type of database that your application will use in production (eg: minimize your dev / prod parity).

This is where postgression comes into play. postgression makes running your tests against a real PostgreSQL database a whole lot simpler.

Instead of running PostgreSQL server locally (or on your testing machine), maintaining the server, credentials, etc... postgression instantly provisions a new PostgreSQL database for your application to run tests against: for free!

Don't spend time setting up and maintaining a database for testing, use postgression and simplify your life!

How postgression Works

  1. Hit our API and get a brand new PostgreSQL database instantly. No account required:

    $ curl http://api.postgression.com
    postgres://user:password@host/db
    
  2. Now that you have a database, run your tests against this database. We're currently building a suite of testing plugins to make this easier.

  3. Your database will magically disappear in 30 minutes. All databases self destruct after 30 minutes. So as long as your tests run in 30 minutes or less, you're good to go!

Support postgression!

postgression is built on top of Heroku Postgres, the largest hosted PostgreSQL service in the world. If you're looking for a stable and feature-rich hosted PostgreSQL service, give Heroku Postgres a try, I promise you won't be disappointed!

Likewise, if you're new to Heroku, and looking for a great getting started guide, The Heroku Hacker's Guide is an excellent resource.

If you'd like to support postgression directly, you can tip either of us (the postgression maintainers) via Gittip. All funds go will go directly to paying for postgression hosting and maintenance. Currently, this costs about 55$ per month to run.

Using with Flask

If you're using the Flask python web framework, along with the Flask-SQLAlchemy and Flask-Testing packages, using postgression is very simple.

Other than Flask, Flask-SQLAlchemy, and Flask-Testing, you'll also need to install the requests library (this makes it possible for us to reserve a postgression database).

The example below shows a working test case that makes use of postgression:

from flask.ext.testing import TestCase
from requests import get

from myproject import app, db
from myproject.models import MyModel


class MyModelTest(TestCase):

    def create_app(self):
        """Configure our app to use a postgression database."""
        app.config['SQLALCHEMY_DATABASE_URI'] = get('http://api.postgression.com').text

    def setUp(self):
        """Prepare the database tables."""
        db.create_all()

    def tearDown(self):
        """Rip out the database tables to have a 'clean slate' for the next test case."""
        db.session.remove()
        db.drop_all()

    def test_mymodel_saves_properly(self):
        """Save our model to a postgression database, then ensure things are OK."""
        mymodel = MyModel()
        db.session.add(mymodel)
        db.session.commit()
        self.assertEqual(mymodel.id, 1)

Using with Sinatra, DataMapper and RSpec

Using postgression with Sinatra, DataMapper, and RSpec is also really easy.

The following example shows a working spec using postgression:

require File.join(File.dirname(__FILE__), 'app.rb')

require 'rack/test'
require 'sinatra'
require 'rspec'

set :environment, :test

RSpec.configure do |config|
  DataMapper::setup(:default, Net::HTTP.get('api.postgression.com', '/'))
  config.before(:each) { DataMapper.auto_migrate! }
end

describe 'App' do
  include Rack::Test::Methods

  def app
    Sinatra::Application
  end

  it 'creates a new user' do
    lambda do
      post '/new', params = { :email => 'postgression@gmail.com' }
    end.should {
      change(User, :count).by(1)
    }
  end
end

Using with Travis CI

If you're currently using Travis CI (a really awesome continuous integration platform) to run your tests, you can easily add postgression support by modifying your .travis.yml file and adding:

env:
- DATABASE_URL=$(curl http://api.postgression.com)

That's it! Assuming your application then uses the DATABASE_URL environment variable to point to your database, you should have perfect integration :)

Using with Other Systems

We've been working hard to build lots of tools that make postgression even easier to use with your favorite web framework, library, and operating system.

Check out our Github organization to view our latest libraries, apps, and integration tools.

If you'd like to build support for postgression into your favorite piece of software, please shoot us an email (postgression@gmail.com)--we'd love to link to it in our documentation.

API Documentation

To request a database, you can hit our public API endpoint, located at http://api.postgression.com (with a GET request).

By default, you'll receive a PostgreSQL URL of the form postgres://user:pass@host:port/dbname.

If you'd like to receive your PostgreSQL database credentials in JSON format, you can specify an Accept or Content-Type HTTP header when making your request, eg:

$ curl -H 'Accept: application/json' 'http://api.postgression.com'
{
  "dbname": "dbname",
  "username": "username",
  "password": "password",
  "port": 123,
  "host": "blah.blah.com"
}

There is currently a rate limit of 100 requests per hour, per IP address, which helps us prevent abuse of the system. If you attempt to provision more than 100 databases in an hour, you'll start receiving HTTP 403 FORBIDDEN responses until the hour has ended.

In regards to security: postgression does not look at, log, or use any data stored by our users. All data is completely ephemeral, and disappears after 30 minutes.