Skip to content
ShipSaaSShipSaaS Docs

Database

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

Setup

Section titled “Setup”

Create and Initialize Local Database

Section titled “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:

Terminal window
bun run db:migrate:local

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

Terminal window
bun run db:studio:local

Create and Initialize Remote Database

Section titled “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

Section titled “(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

Section titled “(2) Create Remote Database”

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

Wrangler CLI

Section titled “Wrangler CLI”
  1. Create a new D1 database:
Terminal window
bunx wrangler d1 create your-database-name
  1. Select no when prompted after the command executes successfully, and copy the database_id from the command output.

Cloudflare Dashboard

Section titled “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

Terminal window
CLOUDFLARE_DATABASE_ID=your-database-id

(3) Initialize Remote Database

Section titled “(3) Initialize Remote Database”

Execute the following command to initialize the remote database:

Terminal window
bun run db:migrate:remote

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

Terminal window
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

Section titled “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

Section titled “Database Commands”

ShipSaaS provides the following database management commands:

Command Description
bun run db:generate Generate Drizzle migration files
bun run db:push Push schema changes to the database (used in development phase)
bun run db:studio:local Open Drizzle Studio (local database)
bun run db:studio:remote Open Drizzle Studio (remote database)
bun run db:migrate:local Apply migrations (local database)
bun run db:migrate:remote Apply migrations (remote database)
bun run auth:schema:generate Generate Better Auth schema

References

Section titled “References”

Next Steps

Section titled “Next Steps”

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