How To Use PostgreSQL with Your Ruby on Rails Application on macOS

How To Use PostgreSQL with Your Ruby on Rails Application on macOS

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



When using the Ruby on Rails web framework, your application is set up by default to use SQLite as a database. SQLite is a lightweight, portable, and user-friendly relational database that performs especially well in low-memory environments, and 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. In order to configure your Ruby on Rails setup to use PostgreSQL, you will need to perform a few additional steps to get it up and running.


This tutorial requires the following:

  • One computer or virtual machine with macOS installed, with administrative access to that machine and an internet connection.
  • A Ruby on Rails development environment installed on your macOS machine. To set this up, follow our guide on How To Install Ruby on Rails with rbenv on macOS. This tutorial will use version 2.6.3 of Ruby and 5.2.3 of Rails; for information on the latest versions, check out the official sites for Ruby and Rails.
Step 1 — Installing PostgreSQL

In order to configure Ruby on Rails to create your web application with PostgreSQL as a database, you will first install the database onto your machine. Although there are many ways to install PostgreSQL on macOS, this tutorial will use the package manager Homebrew.

There are multiple Homebrew packages to install different versions of PostgreSQL. To install the latest version, run the following command:

brew install postgresql

If you would like to download a specific version of PostgreSQL, replace postgresql in the previous command with your desired package. You can find the available packages at the Homebrew website.

Next, include the PostgreSQL binary in your PATH variable in order to access the PostgreSQL command line tools, making sure to replace the 10 with the version number you are using:

echo 'export PATH="/usr/local/opt/[email protected]/bin:$PATH"' >> ~/.bash_profile

Then, apply the changes you made to your ~/.bash_profile file to your current shell session:

source ~/.bash_profile

To start the service and enable it to start at login, run the following:

brew services start [email protected]

Check to make sure the installation was successful:

postgres -V

You will get the following output:

postgres (PostgreSQL) 10.9 

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

Step 2 — Creating a Database Role for Your Application

In PostgreSQL, roles can be used to organize permissions and authorization. When starting PostgreSQL with Homebrew, you will automatically have a superuser role created with your macOS username. In order to keep these superuser privileges separate from the database instance you use for your Rails application, in this step you will create a new role with less access.

To create a new role, run the following command, replacing appname with whatever name you'd like to give the role:

createuser -P -d appname

In this command, you used createuser to create a role named appname. The -d flag gave the role the permission to create new databases.

You also specified the -P flag, which means 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 future step.

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:

psql postgres

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

psql (10.9)
Type "help" for help.

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:

\password appname

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:


Your usual prompt will now reappear.

In this step, you created a new PostgreSQL role without superuser privileges for your application. 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 your 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:

cd ~

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

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:

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 in Step 2. To make sure 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 in your Rails application is to add the password for the PostgreSQL role you created in the last step. To keep sensitive information like passwords safe, it is a good idea to store this 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:

echo 'export APPNAME_DATABASE_PASSWORD="PostgreSQL_Role_Password"' >> ~/.bash_profile

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

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

source ~/.bash_profile

Now that you have stored your password in your environment, it's time to alter the configuration file.

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

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
  username: appname
  <<: *default
  database: appname_development

This 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:

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, the next step is to test your configuration.

Step 5 — Testing Your Configuration

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

First, you'll use the built-in web server for Rails, Puma, to serve your application. This web server comes with Rails automatically and requires no additional setup. To serve your application, run the following command:

rails server --binding=

--binding binds your application to a specified IP. By default, this flag will bind Rails to, but since this means that Rails will listen to all interfaces, 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 5.2.3 application starting in development
Puma starting in single mode...
* Version 3.12.1 (ruby 2.6.3-p62), codename: Llamas in Pajamas
* 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


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

        <strong>Rails version:</strong> 5.2.3<br />
        <strong>Ruby version:</strong> 2.6.3 (x86_64-darwin18)

You can also access your Rails application in a local web browser by visiting:

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

This means that your application is properly configured and connected to the PostgreSQL database.


In this tutorial, you created a Ruby on Rails web application that was configured to use PostgreSQL as a database on a local macOS machine.

Ruby vs Ruby on Rails web framework

Rails is a development tool which gives web developers a framework, providing structure for all the code they write. The Rails framework helps developers to build websites and applications. Ruby is a programming language stronger than Perl and more object-oriented than Python. It is being developed with increasing productivity.

Ruby on Rails vs PHP

Ruby on Rails vs PHP

Understanding the pros and cons of Ruby on Rails versus PHP is important when deciding how to create your business-critical applications.

Originally published at

