writenotenow/d1-manager repository overview

⁠D1 Database Manager

Modern web GUI for Cloudflare D1 databases featuring Zero Trust authentication.

Run D1 Database Manager in Docker for development, testing, or self-hosted deployments. Get full visual control over schemas, data migrations, SQL execution, and portable database export/import via Cloudflare Access.

Live Demo Site⁠ • GitHub⁠ • Wiki⁠ • Changelog⁠ • Release Article⁠

⁠Tech Stack

Frontend: React | Vite | TypeScript | Tailwind CSS | shadcn/ui

Backend: Cloudflare Workers + KV + D1 + R2 + Durable Objects + Zero Trust

⁠🎯 Features

⁠Database Management

• Create, rename, clone, delete, and optimize databases
• Export Database - SQL/JSON/CSV formats with portable schema + data
• Import Database - SQL/JSON/CSV/ZIP with create new or update existing
• Quick Actions - Icon buttons on each database card for instant access to all operations
• Bulk Operations - Multi-select for batch export (SQL/JSON/CSV), optimize, and delete
• Clone Database - Multi-step wizard with selective table cloning and granular options
• Grid/List View Toggle - Switch between card grid and compact sortable table view
• Copyable Database IDs - Click to copy database IDs with visual feedback
• Expanded Color Picker - 27 colors organized by hue family for visual organization
• R2 Backup/Restore + Unified Hub (Cloudflare Workers only) - Manual backups, undo history, and R2 snapshots in one dialog with multi-select, backup counts, and orphaned-backup visibility
• Scheduled R2 Backups (Cloudflare Workers only) - Per-database daily/weekly/monthly schedules with cron triggers, next-run tracking, and enable/disable controls
• Safety Backups (Cloudflare Workers only) - Delete, rename, and STRICT mode operations automatically create R2 backups before proceeding
• Automated Migration System - Auto-detects and applies schema upgrades with one-click "Upgrade Now" banner
• Database search filter & job history - Quickly find databases and audit all operations with full date/time and duration tracking

⁠Table Operations

• Visual schema designer with STRICT mode and generated column support
• NEW! Clone, export (SQL/CSV/JSON), import (CSV/JSON/SQL), and bulk operations
• Column management (add, modify, rename, delete) with UNIQUE constraint support
• Foreign key dependency analysis
• Quick Actions - Icon buttons on each table card for instant access to all operations
• Import Data - Import CSV, JSON, or SQL into new or existing tables with duplicate handling (Fail/Replace/Skip) and auto-add missing columns
• STRICT Mode - Create new tables with STRICT mode or convert existing tables with automatic type mapping and validation
• Generated Columns - Create STORED or VIRTUAL computed columns with expression editor
• Table-level R2 Backup/Restore (Cloudflare Workers only) - Backup or restore individual tables directly from table cards (Grid and List views)
• Grid/List View Toggle - Switch between card grid and compact sortable table view (list view is default)
• Row search filter + table search - Quickly filter visible rows and find tables
• Table Row Counts - See row counts on table cards (formatted with locale separators)
• Table color tags - Assign colors for visual organization

⁠Query Console

• Tabbed interface - Query, SQL Diff, Drizzle ORM, and Query Builder in dedicated tabs
• Drizzle ORM Console - Introspect schemas, view migration status/history, generate SQL, push changes (with dry-run), and export TypeScript schema
• SQL Formatter - One-click formatting with SQLite-aware sql-formatter library
• SQL Autocomplete Toggle - Turn suggestions on/off with preference persisted to localStorage
• Rich editor - Syntax highlighting, line numbers, find/replace, hover docs, inline error squiggles, and word wrap toggle
• SQL Diff Editor - Compare queries side-by-side with syntax highlighting
• Visual Query Builder - Build queries interactively with editable SQL output and "Send to Editor" integration
• Query history and saved queries
• CSV export

⁠Advanced Features

• NEW! Schema Comparison with Migration Script Generation - Compare two databases and generate executable SQL migration scripts with risk classification, copy/download, and apply-to-target functionality
• NEW! AI Search Integration (Cloudflare Workers only) - Semantic search over database schemas and data using Cloudflare AI Search (AutoRAG). Export databases to R2 for indexing, then query with natural language or get AI-generated SQL suggestions
• Unified Backup & Restore Hub (Cloudflare Workers only) - Undo history and R2 backups in one dialog with bulk restore/download/delete, backup counts, source tags, and orphaned-backup visibility
• Scheduled R2 Backups (Cloudflare Workers only) - Daily/weekly/monthly schedules with per-database controls, next-run previews, last-run status, and job history integration
• Foreign Key Visualizer & ER Diagram - Interactive graphs with fullscreen mode, export (PNG/SVG/JSON), alphabetized dropdowns, and dual layouts (hierarchical/force-directed)
• Cascade Impact Simulator - Preview DELETE cascades before execution with optimized dependency checks and multi-format export (CSV/JSON/Text/PDF)
• Circular Dependency Detector - DFS-based cycle detection with severity classification and breaking suggestions
• Undo/Rollback with safeguards - Automatic undo snapshots for destructive operations (R2 backups available on Cloudflare Workers deployments)
• FTS5 Full-Text Search - Manage virtual tables, convert to/from regular tables, dedicated FTS5 search mode in main Search tab, and quick actions on FTS5 table cards
• Index Analyzer - Smart index recommendations plus "Create All Indexes" one-click apply with progress tracking
• Metrics Dashboard - Query volume (reads/writes), P90 latency, rows read, and storage trends via GraphQL Analytics with time range selector (24h/7d/30d)
• NEW! Query Insights Tab for slow query analysis with performance badges and sortable table
• NEW! Health Dashboard - System health score, backup coverage alerts, failed backup tracking, and replication status overview
• Time Travel - View bookmarks, checkpoint history, manual checkpoint capture, and CLI restore commands
• Read Replication - Enable/disable global read replicas with D1 Sessions API info
• Constraint Validator - Validate foreign key, NOT NULL, and UNIQUE constraints across database with guided fix workflow

