Database

This guide covers the database creation, initialization, and connection to Cloudflare D1 database using Drizzle ORM.

Setup

Create and Initialize Local Database

The local D1 database is automatically created when running the database initialization command. Run the following command to initialize the local database:

pnpm db:migrate:local

For local development, you can use the following command to open Drizzle Studio for local database management:

pnpm db:studio:local

Create Remote D1 Database

The remote D1 database needs to be created manually. Before creating it, you need to configure the Cloudflare API Token first.

(1) Configure Cloudflare API Token

Please complete the Cloudflare API Token configuration first, ensuring the Token includes at least the Account > D1 > Edit permission.

(2) Create Remote Database

You can create a remote D1 database via the Cloudflare Dashboard or Wrangler CLI:

Create a new D1 database:

pnpm wrangler d1 create your-database-name

Select no when prompted after the command executes successfully, then copy the database_id from the command output

Log in to the Cloudflare Dashboard
Go to Storage & Databases > D1 SQL Databases
Click Create Database
Enter a database name, click Create
Once created, copy the Database ID from the database details page

After creation, update the database_id and database_name in your wrangler.jsonc file:

wrangler.jsonc

"d1_databases": [
  {
    "binding": "DB",
    "database_name": "your-database-name",  // Change to your database name
    "database_id": "your-database-id",  // Change to your database ID
    "migrations_dir": "./src/db/migrations"
  }
],

Also add the database ID to your environment variables file:

.env

CLOUDFLARE_DATABASE_ID=your-database-id

Initialize Remote Database

Run the following command to initialize the remote database:

pnpm db:migrate:remote

Run the following command to view and manage the remote database:

pnpm db:studio:remote

If you are setting up your environment, you can now go back to the Environment Configuration and continue. The rest of this document can be read later.

Environment Configuration

Set up environment variables

Database Schema

The database schema is defined in the src/db/ directory:

src/db/auth.schema.ts - Better Auth schema (auto-generated)
src/db/app.schema.ts - Application schema

The database includes the following tables:

Users - User accounts and profiles
Sessions - User authentication sessions
Accounts - OAuth account links
Verification - Email verification tokens
API Keys - API key management
Payments - Payment records and subscription tracking
User Files - User uploaded file metadata

Database Commands

TanStarter provides the following database management commands:

Command	Description
`pnpm db:generate`	Generate Drizzle migration files
`pnpm db:push`	Push schema changes to database
`pnpm db:studio:local`	Open Drizzle Studio (local database)
`pnpm db:studio:remote`	Open Drizzle Studio (remote database)
`pnpm db:migrate:local`	Apply migrations (local database)
`pnpm db:migrate:remote`	Apply migrations (remote database)

References

Next Steps

Now that you understand how to set up a database in TanStarter, you might want to explore these related features:

Authentication

Configure user authentication

Email

Configure email services

Configure newsletter subscriptions

Deployment

Deploy to Cloudflare Workers

This guide covers the database creation, initialization, and connection to Cloudflare D1 database using Drizzle ORM.

Setup

Create and Initialize Local Database

The local D1 database is automatically created when running the database initialization command. Run the following command to initialize the local database:

pnpm db:migrate:local

For local development, you can use the following command to open Drizzle Studio for local database management:

pnpm db:studio:local

Create Remote D1 Database

The remote D1 database needs to be created manually. Before creating it, you need to configure the Cloudflare API Token first.

(1) Configure Cloudflare API Token

Please complete the Cloudflare API Token configuration first, ensuring the Token includes at least the Account > D1 > Edit permission.

(2) Create Remote Database

You can create a remote D1 database via the Cloudflare Dashboard or Wrangler CLI:

Create a new D1 database:

pnpm wrangler d1 create your-database-name

Select no when prompted after the command executes successfully, then copy the database_id from the command output

Log in to the Cloudflare Dashboard
Go to Storage & Databases > D1 SQL Databases
Click Create Database
Enter a database name, click Create
Once created, copy the Database ID from the database details page

After creation, update the database_id and database_name in your wrangler.jsonc file:

wrangler.jsonc

"d1_databases": [
  {
    "binding": "DB",
    "database_name": "your-database-name",  // Change to your database name
    "database_id": "your-database-id",  // Change to your database ID
    "migrations_dir": "./src/db/migrations"
  }
],

Also add the database ID to your environment variables file:

.env

CLOUDFLARE_DATABASE_ID=your-database-id

Initialize Remote Database

Run the following command to initialize the remote database:

pnpm db:migrate:remote

Run the following command to view and manage the remote database:

pnpm db:studio:remote

If you are setting up your environment, you can now go back to the Environment Configuration and continue. The rest of this document can be read later.

Environment Configuration

Set up environment variables

Database Schema

The database schema is defined in the src/db/ directory:

src/db/auth.schema.ts - Better Auth schema (auto-generated)
src/db/app.schema.ts - Application schema

The database includes the following tables:

Users - User accounts and profiles
Sessions - User authentication sessions
Accounts - OAuth account links
Verification - Email verification tokens
API Keys - API key management
Payments - Payment records and subscription tracking
User Files - User uploaded file metadata

Database Commands

TanStarter provides the following database management commands:

Command	Description
`pnpm db:generate`	Generate Drizzle migration files
`pnpm db:push`	Push schema changes to database
`pnpm db:studio:local`	Open Drizzle Studio (local database)
`pnpm db:studio:remote`	Open Drizzle Studio (remote database)
`pnpm db:migrate:local`	Apply migrations (local database)
`pnpm db:migrate:remote`	Apply migrations (remote database)

Setup

Create and Initialize Local Database

Create Remote D1 Database

(1) Configure Cloudflare API Token

(2) Create Remote Database

Initialize Remote Database

Environment Configuration

Database Schema

Database Commands

References

Next Steps

Authentication

Email

Newsletter

Deployment

Table of Contents

Database

Setup

Create and Initialize Local Database

Create Remote D1 Database

(1) Configure Cloudflare API Token

(2) Create Remote Database

Initialize Remote Database

Environment Configuration

Database Schema

Database Commands

References

Next Steps

Authentication

Email

Newsletter

Deployment

Table of Contents