SQLite

TurboStarter ships with PostgreSQL by default, but you can absolutely run it on SQLite if that fits your product better.

SQLite is a good option when you want a simpler local setup, a single file database for development, or a libSQL provider such as Turso in production. The important thing to understand is that SQLite is a customization rather than a one-line toggle.

When SQLite makes sense

SQLite is a strong fit when you want:

• local development without a database container
• a simpler deployment story for smaller products
• an edge-friendly database provider such as Turso/libSQL

You should usually stay on PostgreSQL if you need:

• heavier concurrent write traffic
• PostgreSQL-specific features
• a fully drop-in experience with the starter's default schema and migrations

What you need to change

Moving to SQLite usually means updating these areas:

• packages/db/package.json - add a SQLite driver
• packages/db/src/env.ts - validate the new connection settings
• packages/db/src/server.ts - initialize Drizzle with a SQLite client
• packages/db/drizzle.config.ts - switch Drizzle Kit from postgresql to sqlite
• packages/auth/src/server.ts - change Better Auth from provider: "pg" to provider: "sqlite"
• packages/db/src/schema/* - replace PostgreSQL-only schema utilities with SQLite-compatible ones
• packages/db/src/utils/index.ts - review helper types that still import PostgreSQL table types

The good news is that not everything needs to be rewritten. For example, helper utilities such as buildConflictUpdateColumns already support both PgTable and SQLiteTable.

pnpm --filter @workspace/db add @libsql/client
pnpm --filter @workspace/db remove postgres

DATABASE_URL="file:./.data/local.db"

DATABASE_URL="libsql://your-database.turso.io"
DATABASE_AUTH_TOKEN="your-token"

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

import { env } from "./env";
import * as schema from "./schema";

const client = createClient({
  url: env.DATABASE_URL,
  authToken: env.DATABASE_AUTH_TOKEN,
});

export const db = drizzle(client, {
  schema,
  casing: "snake_case",
});

export const preset = {
  id: "db",
  server: {
    DATABASE_URL: z.string().min(1),
    DATABASE_AUTH_TOKEN: z.string().optional(),
  },
} as const;

import { defineConfig } from "drizzle-kit";

import { env } from "./src/env";

export default defineConfig({
  out: "./migrations",
  schema: "./src/schema/index.ts",
  dialect: "sqlite",
  casing: "snake_case",
  dbCredentials: {
    url: env.DATABASE_URL,
    authToken: env.DATABASE_AUTH_TOKEN,
  },
});

database: drizzleAdapter(db, {
  provider: "sqlite",
  schema,
}),

import { sqliteTable, text } from "drizzle-orm/sqlite-core";

const subscriptionStatuses = [
  "active",
  "canceled",
  "incomplete",
  "incomplete_expired",
  "past_due",
  "paused",
  "trialing",
  "unpaid",
] as const;

export const subscription = sqliteTable("subscription", {
  id: text("id").primaryKey(),
  status: text("status", { enum: subscriptionStatuses }).notNull(),
});

import type { SQLiteTable } from "drizzle-orm/sqlite-core";
// replace PgTable / PgTableWithColumns imports as needed

rm -rf packages/db/migrations
pnpm with-env turbo db:generate
pnpm with-env pnpm --filter @workspace/db db:migrate

Recommended migration order

If you're converting an existing project, this is the safest order:

1. Commit your PostgreSQL version first.
2. Switch the client, Drizzle config, and Better Auth provider.
3. Convert the schema files from pg-core to sqlite-core.
4. Update packages/db/src/utils/index.ts for SQLite-compatible typing where needed.
5. Delete old PostgreSQL migrations.
6. Generate fresh SQLite migrations.
7. Smoke test sign-in, sign-up, billing, and organization flows.

Final notes

SQLite works well with the starter, but it is not currently the "default path". Treat it as an intentional database adapter swap, not just a connection string change.

If you want the smoothest setup, prefer @libsql/client, keep the schema conservative, and regenerate your migrations cleanly once the dialect switch is complete.