Rails PostgreSQL CRUD API Starter

A Rails 8.1 API-only CRUD starter in Ruby 3.4 that stores one resource, items, in PostgreSQL through Active Record, served by Puma. It is for Ruby developers who want rails new --api already turned into a working service, with validation, JSON errors, limit and offset paging, a database health check, an OpenAPI 3.1 document and tests.

by Light CloudCRUD APIs

Features

  • GET, POST, PUT and DELETE on /items, with GET /items?limit=20&offset=0 listing oldest first and limit 1 to 100
  • Rails in API-only mode: no views, cookies or assets, one controller for items and one for the health check
  • Validation without a gem: name trimmed and 1 to 200 characters, and a number or an array refused rather than turned into text
  • Every error is { "error": "..." }: 400 for invalid input or malformed JSON, 404 for an unknown item or route, 500 for the unexpected
  • An OpenAPI 3.1 document at /openapi.json, with a test that fails when it and config/routes.rb list different routes
  • Migrations applied by the Docker entrypoint under Rails' PostgreSQL advisory lock on every start
  • GET /health answers 200 when the database answers and 503 when it does not; TLS to the database by default
  • Minitest integration tests against a real PostgreSQL, each in a rolled-back transaction, with RuboCop and Brakeman

Tech stack

What you need

  • A paid plan: deploying creates a PostgreSQL database, which the Free plan does not include
  • To run it locally: Ruby 3.4, libpq, and Docker for a local PostgreSQL
  • No API keys: it starts with nothing to configure, and needs no SECRET_KEY_BASE
  • DB_HOST, DB_NAME, DB_USER and DB_PASSWORD: Light Cloud sets them on deploy; set DB_SSLMODE=disable for a local database without TLS

About

config/database.yml builds the connection with ERB from DB_HOST (which may carry a port), DB_NAME, DB_USER, DB_PASSWORD and DB_SSLMODE rather than DATABASE_URL, with as many pooled connections as Puma threads and a 5 second connect timeout. The first change is usually renaming Item or giving it your own fields: generate a migration, update items_controller.rb and add the paths to public/openapi.json, since the OpenAPI test fails until the routes and the document match. Because the entrypoint migrates before Puma takes traffic, an unreachable database shows up at deploy time rather than on the first request. There is no authentication or rate limiting, so every endpoint is open to anyone with the URL until you add tokens. SECRET_KEY_BASE is random at each start because nothing in the API is signed; set one if you add cookies, signed ids or encryption.

FAQ

How do I build a JSON CRUD API with Ruby on Rails and PostgreSQL?

Generate an API-only app with rails new --api --database=postgresql, add a migration and a model, and route index, show, create, update and destroy to a controller that renders JSON. This starter is that app, with validation, JSON errors, paging, a health check and tests already written.

How do I connect Rails to PostgreSQL without DATABASE_URL?

config/database.yml builds the connection from DB_HOST, DB_NAME, DB_USER, DB_PASSWORD and DB_SSLMODE with ERB, the variables Light Cloud sets. DB_SSLMODE=require means TLS without checking the certificate.

How do I add a new resource to this Rails API?

Run bin/rails generate model for the table, add a controller modelled on items_controller.rb, add its routes in config/routes.rb and its paths to public/openapi.json; the OpenAPI test fails until the two match.

How do I deploy a Rails API with a PostgreSQL database?

Press Deploy on this template: Light Cloud copies the repo into your GitHub account, builds the Dockerfile, creates a PostgreSQL database and sets DB_HOST, DB_NAME, DB_USER and DB_PASSWORD on the app. Databases need a paid plan.

Can I host this Rails API without Light Cloud?

Yes. Any Docker host that can reach PostgreSQL runs the image once the DB_* variables are set; without Docker, run bin/rails db:migrate and bin/rails server with RAILS_ENV=production.

Price
Free
Framework
Ruby on Rails · Ruby
Updated