// Tutorial //

How To Use PostgreSQL with Your Ruby on Rails Application on Ubuntu 20.04

How To Use PostgreSQL with Your Ruby on Rails Application on Ubuntu 20.04
Not using Ubuntu 20.04?Choose a different version or distribution.
Ubuntu 20.04


When using the Ruby on Rails web framework, your application will use SQLite as a database by default. SQLite is a lightweight, portable, and user-friendly relational database that performs especially well in low-memory environments, so it will work well in many cases. However, for highly complex applications that need more reliable data integrity and programmatic extensibility, a PostgreSQL database will be a more robust and flexible choice. You will need to perform additional steps to configure your Ruby on Rails setup to use PostgreSQL.

In this tutorial, you will set up a Ruby on Rails development environment connected to a PostgreSQL database on an Ubuntu 20.04 server. You will install and configure PostgreSQL, then test your setup by creating a Rails application that uses PostgreSQL as its database server.


This tutorial requires the following:

Step 1 – Installing PostgreSQL

To configure Ruby on Rails with PostgreSQL as a database for your web application, you will first install the database onto your server.

Using sudo privileges, update your APT package index to make sure that your repositories are up to date:

  1. sudo apt update

Next, install PostgreSQL and its development libraries:

  1. sudo apt install postgresql postgresql-contrib libpq-dev

In the previous command, the postgresql package holds the main PostgreSQL program, while postgresql-contrib adds several PostgreSQL features that extend its capabilities. libpq-dev is a PostgreSQL library that allows clients to send queries and receive responses from the back-end server, which will allow your application to communicate with its database.

Once PostgreSQL and its dependencies are installed, the next step is to create a role that your Rails application will use later to create your database.

Step 2 – Creating a New Database Role

In PostgreSQL, roles can be used to organize permissions and authorization in the same way as users can in Linux. In this step, you will create a new super user role for your Linux username that will allow you to create and configure databases within the PostgreSQL system.

To create a PostgreSQL super user role, run the following command, substituting the highlighted word with your Ubuntu 20.04 username:

  1. sudo -u postgres createuser -s sammy -P

Since you specified the -P flag, you will be prompted to enter a password for your new role. Enter your desired password, making sure to record it so that you can use it in a configuration file in a later step.

You use createuser to create a role named sammy (or your preferred username). The -s flag gives this user super user privileges, and sudo -u allows you to run the command from the postgres account that is automatically created upon installing PostgreSQL.

Note: Since the authentication mode for PostgreSQL on Ubuntu starts out as ident, by default an Ubuntu user can only operate in PostgreSQL with a role of the same name. For more information, check out the PostgreSQL official documentation on authentication.

If you did not use the -P flag and want to set a password for the role after you create it, enter the PostgreSQL console with the following command:

  1. sudo -u postgres psql

You will receive the following output, along with the prompt for the PostgreSQL console:

psql (12.12 (Ubuntu 12.12-0ubuntu0.20.04.1)) Type "help" for help. postgres=#

The PostgreSQL console is indicated by the postgres=# prompt. At the PostgreSQL prompt, enter this command to set the password for the new database role, replacing the highlighted name with the one you created:

  1. \password sammy

PostgreSQL will prompt you for a password. Enter your desired password at the prompt, then confirm it.

Now, exit the PostgreSQL console by entering this command:

  1. \q

Your usual prompt will now reappear.

In this step, you created a new PostgreSQL role with super user privileges. Now you are ready to create a new Rails app that uses this role to create a database.

Step 3 – Creating a New Rails Application

With a role configured for PostgreSQL, you can now create a new Rails application that is set up to use PostgreSQL as a database.

First, navigate to your home directory:

  1. cd ~

Create a new Rails application in this directory, replacing appname with whatever you would like to call your app:

  1. rails new appname -d=postgresql

The -d=postgresql option sets PostgreSQL as the database.

Once you’ve run this command, a new folder named appname will appear in your home directory, containing all the elements of a basic Rails application.

Next, move into the application’s directory:

  1. cd appname

Now that you have created a new Rails application and have moved into the root directory for your project, you can configure and create your PostgreSQL database from within your Rails app.

Step 4 – Configuring and Creating Your Database

When creating the development and test databases for your application, Rails will use the PostgreSQL role that you created for your Ubuntu username. To ensure that Rails creates these databases, you will alter the database configuration file of your project. You will then create your databases.

One of the configuration changes to make for your Rails application is to add the password for the PostgreSQL role created in the last step. To keep sensitive information like passwords safe, it is recommended to store the password in an environment variable rather than to write it directly in your configuration file.

To store your password in an environment variable at login, run the following command, replacing APPNAME with the name of your app and PostgreSQL_Role_Password with the password you created in the last step:

  1. echo 'export APPNAME_DATABASE_PASSWORD="PostgreSQL_Role_Password"' >> ~/.bashrc

