Deploy and Host Turso / libSQL Database (Basic Auth) on Railway

Host your own libSQL (sqld) instance, the open-source heart of Turso, directly on Railway. This template provides a SQLite-compatible database server maintaining full compatibility with the libSQL ecosystem and Drizzle ORM.

Important: This setup does NOT use JWT "Auth Tokens." Most libSQL SDKs expect a JWT when using the authToken property. To connect successfully, you must either include credentials in the URL or use a custom fetch wrapper (see Drizzle example below).

About Hosting Turso / libSQL Database (Basic Auth)

Hosting libSQL on Railway involves deploying a containerized sqld server paired with a persistent Railway Volume. Unlike the managed Turso service which primarily uses JWT tokens, this setup is secured via HTTP Basic Authentication (username:password).

Common Use Cases

• Self-Hosted Turso Alternative: Get a dedicated database for production apps without usage-based pricing or row caps.
• Edge-Ready Backend: Provide a centralized, low-latency SQLite entry point for serverless functions on Vercel or Netlify.
• Dev/Staging Environments: Cost-effectively mirror your production Turso architecture for testing and migrations.

Dependencies for Turso / libSQL Database (Basic Auth) Hosting

• Railway Volume: Required to be mounted at /var/lib/sqld to persist your SQLite database files.
• Environment Variables: Railway will automatically create the DB_PASSWORD during deployment to secure your instance.

Deployment Dependencies

• libSQL (sqld) GitHub Repository

Implementation Details (Drizzle ORM Example)

To connect using Drizzle, you must use a custom fetch wrapper. This is because the @libsql/client SDK defaults to Bearer tokens, while this server requires the Basic prefix for authentication.

See => Drizzle test app on Github

db/index.ts

import { createClient } from '@libsql/client';
import { drizzle } from 'drizzle-orm/libsql';
import * as schema from './schema';

export function createDbClient(url: string, username: string, password: string) {
  // 1. Encode credentials for HTTP Basic Auth
  const credentials = Buffer.from(`${username}:${password}`).toString('base64');

  // 2. Create custom fetch to force "Basic" instead of "Bearer"
  const authenticatedFetch = (input: string | Request | URL, init?: RequestInit) => {
    const headers = new Headers(init?.headers);
    headers.set('Authorization', `Basic ${credentials}`);
    return fetch(input, { ...init, headers });
  };

  // 3. Initialize libSQL with the custom fetcher
  const client = createClient({
    url,
    fetch: authenticatedFetch,
  });

  return drizzle(client, { schema });
}

Why Deploy Turso / libSQL Database (Basic Auth) on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Turso / libSQL Database (Basic Auth) on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.