Use Supabase with Ruby on Rails

Learn how to create a Rails project and connect it to your Supabase Postgres database.

AI Prompt

Help me add Supabase to my Ruby on Rails project. Create a Supabase project at database.new. Then: 1. Run `rails new blog -d=postgresql` to scaffold a new Rails project. 2. Set `DATABASE_URL` to the Supabase Session Pooler connection string in `.env`. 3. Generate an Article model with `bin/rails generate model Article title:string body:text` and run `bin/rails db:migrate`. 4. Use `bin/rails console` to create and query articles. 5. Run `bin/rails server` and open http://127.0.0.1:3000. REFERENCE https://supabase.com/docs/guides/getting-started/quickstarts/ruby-on-rails.md

1. Create a Supabase project#

To start, you need a Supabase project.

Create a new Supabase project from the Dashboard of any organization you belong to.

Want to create a project programmatically?

Use the Management API or ask the MCP server to create a new Supabase project.

Save your database password securely. You need it for the connection string.

This guide uses Rails' own Active Record models and migrations, not the shared instruments sample table used by other quickstarts.

2. Create a Rails project#

With your Ruby and Rails versions up to date, run rails new on your terminal to scaffold a new project.

Use the -d=postgresql flag to set it up for Postgres.

Check the Rails docs for more details.

1
rails new blog -d=postgresql
2
cd blog

3. Set up AI tooling (optional)#

Supabase provides two ways to give AI tools context about your project: Agent Skills, which give your AI coding agent procedural knowledge, and the MCP server, which connects AI assistants to your Supabase project directly.

Agent Skills#

Agent Skills is a curated set of instructions that give your AI agent procedural knowledge about working with Supabase.

Install them so your AI coding agent can produce more accurate, reliable code using current Supabase patterns, such as authentication, server-side rendering, and database migrations, rather than relying solely on training data.

Installing Agent Skills#

To install, run the following command in the root of your project:

1
npx skills add supabase/agent-skills

Supabase MCP server#

The Supabase MCP server connects AI assistants to Supabase, so they can inspect your schema and act on your projects on your behalf. Find out how to add it to your client in the MCP docs.

4. Set up the Postgres connection details#

Navigate to your project dashboard and click on Connect.

Don't use the Transaction pooler (port 6543) as your app's main data source. Most ORMs rely on server-side prepared statements, which the Transaction pooler doesn't support. Use the Session pooler (port 5432), or the direct connection string if you're in an IPv6 environment or have the IPv4 Add-On.
Look for the Session pooler connection string and copy it. Replace the password placeholder with your saved database password, and percent-encode any reserved characters it contains, such as &, #, ?, or a space. If you don't have your database password, you can reset it in your Database Settings.
Set sslmode=require either on the connection string itself or as an explicit config option if your framework sets it separately. Most drivers default to prefer, which falls back to sending your data in plaintext if the encrypted attempt fails. You can also enforce SSL on the database side.

The connection strings below show the format only. Take the host, port, and username from the string you copied rather than typing the bracketed placeholders literally.

Set the connection string as an environment variable. Rails reads DATABASE_URL from the environment and connects with it, so you don't need to edit config/database.yml. The export applies to the current shell session, so run it in the same shell as the Rails commands in the following steps.

1
export DATABASE_URL=postgres://postgres.[PROJECT-REF]:[YOUR-PASSWORD]@[POOLER-HOST]:5432/postgres?sslmode=require

5. Create and run a database migration#

Rails includes Active Record as the ORM as well as database migration tooling which generates the SQL migration files for you.

Create an example Article model and generate the migration files.

1
bin/rails generate model Article title:string body:text
2
bin/rails db:migrate

6. Use the model to interact with the database#

You can use the included Rails console to interact with the database. For example, you can create new entries or list all entries in a Model's table.

1
bin/rails console

irb

1
article = Article.new(title: "Hello Rails", body: "I am on Rails!")
2
article.save # Saves the entry to the database
3
4
Article.all

7. Start the app#

Run the development server. Go to http://127.0.0.1:3000 in a browser to see your application running.

1
bin/rails server

Production requirements#

The quickstart procedure in this guide optimizes for getting you to a working app, not for production.

Before you deploy:

If your app reads or writes through the Data API, review your Row Level Security policies. Any policy you added here is scoped to this quickstart's sample data, not to real user data.
Set your Supabase credentials as environment variables on whatever platform you deploy to, rather than committing them to source control.
Configure a custom domain for your Supabase project once you're ready to go live.

Next steps#

Set up Auth for your app
Insert more data into your database
Upload and serve static files using Storage