united-tattoo/D1_SETUP.md

Cloudflare D1 Database Setup Guide

This guide will help you set up Cloudflare D1 database for the United Tattoo Studio management platform.

Prerequisites

1. Cloudflare Account with Workers/Pages access
2. Wrangler CLI installed globally: npm install -g wrangler
3. Authenticated with Cloudflare: wrangler auth login

Step 1: Create D1 Database

# Create the D1 database
npm run db:create

# This will output something like:
# ✅ Successfully created DB 'united-tattoo-db' in region ENAM
# Created your database using D1's new storage backend. The new storage backend is not yet recommended for production workloads, but backs up your data via point-in-time restore.
# 
# [[d1_databases]]
# binding = "DB"
# database_name = "united-tattoo-db"
# database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Step 2: Update wrangler.toml

Copy the database_id from the output above and update your wrangler.toml:

[[d1_databases]]
binding = "DB"
database_name = "united-tattoo-db"
database_id = "your-actual-database-id-here"  # Replace with the ID from step 1

Step 3: Run Database Migrations

For Local Development:

# Create tables in local D1 database
npm run db:migrate:local

For Production:

# Create tables in production D1 database
npm run db:migrate

Step 4: Verify Database Setup

Check Local Database:

# List tables in local database
npm run db:studio:local

Check Production Database:

# List tables in production database
npm run db:studio

Step 5: Development Workflow

Local Development:

# Start Next.js development server
npm run dev

# The app will use local SQLite file for development
# Database file: ./local.db

Preview with Cloudflare:

# Build for Cloudflare Pages
npm run pages:build

# Preview locally with Cloudflare runtime
npm run preview

# Deploy to Cloudflare Pages
npm run deploy

Database Schema

The database includes the following tables:

• users - User accounts and roles
• artists - Artist profiles and information
• portfolio_images - Artist portfolio images
• appointments - Booking and appointment data
• availability - Artist availability schedules
• site_settings - Studio configuration
• file_uploads - File upload metadata

Environment Variables

Local Development (.env.local):

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

Production (Cloudflare Pages):

Environment variables are managed through:

1. wrangler.toml for public variables
2. Cloudflare Dashboard for secrets
3. D1 database binding automatically available as env.DB

Useful Commands

# Database Management
npm run db:create          # Create new D1 database
npm run db:migrate         # Run migrations on production DB
npm run db:migrate:local   # Run migrations on local DB
npm run db:studio          # Query production database
npm run db:studio:local    # Query local database

# Cloudflare Pages
npm run pages:build        # Build for Cloudflare Pages
npm run preview           # Preview with Cloudflare runtime
npm run deploy            # Deploy to Cloudflare Pages

# Development
npm run dev               # Start Next.js dev server
npm run build             # Standard Next.js build

Troubleshooting

Common Issues:

1. "Database not found"

   • Make sure you've created the D1 database: npm run db:create
   • Verify the database_id in wrangler.toml matches the created database

2. "Tables don't exist"

   • Run migrations: npm run db:migrate:local (for local) or npm run db:migrate (for production)

3. "Wrangler not authenticated"

   • Run: wrangler auth login

4. "Permission denied"

   • Ensure your Cloudflare account has Workers/Pages access
   • Check that you're authenticated with the correct account

Database Access in Code:

In your API routes, access the D1 database through the environment binding:

// In API routes (production)
const db = env.DB; // Cloudflare D1 binding

// For local development, you'll use SQLite
// The lib/db.ts file handles this automatically

Next Steps

After setting up D1:

1. Update the database functions in lib/db.ts to use actual D1 queries
2. Test the admin dashboard with real database operations
3. Deploy to Cloudflare Pages for production testing