There’s more than one way to build a web application. No matter what type of application you are trying to create, your programmers have their preferred approach and their preferred code languages to accomplish the task. In the world of web applications, most program developers have to decide between Ruby on Rails versus PHP.

Ruby on Rails consists of Ruby, which is a scripting language, and Rails, which is a web development framework; PHP is a server-side scripting language. Both programming languages have been around since the mid-1990s, but PHP rules the web, while Ruby on Rails is more popular for business web applications. Understanding the pros and cons of Ruby on Rails versus PHP is important when deciding how to create your business-critical applications.

Ruby on Rails Versus PHP at First Glance

Both Ruby on Rails and PHP are open source, so there are no licensing fees. However, because PHP is used to run most of today’s web systems, there are more PHP programmers than Ruby developers, which means there is a larger pool of PHP experts and a larger open source library to draw from.

Part of the reason PHP is more popular with web developers is because it is easier to learn. PHP is also an object-oriented programming language, which makes it easier to be more creative and tackle tougher software challenges.

Once web developers master PHP, many of them choose to add Ruby on Rails to their expertise because of the advantages and power that Ruby on Rails offers for business application development. Ruby and Rails were created together to deliver web solutions, and the primary difference between PHP and Ruby on Rails is that Rails requires you to understand the full stack, including the web server, application server, and database engine.

Since both Ruby and PHP are open source, the support of the programming communities is an important differentiator. PHP has more deployments so it has a larger developer community, but the Ruby on Rails community is very skilled and enthusiastic and they want to share, so there is a growing library of ready-to-use Ruby gems.

Differences in Deployment

When it comes to deployment, PHP is very easy to implement. You simply transfer files to the web server via FTP and that’s it. With PHP, you don’t need to worry about the web stack. Most hosting services use a combination of open source for the stack, including Linux, Apache, MySQL, and PHP (LAMP), so once the files are loaded, they just run. That’s the advantage of server-side software.

Ruby on Rails is more complex to deploy because you have to know the full stack. That means knowing the details of the web server (e.g., Apache or NginX), as well as the database. You have to go through more steps, such as precompiling assets to make sure all the right files are there. This is the price of being able to design and deploy more complex applications.

Where Ruby on Rails really shines is in the software development process itself. Since Ruby is an object-intensive language, everything is an object, including classes and modules, with Rails providing an integrated test framework. PHP is not always object-oriented, so coding can be laborious and time-consuming. Applications can be built and tested in Ruby on Rails much faster than in PHP, so even if there is some debugging involved, Ruby on Rails dramatically reduces the time to deployment.

As noted above, PHP applications are relatively simple to deploy since there is no stack to worry about, and they are relatively inexpensive to host. Hosting Ruby on Rails applications is another story. Not all hosting providers will support Ruby on Rails, and those that do usually add additional a la carte fees because Ruby applications require more services.

The Business Case for Ruby on Rails versus PHP

While it’s clear that Ruby is a more difficult programming language to master, in many ways, it is a more robust language that is better suited for creating business applications. PHP was created specifically for the web, but Ruby on Rails offers much more.

For one thing, Ruby on Rails applications tend to be cleaner and more compact. Because PHP is so simple, it lends itself to sloppy coding that can be impossible to maintain. Ruby has the advantage of being more elegant and concise, and the documentation for Ruby applications tends to be generated with the code so anyone can make revisions or upgrades.

Most importantly, Ruby on Rails lends itself to agile software practices and rapid application development (RAD). Rails is a mature framework that allows programmers to create maintainable software, and it has integrated testing tools that shorten the developer cycle. When you consider the cost of talented programmers (and you know that time is money), reducing development time can mean substantial savings.

Depending on your business development needs, you may be leaning toward PHP or Ruby on Rails. Each has its strengths and weaknesses, but Ruby on Rails continues to gain popularity for business-critical and e-commerce applications because of its versatility, scalability, and upgradability. In the end, you have to consider which language will deliver a cleaner, more stable application that can evolve and grow with your business.

Thanks for reading


Follow us on Facebook | Twitter

Learn More

PHP for Beginners - Become a PHP Master - CMS Project

Learn Object Oriented PHP By Building a Complete Website

PHP OOP: Object Oriented Programming for beginners + Project

Laravel PHP Framework Tutorial - Full Course for Beginners (2019)

Symfony PHP Framework - Full Course

What is a Full Stack Developer?

Build RESTful API In Laravel 5.8 Example

Laravel 5.8 Tutorial from Scratch for Beginners

Build a CRUD Operation using PHP & MongoBD

Build a CRUD Web App with Ruby on Rails

Ruby on Rails Tutorial for Beginners

How To Use PostgreSQL with Your Ruby on Rails Application on macOS
