Database setup

Overview

Better-T-Stack supports automated setup for popular database providers. Choose a managed provider for production or Docker for local development.

Setup options by database type

SQLite

Turso
Cloudflare D1
None (Manual)

Turso - SQLite for Production, powered by libSQLFeatures:

Edge-replicated SQLite
HTTP API
Branching support
Generous free tier

Setup:

npm create better-t-stack@latest my-app \
  --database sqlite \
  --orm drizzle \
  --db-setup turso

What you get:

Turso CLI installation helper
Connection string template
Environment variable configuration

Next steps:

Sign up at turso.tech
Create a database: turso db create my-app
Get connection URL: turso db show my-app --url
Get auth token: turso db tokens create my-app

Add to .env:

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

Cloudflare D1 - Serverless SQLite on Cloudflare WorkersFeatures:

Native Cloudflare Workers integration
Global edge network
Zero cold starts
Free tier included

Requirements:

Runtime must be workers
Server deploy should be cloudflare

Setup:

npm create better-t-stack@latest my-app \
  --database sqlite \
  --orm drizzle \
  --runtime workers \
  --db-setup d1 \
  --server-deploy cloudflare

What you get:

D1 database binding in alchemy.run.ts
Automated migrations on deploy
Type-safe bindings via packages/env

Configuration:

// packages/infra/alchemy.run.ts
import { D1Database } from "alchemy/cloudflare";

const db = await D1Database("database", {
  migrationsDir: "../../packages/db/src/migrations",
});

export const server = await Worker("server", {
  bindings: {
    DB: db,
    // ... other bindings
  },
});

Manual Setup - Use local SQLite fileSetup:

npm create better-t-stack@latest my-app \
  --database sqlite \
  --orm drizzle \
  --db-setup none

What you get:

SQLite file-based database
Local development ready

Configuration:

# apps/server/.env
DATABASE_URL=file:./dev.db

Apply schema:

bun run db:push

PostgreSQL

Neon Postgres - Serverless Postgres with branchingFeatures:

Serverless, scale-to-zero
Database branching (like Git)
Instant read replicas
Generous free tier

Setup:

npm create better-t-stack@latest my-app \
  --database postgres \
  --orm drizzle \
  --db-setup neon

Next steps:

Sign up at neon.tech
Create a project
Copy connection string from dashboard

Add to .env:

DATABASE_URL=postgresql://user:pass@ep-xxx.us-east-2.aws.neon.tech/neondb?sslmode=require

Supabase - Open source Firebase alternativeFeatures:

Postgres database
Auth, Storage, Realtime included
Local development with Docker
Free tier available

Setup:

npm create better-t-stack@latest my-app \
  --database postgres \
  --orm drizzle \
  --db-setup supabase

What you get:

Supabase CLI helpers
Local development setup
Environment variable templates

Next steps:

# Start local Supabase
npx supabase init
npx supabase start

# Get connection string
npx supabase status

Prisma Postgres - Instant Postgres for global applicationsFeatures:

Global edge database
Fast cold queries
Connection pooling
Free tier available

Setup:

npm create better-t-stack@latest my-app \
  --database postgres \
  --orm prisma \
  --db-setup prisma-postgres

Next steps:

Sign up at prisma.io/data-platform
Create a project
Get connection URL
Add to .env:
```
DATABASE_URL=prisma+postgres://xxx
```

PlanetScale - MySQL-compatible Postgres on VitessFeatures:

Vitess-powered scaling
Branching and schema management
Non-blocking schema changes
Free tier available

Setup:

npm create better-t-stack@latest my-app \
  --database postgres \
  --orm drizzle \
  --db-setup planetscale

Next steps:

Sign up at planetscale.com
Create a database
Get connection string

Add to .env:

DATABASE_URL=mysql://xxx@xxx.us-east-2.psdb.cloud/mydb?sslaccept=strict

Docker - Local Postgres with Docker ComposeSetup:

