Railway

PerSQL gives a Railway service its own SQLite database on the edge. You provision a database, set three environment variables, and query with the PerSQL SDK. Every Railway PR environment can get its own isolated branch database.

Connect

1. Go to railway.persql.com/connect, sign in, and provision a database. You get three values:

   Variable	Example	Secret
   PERSQL_API_URL	https://api.persql.com	no
   PERSQL_DATABASE	<namespace>/<db-slug>	no
   PERSQL_TOKEN	psql_live_…	yes

   The token is admin-scoped to that one database (so your app can run its own migrations) and nothing else.

2. Apply them with the Railway CLI:

   railway variables \
     --set "PERSQL_API_URL=https://api.persql.com" \
     --set "PERSQL_DATABASE=<namespace>/<db-slug>" \
     --set "PERSQL_TOKEN=psql_live_…"

   …or paste them under Service → Variables in the dashboard.

3. Query:

   import { PerSQL } from "@persql/sdk";
   
   const db = new PerSQL({
     token: process.env.PERSQL_TOKEN,
     baseURL: process.env.PERSQL_API_URL,
   }).database(process.env.PERSQL_DATABASE);
   
   const { data } = await db.query("SELECT 1 AS ok");

Deploy a starter

The railway-starter repo is a minimal web service backed by PerSQL, with a railway.json that pins the Node build, start command, and healthcheck. Deploy it in one click:

Railway prompts for PERSQL_DATABASE and PERSQL_TOKEN — paste the values from the connect page. (Prefer the dashboard? New Project → Deploy from GitHub repo → persql/railway-starter works too.)

A database per PR environment

Point a coding agent at the Railway MCP for the per-PR recipe:

https://railway.persql.com/mcp

Authenticate with a PerSQL bearer token. preview_recipe returns the CI snippet that spawns a preview-pr-<n> branch when a PR environment opens and deletes it on close; preview_list shows the active previews.