This command writes the export command to your ~/.bashrc file so that the environment variable will be set at login.

To export the variable for your current session, use the source command:

  1. source ~/.bashrc

Now that you have stored your password in your environment, you can alter the configuration file.

Open your application’s database configuration file in your preferred text editor. This tutorial will use nano:

  1. nano config/database.yml

Under the default section, find the line that says pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %> and add the following highlighted lines, filling in your credentials and the environment variable you created. It should look something like this:

default: &default
  adapter: postgresql
  encoding: unicode
  # For details on connection pooling, see Rails configuration guide
  # http://guides.rubyonrails.org/configuring.html#database-pooling
  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
  username: sammy

  <<: *default
  database: appname_development

This update will make the Rails application run the database with the correct role and password. Save and exit by pressing CTRL + x, Y, then ENTER.

For more information on configuring databases in Rails, see the Rails documentation.

Now that you have made changes to config/database.yml, create your application’s databases by using the rails command:

  1. rails db:create

Once Rails creates the database, you will receive the following output:

Created database 'appname_development' Created database 'appname_test'

As the output suggests, this command created a development and test database in your PostgreSQL server.

You now have a PostgreSQL database connected to your Rails app. To ensure that your application is working, you will now test your configuration.

Step 5 – Testing Your Configuration

To test that your application is able to use the PostgreSQL database, you will run your web application so that it will show up in a browser.

Using the rails server command, run your web application on the built-in webserver in your Rails app, Puma:

  1. rails server --binding=

--binding binds your application to a specified IP. By default, this flag will bind Rails to, which means that Rails will listen to all interfaces, so it is more secure to use to specify the localhost. By default, the application listens on port 3000.

Once your Rails app is running, your command prompt will disappear, replaced by this output:

=> Booting Puma => Rails 7.0.4 application starting in development => Run `bin/rails server --help` for more startup options Puma starting in single mode... * Puma Version 5.6.5 (ruby 3.1.2-p20) ("Birdie's Version") * Min threads: 5 * Max threads: 5 * Environment: development * Listening on tcp:// Use Ctrl-C to stop

To test if your application is running, open up a new terminal window on your server and use the curl command to send a request to

  1. curl

You will receive a lot of output in HTML, ending in something like:

... <strong>Rails version:</strong> 7.0.4<br /> <strong>Ruby version:</strong> 3.1.2 (x86_64-linux) </p> </section> </div> </body> </html>

If your Rails application is on a remote server and you want to access it through a web browser, you can bind it to the public IP address of your server. First, open port 3000 in your firewall:

  1. sudo ufw allow 3000

Next, look up the public IP address of your server. You can do this by running the following curl command:

  1. curl http://icanhazip.com

This will return your public IP address. Use it with the rails server command, substituting server_public_IP with your server’s public IP:

  1. rails server --binding=server_public_IP

Now you will be able to access your Rails application in a local web browser via the server’s public IP address on port 3000 by visiting:


At this URL, you will find a Ruby on Rails page:

Ruby on Rails Page

If you can access the home page, your application is properly configured and connected to the PostgreSQL database.

After testing the configuration, if you would like to close port 3000, use the following command.

  1. sudo ufw delete allow 3000


In this tutorial, you created a Ruby on Rails web application that was configured to use PostgreSQL as a database on an Ubuntu 20.04 server. If you would like to learn more about the Ruby programming language, check out our series on How To Code in Ruby.

For more information on choosing a database for your application, check out our tutorial on the differences between and use cases of SQLite, PostgreSQL, and MySQL. If you want to read more about how to use databases, see An Introduction to Queries in PostgreSQL article, or explore DigitalOcean’s Managed Databases product.

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about us

About the authors

Default avatar

Senior Technical Editor

Editor at DigitalOcean, fiction writer and podcaster elsewhere, always searching for the next good nautical pun!

Default avatar

Technical Editor

Still looking for an answer?

Ask a questionSearch for more help

Was this helpful?

This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

Thank you for this. It was of much help.

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!

Sign up

card icon
Get our biweekly newsletter

Sign up for Infrastructure as a Newsletter.

Sign up
card icon
Hollie's Hub for Good

Working on improving health and education, reducing inequality, and spurring economic growth? We’d like to help.

Learn more
card icon
Become a contributor

You get paid; we donate to tech nonprofits.

Learn more
Welcome to the developer cloud

DigitalOcean makes it simple to launch in the cloud and scale up as you grow – whether you’re running one virtual machine or ten thousand.

Learn more ->
DigitalOcean Cloud Control Panel
Get started for free

Enter your email to get $200 in credit for your first 60 days with DigitalOcean.

New accounts only. By submitting your email you agree to our Privacy Policy.

© 2023 DigitalOcean, LLC.