npm create better-t-stack@latest my-app \
  --database postgres \
  --orm drizzle \
  --db-setup docker

What you get:

docker-compose.yml with Postgres service
Pre-configured connection string

Start database:

docker compose up -d

Environment:

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/myapp

Manual Setup - Use your own Postgres instanceSetup:

npm create better-t-stack@latest my-app \
  --database postgres \
  --orm drizzle \
  --db-setup none

Configuration:

# apps/server/.env
DATABASE_URL=postgresql://user:pass@host:5432/dbname

MySQL

PlanetScale
Docker
None (Manual)

PlanetScale - MySQL on Vitess with NVMe storageSetup:

npm create better-t-stack@latest my-app \
  --database mysql \
  --orm drizzle \
  --db-setup planetscale

See PostgreSQL > PlanetScale tab for details.

Docker - Local MySQL with Docker ComposeSetup:

npm create better-t-stack@latest my-app \
  --database mysql \
  --orm drizzle \
  --db-setup docker

What you get:

docker-compose.yml with MySQL service
Pre-configured connection string

Start database:

docker compose up -d

Environment:

DATABASE_URL=mysql://root:password@localhost:3306/myapp

Manual Setup - Use your own MySQL instanceConfiguration:

# apps/server/.env
DATABASE_URL=mysql://user:pass@host:3306/dbname

MongoDB

MongoDB Atlas
Docker
None (Manual)

MongoDB Atlas - Fully managed cloud MongoDBFeatures:

Global clusters
Automated backups
Monitoring and alerts
Free tier (512MB)

Setup:

npm create better-t-stack@latest my-app \
  --database mongodb \
  --orm mongoose \
  --db-setup mongodb-atlas

Next steps:

Sign up at mongodb.com/cloud/atlas
Create a cluster
Create a database user
Whitelist your IP address
Get connection string

Add to .env:

DATABASE_URL=mongodb+srv://user:pass@cluster.mongodb.net/myapp?retryWrites=true&w=majority

Docker - Local MongoDB with Docker ComposeSetup:

npm create better-t-stack@latest my-app \
  --database mongodb \
  --orm mongoose \
  --db-setup docker

What you get:

docker-compose.yml with MongoDB service
Pre-configured connection string

Start database:

docker compose up -d

Environment:

DATABASE_URL=mongodb://localhost:27017/myapp

Manual Setup - Use your own MongoDB instanceConfiguration:

# apps/server/.env
DATABASE_URL=mongodb://host:27017/dbname

Connection strings

Each database type uses a specific connection string format:

SQLite

# Local file
DATABASE_URL=file:./dev.db

# Turso (libSQL)
DATABASE_URL=libsql://your-db.turso.io
DATABASE_AUTH_TOKEN=your-token

PostgreSQL

# Standard Postgres
DATABASE_URL=postgresql://user:pass@host:5432/dbname

# With SSL
DATABASE_URL=postgresql://user:pass@host:5432/dbname?sslmode=require

# Prisma Postgres
DATABASE_URL=prisma+postgres://accelerate.prisma-data.net/?api_key=xxx

MySQL

# Standard MySQL
DATABASE_URL=mysql://user:pass@host:3306/dbname

# PlanetScale
DATABASE_URL=mysql://user@host.psdb.cloud/dbname?sslaccept=strict

MongoDB

# Local MongoDB
DATABASE_URL=mongodb://localhost:27017/dbname

# MongoDB Atlas
DATABASE_URL=mongodb+srv://user:pass@cluster.mongodb.net/dbname?retryWrites=true&w=majority

Environment variables

Location

Database URLs are typically stored in:

apps/server/.env          (for server-side code)
packages/db/.env          (for database packages)
packages/infra/.env       (for Alchemy deployments)

Required variables

Standard setup:

DATABASE_URL=your-connection-string

Turso (requires auth token):

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

Cloudflare D1 (no env vars needed): D1 uses bindings configured in alchemy.run.ts. No connection string needed.

