Database

This document covers database creation, initialization, and connecting to a Cloudflare D1 database using Drizzle ORM.

Setup

Create and Initialize Local Database

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

bun run db:migrate:local

For local development, you can use the following command to open Drizzle Studio and manage your local database:

bun run db:studio:local

Create and Initialize Remote Database

Remote D1 databases must be created manually. You need to configure your Cloudflare API Token before creating them.

(1) Configure Cloudflare API Token

First, complete the Cloudflare configuration. Ensure that your Token has at least Account > D1 > Edit permissions.

(2) Create Remote Database

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

Wrangler CLI

1. Create a new D1 database:

bunx wrangler d1 create your-database-name

2. Select no when prompted after the command executes successfully, and copy the database_id from the command output.

Cloudflare Dashboard

1. Log in to the Cloudflare Dashboard
2. Navigate to Storage & Databases > D1 SQL Databases
3. Click Create Database
4. Enter the database name, and click Create
5. Once created, copy the Database ID from the database details page

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

wrangler.jsonc

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

Also, add the database ID to your environment variable file:

.env

CLOUDFLARE_DATABASE_ID=your-database-id

(3) Initialize Remote Database

Execute the following command to initialize the remote database:

bun run db:migrate:remote

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

bun run db:studio:remote

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

Environment configuration set environment variables

Database Structure

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 contains the following tables:

• Users - User accounts and profiles
• Sessions - User authentication sessions
• Accounts - OAuth account association
• Verification - Email verification tokens
• API Keys - API key management
• Payments - Payment records and subscription tracking
• User Files - Metadata for user uploaded files

Database Commands

ShipSaaS provides the following database management commands:

References

• Cloudflare D1 Documentation
• Drizzle ORM Documentation
• Wrangler CLI Reference

Next Steps

Now that you know how to set up a database in ShipSaaS, you may want to explore these related features:

• Authentication - Configure user authentication

• Email - Configure email service

• Newsletter - Configure email list subscription

• Deployment - Deploy to Cloudflare Workers

• Cloudflare

• Storage