Setup

Environment variables

When your app is created (or when you provision a database from the Data tab), two environment variables are automatically injected into your Railway service:

These are set per environment — your dev and prod services each receive their own URL and token.

You do not need to configure these manually. They are synced to Railway by the platform whenever a database is provisioned or a token is rotated.

Install dependencies

Install the libSQL client and Drizzle ORM:

npm install @libsql/client drizzle-orm

Or with Bun:

bun add @libsql/client drizzle-orm

For migrations, also add drizzle-kit as a dev dependency:

npm install -D drizzle-kit

Create the database client

Create a db.ts (or lib/db.ts) file in your project:

import { createClient } from "@libsql/client";
import { drizzle } from "drizzle-orm/libsql";

const client = createClient({
  url: process.env.BUILDSPACE_DB_URL!,
  authToken: process.env.BUILDSPACE_DB_TOKEN!,
});

export const db = drizzle(client);

That's it — db is a Drizzle instance ready for queries.

Local development

For local development you can use a local SQLite file instead of connecting to the remote Turso database:

import { createClient } from "@libsql/client";
import { drizzle } from "drizzle-orm/libsql";

const client = createClient({
  url: process.env.BUILDSPACE_DB_URL ?? "file:local.db",
  authToken: process.env.BUILDSPACE_DB_TOKEN,
});

export const db = drizzle(client);

This falls back to a local local.db file when the env vars are not set, so you can develop without connecting to Turso.

Token rotation

You can rotate database tokens from the Data tab in Creator Studio. When you rotate a token:

1. All existing tokens for that database are invalidated.
2. A new token is generated and stored.
3. The BUILDSPACE_DB_TOKEN env var is updated and synced to Railway.
4. Your service will pick up the new token on its next deploy or restart.