For Alchemy deployments

If using Cloudflare deployment with Alchemy:

// packages/infra/alchemy.run.ts
import { config } from "dotenv";

config({ path: "../../apps/server/.env" });

export const server = await Worker("server", {
  bindings: {
    DATABASE_URL: alchemy.secret.env.DATABASE_URL!,
  },
});

Applying schema

After setting up your database:

With Drizzle

Push schema (development):

bun run db:push

Generate migration:

bun run db:generate

Apply migration (production):

bun run db:migrate

With Prisma

Push schema (development):

bun run db:push

Generate migration:

cd packages/db && npx prisma migrate dev --name init

Apply migration (production):

cd packages/db && npx prisma migrate deploy

With Mongoose

Mongoose doesn’t require migrations - schemas are applied automatically on first connection.

Switching providers

To switch database providers after creation:

Update connection string

Replace DATABASE_URL in your .env files with the new provider’s connection string.

Update ORM configuration (if needed)

Some ORMs require provider-specific configuration:Drizzle:

// packages/db/src/index.ts
import { drizzle } from "drizzle-orm/postgres-js"; // or /mysql2, /better-sqlite3

Prisma:

// packages/db/prisma/schema.prisma
datasource db {
  provider = "postgresql" // or "mysql", "sqlite"
  url      = env("DATABASE_URL")
}

Regenerate migrations

bun run db:generate
bun run db:push

Update deployment config (if using Alchemy)

If switching to/from Cloudflare D1, update your alchemy.run.ts.

Troubleshooting

Connection refused

Issue: Cannot connect to databaseSolutions:

Verify connection string format
Check database is running (docker ps for Docker)
Confirm firewall/network access
For cloud providers, whitelist your IP address

SSL/TLS errors

Issue: SSL certificate validation failsSolutions:

Add ?sslmode=require to PostgreSQL URLs
Add ?sslaccept=strict to MySQL URLs
For self-signed certificates, use ?sslmode=disable (dev only)

Authentication failed

Issue: Username/password rejectedSolutions:

Verify credentials are correct
Check database user has proper permissions
For cloud providers, ensure database user is created
URL-encode special characters in passwords

Migrations fail

Issue: Schema migrations don’t applySolutions:

Check connection string is valid
Ensure database exists
Verify migration files are in correct location
For Drizzle, run bun run db:generate first

Next steps

Project structure

Learn where database code lives

Examples

See database usage in Todo example

Deployment

Deploy with database providers

Compatibility

Database and ORM compatibility

Getting Started

CLI Reference

Configuration

Guides

Stack Options

Overview

Setup options by database type

SQLite

PostgreSQL

MySQL

MongoDB

Connection strings

SQLite

PostgreSQL

MySQL

MongoDB

Environment variables

Location

Required variables

For Alchemy deployments

Applying schema

With Drizzle

With Prisma

With Mongoose

Switching providers

Troubleshooting

Next steps

Project structure

Examples

Deployment

Compatibility

Build docs developers (and LLMs) love

Getting Started

CLI Reference

Configuration

Guides

Stack Options

Documentation Index

​Overview

​Setup options by database type

​SQLite

​PostgreSQL

​MySQL

​MongoDB

​Connection strings

​SQLite

​PostgreSQL

​MySQL

​MongoDB

​Environment variables

​Location

​Required variables

​For Alchemy deployments

​Applying schema

​With Drizzle

​With Prisma

​With Mongoose

​Switching providers

​Troubleshooting

​Next steps

Project structure

Examples

Deployment

Compatibility

Build docs developers (and LLMs) love

Overview

Setup options by database type

SQLite

PostgreSQL

MySQL

MongoDB

Connection strings

SQLite

PostgreSQL

MySQL

MongoDB

Environment variables

Location

Required variables

For Alchemy deployments

Applying schema

With Drizzle

With Prisma

With Mongoose

Switching providers

Troubleshooting

Next steps