⁠Webhook Notifications

• Event-driven webhooks - Send HTTP notifications on key database events
• Configurable events - database_create, database_delete, database_export, database_import, job_failed, batch_complete
• HMAC signatures - Optional secret-based request signing for security
• Test webhooks - Verify endpoint connectivity before going live
• Centralized Error Logging - Structured logging with module-prefixed error codes, automatic webhook notifications for critical errors

⁠🚀 Quick Start

⁠1. Set Up Metadata Database

D1 Manager requires a D1 database for job history, color tags, webhooks, and saved queries.

Authenticate with Cloudflare:

npx wrangler login

Create the metadata database:

npx wrangler d1 create d1-manager-metadata

Clone repo and initialize schema:

git clone https://github.com/neverinfamous/d1-manager.git
cd d1-manager
npx wrangler d1 execute d1-manager-metadata --remote --file=worker/schema.sql

⁠2. Get Cloudflare Credentials

⁠3. Run Container

docker pull writenotenow/d1-manager:latest

docker run -d \
  -p 8787:8787 \
  -e ACCOUNT_ID=your_cloudflare_account_id \
  -e API_KEY=your_cloudflare_api_token \
  -e TEAM_DOMAIN=https://yourteam.cloudflareaccess.com \
  -e POLICY_AUD=your_cloudflare_access_aud_tag \
  --name d1-manager \
  --restart unless-stopped \
  writenotenow/d1-manager:latest

Open http://localhost:8787⁠

⁠⬆️ Upgrading

⁠1. Update Schema

Automated Migrations (Recommended)

D1 Manager includes an automated migration system:

1. Update the container to the latest version
2. Open the app - a banner will appear if schema updates are needed
3. Click "Upgrade Now" to apply migrations automatically

The app detects pending migrations and handles legacy installations gracefully.

Manual Schema Update (Alternative)

If you prefer manual control:

npx wrangler d1 execute d1-manager-metadata --remote --file=worker/schema.sql

Or apply individual migrations:

npx wrangler d1 execute d1-manager-metadata --remote --file=worker/migrations/002_add_color_tags.sql

⁠Docker vs Cloudflare Workers Features

Docker deployments do not require Durable Object configuration. The Durable Object binding (used for R2 backups in Cloudflare Workers deployments) is not applicable to Docker containers.

If you see documentation about Durable Objects or BACKUP_DO bindings, those apply only to Cloudflare Workers deployments. Docker users can safely ignore those sections.

For R2 backup features, deploy to Cloudflare Workers instead. See the main README.md⁠ for Workers deployment instructions.

⁠2. Update Container

docker pull writenotenow/d1-manager:latest
docker stop d1-manager && docker rm d1-manager

docker run -d \
  -p 8787:8787 \
  -e ACCOUNT_ID=your_account_id \
  -e API_KEY=your_api_token \
  -e TEAM_DOMAIN=https://yourteam.cloudflareaccess.com \
  -e POLICY_AUD=your_aud_tag \
  --name d1-manager \
  --restart unless-stopped \
  writenotenow/d1-manager:latest

⁠🐋 Docker Compose

Create docker-compose.yml:

services:
  d1-manager:
    image: writenotenow/d1-manager:latest
    container_name: d1-manager
    ports:
      - "8787:8787"
    environment:
      - ACCOUNT_ID=${ACCOUNT_ID}
      - API_KEY=${API_KEY}
      - TEAM_DOMAIN=${TEAM_DOMAIN}
      - POLICY_AUD=${POLICY_AUD}
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8787/health"]
      interval: 30s
      timeout: 10s
      retries: 3

Create .env:

ACCOUNT_ID=your_cloudflare_account_id
API_KEY=your_cloudflare_api_token
TEAM_DOMAIN=https://yourteam.cloudflareaccess.com
POLICY_AUD=your_cloudflare_access_aud_tag

Start:

docker compose up -d

Upgrade:

docker compose pull && docker compose up -d

⁠📋 Environment Variables

⁠📊 Container Info

⁠🏷️ Available Tags

⁠🔧 Building from Source

git clone https://github.com/neverinfamous/d1-manager.git
cd d1-manager

docker build -t d1-manager:local .

docker run -d -p 8787:8787 \
  -e ACCOUNT_ID=your_account_id \
  -e API_KEY=your_api_token \
  -e TEAM_DOMAIN=https://yourteam.cloudflareaccess.com \
  -e POLICY_AUD=your_aud_tag \
  d1-manager:local

⁠🐞 Troubleshooting

⁠Container Won't Start

docker logs d1-manager

Common causes:

• Missing environment variables
• Port already in use

⁠Authentication Failures

• Verify TEAM_DOMAIN includes https://
• Confirm POLICY_AUD matches your Access application
• Check API token has D1 Edit permission

⁠Database Operations Fail

Test your API token:

curl -X GET "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/d1/database" \
  -H "Authorization: Bearer ${API_KEY}"

📚 More solutions: Wiki - Troubleshooting⁠

⁠📚 Additional Resources

• Wiki Documentation⁠
• GitHub Repository⁠
• Cloudflare D1 Docs⁠
• Cloudflare Access Docs⁠

⁠📞 Support

• 🐛 Bug Reports: GitHub Issues⁠
• 💡 Feature Requests: GitHub Discussions⁠
• 📧 Email: [email protected]⁠

⁠📄 License

MIT License - see LICENSE⁠

Made with ❤️ for the Cloudflare and Docker communities