Skip to main content


Setup your application with PostgreSQL

Follow the instructions in the installation guide below that corresponds to your operating system:

  1. macOS
    • PostgreSQL installation as a Mac app
    • Homebrew: if you use Homebrew you can easily install PostgreSQL with brew install postgresql
  2. Linux (Ubuntu)
  3. Windows

You can find all installation options for a variety of operating systems on the official PostgreSQL download page.


By default, the application is configured to connect to a local database named PracticalDeveloper_development. If you need to specify a username and a password, you can go about it by using the environment variable DATABASE_URL with a connection string.

The official Rails guides go into depth on how Rails merges the existing database.yml with the connection string.

Setup DATABASE_URL in .env

  1. Open your .env

  2. Add the following:

export DATABASE_URL=postgresql://USERNAME:PASSWORD@localhost
  1. Replace USERNAME with your database username, PASSWORD with your database password.

You can find more details on connection strings in PostgreSQL's own documentation.

NOTE: due to how Rails merges database.yml and DATABASE_URL it's recommended not to add the database name in the connection string. This will default to your development database name also during tests, which will effectively empty the development DB each time tests are run.

Because the test environment is loaded separately, if you are running tests and need to provide a postgresql url, set the DATABASE_TEST_URL variable in a file named .env.test.local

# Optional: If your test database is in a different url, be sure to set this.
export DATABASE_URL_TEST=postgresql://USERNAME:PASSWORD@localhost

Connection Pooling

We use PgBouncer to manage connection pooling.

Database pooling creates a shared pool of connections to our database, rather than creating new connection each time. PgBouncer is a wrapper around our database connection and ensures that we only have a finite set of "cached" connections to the database. This means that our app doesn't need to actually connect to the database, it only needs to connect to the pool of connections. The number of connections to the database (the connection limit) is dependent on our Heroku Postgres plan. PgBouncer ensures that we do not exceed our plan's connection limit.