Schema migration with Neon Postgres and Ruby on Rails
Set up Neon Postgres and run migrations for your Rails project
Ruby on Rails is a popular web application framework for Ruby developers. It provides an ORM (Object-Relational Mapping) layer called Active Record
, that simplifies database interactions and schema management. Rails also includes a powerful migration system that allows you to define and manage database schema changes over time.
This guide demonstrates how to run schema migrations in your Ruby on Rails project backed by the Neon
Postgres database. We'll create a simple Rails application and walk through the process of setting up the database, defining models, and generating and running migrations to manage schema changes.
Prerequisites
To follow along with this guide, you will need:
-
A Neon account. If you do not have one, sign up at Neon. Your Neon project comes with a ready-to-use Postgres database named
neondb
. We'll use this database in the following examples. -
Ruby installed on your local machine.
You can install Ruby using the instructions provided on the official Ruby website. We recommend using a newer version of Ruby, 3.0 or higher.
-
Rails installed on your local machine. You can install Rails by running
gem install rails
.We recommend using Rails 6 or higher. This project uses
Rails 7.1.3.2
.
Setting up your Neon database
Initialize a new project
- Log in to the Neon Console and navigate to the Projects section.
- Select a project or click the New Project button to create a new one.
Retrieve your Neon database connection string
On your project dashboard in Neon, navigate to the Connection Details section to find your database connection string. It should look similar to this:
Keep your connection string handy for later use.
note
Neon supports both direct and pooled database connection strings, which can be copied from the Connection Details widget on your Neon Project Dashboard. A pooled connection string connects your application to the database via a PgBouncer connection pool, allowing for a higher number of concurrent connections. However, using a pooled connection string for migrations can be prone to errors. For this reason, we recommend using a direct (non-pooled) connection when performing migrations. For more information about direct and pooled connections, see Connection pooling.
Setting up the Rails project
Create a new Rails project
Open your terminal and run the following command to create a new Rails project:
This command creates a new Rails project named guide-neon-rails
with Postgres as the default database. It will also generate the necessary project files and directories, and install the required dependencies.
Set up the Database configuration
Create a .env
file in the project root directory and add the DATABASE_URL
environment variable to it. Use the connection string that you obtained from the Neon Console earlier:
For Rails to load the environment variables automatically from the .env
file, add the dotenv-rails
gem to the Gemfile
at the root of your project:
Then, run bundle install
to install the gem.
Finally, we open the config/database.yml
file in your project directory and update the default
section so that Rails uses the DATABASE_URL
environment variable to connect to the Neon
database.
Defining data models and running migrations
Generate models and migrations
Next, we will create the data models for our application. Run the following commands to generate the Author
and Book
models:
These commands generate model files and the corresponding migration files in the app/models
and db/migrate
directories, respectively.
Run the migrations
To run the migrations and create the corresponding tables in the Neon Postgres database, run the following command:
This command executes the migration files and creates the authors
and books
tables in the database. Additionally, it also creates some tables for its internal bookkeeping.
Seed the database
To populate the database with some initial data, open the db/seeds.rb
file and add the following code:
To run the seed file and populate the database with the initial data, run the following command:
This command inserts the sample authors and books data into the database. Note that the script looks for existing records before creating new ones, so you can run it multiple times without duplicating the data.
Implement the application
Create controllers and views
Next, we will create controllers and views to display the authors and books in our application. Run the following commands to generate the controllers:
These commands generate controller files and corresponding view files in the app/controllers
and app/views
directories.
Open the app/controllers/authors_controller.rb
file and update the index
action:
Similarly, open the app/controllers/books_controller.rb
file and update the index
action:
Now, we update the corresponding views to display the data. Open the app/views/authors/index.html.erb
file and add the following code:
Open the app/views/books/index.html.erb
file and add the following code:
Define routes
Open the config/routes.rb
file and define the routes for the authors and books:
Run the Rails server
To start the Rails server and test the application, run the following command:
Navigate to the url http://localhost:3000/authors
in your browser to view the list of authors. You can also view the books by a specific author by clicking on the "Books" link next to each author, which takes you to the http://localhost:3000/books/:author_id
route.
Applying schema changes
We will demonstrate how to handle schema changes by adding a new field country
to the Author
model, to store the author's country of origin.
Generate a migration
To generate a migration file for adding the country
field to the authors
table, run the following command:
This command generates a new migration file in the db/migrate
directory.
Run the migration
To run the migration and apply the schema change, run the following command:
This command executes the migration file and adds the country
column to the authors
table in the database.
Update the existing records
To update the existing records with the author's country, open the db/seeds.rb
file and update the authors data with the country information:
Run the seed file again to update the existing records in the database:
Test the schema change
Update the app/views/authors/index.html.erb
file to display the country alongside each author:
Now, restart the Rails server:
Navigate to the url http://localhost:3000/authors
to view the list of authors. The country
field is now available for each author, reflecting the schema change.
Conclusion
In this guide, we demonstrated how to set up a Ruby on Rails project with Neon Postgres, define database models, generate migrations, and run them. Rails' Active Record ORM and migration system make it easy to interact with the database and manage schema evolution over time.
Source code
You can find the source code for the application described in this guide on GitHub.
Resources
For more information on the tools and concepts used in this guide, refer to the following resources:
Need help?
Join our Discord Server to ask questions or see what others are doing with Neon. Users on paid plans can open a support ticket from the console. For more detail, see Getting Support.