Rails

Rails connects to DB9 through the standard pg gem and ActiveRecord. No special adapter or driver is needed — DB9 speaks the PostgreSQL wire protocol, so ActiveRecord’s PostgreSQL adapter works out of the box.

Prerequisites

A DB9 database (create one)
Ruby 3.1+
Rails 7+

Create a DB9 Database

db9 create --name rails-app

Get the connection string:

db9 db status rails-app

Set the connection string as an environment variable:

export DATABASE_URL="postgresql://rails-app.admin:YOUR_PASSWORD@pg.db9.io:5433/postgres?sslmode=require"

Create a New Rails App

rails new rails-db9 --database=postgresql
cd rails-db9

The --database=postgresql flag adds the pg gem to your Gemfile and generates the correct config/database.yml template.

Configure Database Connection

The simplest approach is to use the DATABASE_URL environment variable. Rails will pick it up automatically.

To configure directly, edit config/database.yml:

default: &default
  adapter: postgresql
  host: pg.db9.io
  port: 5433
  database: postgres
  username: rails-app.admin
  password: <%= ENV["DB9_PASSWORD"] %>
  sslmode: require
  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
  timeout: 5000

development:
  <<: *default

test:
  <<: *default

production:
  <<: *default
  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 10 } %>

Define Models

Generate a User model:

rails generate model User name:string email:string

Generate a Post model with a foreign key to User:

rails generate model Post title:string body:text published:boolean user:references

Edit the generated models to add validations and associations:

class User < ApplicationRecord
  has_many :posts, dependent: :destroy

  validates :name, presence: true
  validates :email, presence: true, uniqueness: true
end

class Post < ApplicationRecord
  belongs_to :user

  validates :title, presence: true
end

Run Migrations

rails db:migrate

Controllers and Routes

Generate a Users controller:

rails generate controller Users

Add a simple CRUD controller:

class UsersController < ApplicationController
  def index
    @users = User.all
    render json: @users
  end

  def show
    @user = User.find(params[:id])
    render json: @user, include: :posts
  end

  def create
    @user = User.new(user_params)
    if @user.save
      render json: @user, status: :created
    else
      render json: { errors: @user.errors }, status: :unprocessable_entity
    end
  end

  def update
    @user = User.find(params[:id])
    if @user.update(user_params)
      render json: @user
    else
      render json: { errors: @user.errors }, status: :unprocessable_entity
    end
  end

  def destroy
    User.find(params[:id]).destroy
    head :no_content
  end

  private

  def user_params
    params.require(:user).permit(:name, :email)
  end
end

Wire up the routes:

Rails.application.routes.draw do
  resources :users
end

Start the server and test:

rails server
curl http://localhost:3000/users

Production Notes

Port 5433: DB9 listens on port 5433, not the PostgreSQL default 5432.
TLS required: Always use sslmode=require in your connection string or database.yml.
Connection pool size: Set pool in database.yml to match RAILS_MAX_THREADS. Start with 5–10 connections.
Database name: The database is always postgres. Do not run rails db:create — it will fail because the database already exists and you cannot create new ones.
Puma threads: If using Puma, ensure the pool size in database.yml is at least equal to RAILS_MAX_THREADS to avoid connection checkout timeouts.

Troubleshooting

Connection refused on port 5432

DB9 uses port 5433. Check your DATABASE_URL or database.yml — Rails defaults to 5432 if no port is specified.

`rails db:create` fails

The postgres database already exists on DB9. Skip db:create and run db:migrate directly.

ActiveRecord::ConnectionNotEstablished

Verify that your username follows the format <app-name>.admin (e.g., rails-app.admin). DB9 routes connections by parsing the tenant from the username. Also confirm sslmode=require is set.

Migrations fail with permission errors

DB9 connects you to the postgres database with admin privileges for your tenant. If you see schema-related errors, confirm you are not trying to modify system tables or create additional databases.

Slow first request

The first connection to DB9 may take slightly longer due to TLS handshake and tenant routing. Subsequent requests reuse pooled connections. Preload the connection pool by adding an initializer:

ActiveRecord::Base.connection_pool.checkout

Connect — connection strings and authentication
Production Checklist — deployment readiness