Quick Start Guide

Quick Start Guide

Get up and running with D1 Database Manager in just a few minutes!

🚀 Local Development (No Cloudflare Account Required)

The fastest way to try D1 Manager is using local development mode with mock data.

Step 1: Install

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

Step 2: Start the Servers

Terminal 1 - Frontend:

npm run dev

Runs on http://localhost:5173

Terminal 2 - Worker API:

npx wrangler dev --config wrangler.dev.toml --local

Runs on http://localhost:8787

Step 3: Open the App

Navigate to http://localhost:5173 in your browser.

You'll see sample databases with mock data - perfect for exploring features!

📊 First Steps with the Interface

1. Browse Databases

On the home page, you'll see database cards showing:

• Database name and UUID
• Creation date
• File size
• Number of tables

💡 Tip: Use the search box to quickly filter databases by name - great when you have many databases!

Try it: Click on any database card to explore its tables.

2. View Tables

Inside a database, you'll see:

• List of all tables
• Search bar to filter tables by name
• Quick actions (Browse, Schema, Export)

💡 Tip: Type in the search bar to instantly filter tables - partial matches work too!

Try it: Click the "Browse" button on any table to view its data.

3. Execute Queries

Open the Query Console:

1. Click the "Query" button on any database card
2. Write a SQL query in the editor
3. Press Ctrl+Enter (Cmd+Enter on Mac) to execute

Example query:

SELECT * FROM users LIMIT 10;

4. Create a Table

Use the Visual Schema Designer:

1. Navigate to any database
2. Click "Create Table"
3. Add columns with the visual builder
4. Review the SQL preview
5. Click "Create"

🔑 Key Features to Explore

Database Operations

Create a New Database

1. From the home page, click "Create Database"
2. Enter a name (lowercase, letters, numbers, hyphens)
3. Click "Create"

Rename a Database

1. Click the "Rename" button on a database card
2. Download a backup (recommended)
3. Enter the new name
4. Check the confirmation box
5. Click "Rename Database"

Note: Renaming creates a new database, migrates data, and deletes the original.

Delete a Database

1. Select one or more databases using checkboxes
2. Click "Delete Selected"
3. Confirm the deletion

Table Operations

Clone a Table

1. Navigate to a database
2. Find the table you want to clone
3. Click the "Clone" button
4. Enter a new name
5. Click "Clone Table"

This copies the table structure, data, and indexes.

Export a Table

1. Click the "Export" button on a table
2. Choose format: SQL or CSV
3. The file downloads automatically

Add a Column

1. View a table's data
2. Click "Add Column" in the column management section
3. Specify:
   • Column name
   • Data type (TEXT, INTEGER, REAL, BLOB, NUMERIC)
   • Constraints (NOT NULL, PRIMARY KEY)
   • Default value (optional)
4. Click "Add Column"

Advanced Features

Filter Table Rows

1. View a table's data
2. Use the filter bar above the table
3. Select operator and enter value for any column
4. Filters apply automatically

Available operators:

• TEXT: contains, equals, starts with, ends with
• INTEGER/REAL: =, >, <, ≥, ≤
• NULL: is null, is not null

Cross-Database Search

1. From the home page, expand the "Cross-Database Search" card
2. Enter a search term
3. Select search scope:
   • Table names
   • Column names
   • Table data
4. Click "Search"

Compare Databases

1. From the home page, click "Compare Databases"
2. Select two databases to compare
3. Click "Compare"
4. View differences in:
   • Tables (missing, matching)
   • Column structures
   • Data types

Migrate Data Between Databases

1. From the home page, click "Migrate Database"
2. Select source and target databases
3. Choose tables to migrate
4. Review migration plan
5. Click "Start Migration"

🎨 Theme Switching

Click the theme icon in the header to cycle through:

• System - Follows your OS preference
• Light - Force light mode
• Dark - Force dark mode

Your preference is saved automatically.

⌨️ Keyboard Shortcuts

• Ctrl+Enter / Cmd+Enter - Execute query in Query Console
• Esc - Close open dialogs

💡 Tips & Tricks

1. Bulk Operations

Select multiple databases or tables using checkboxes for efficient batch operations:

• Download multiple databases as a ZIP file
• Delete multiple items at once
• Clone multiple tables simultaneously
• Export multiple tables as SQL or CSV

2. URL Persistence for Filters

When you filter table rows, the filters are saved in the URL. Bookmark or share the URL to preserve your filtered view.

3. Cascade Impact Simulator

Before deleting rows or tables, use the "Simulate Cascade Impact" button to visualize exactly what will be affected:

• Interactive graph showing all cascade paths
• Row count estimates at each level
• Export reports for documentation
• See Cascade Impact Simulator for details

4. Query History

All your executed queries are automatically saved. Access them from the Query Console's history tab.

5. Saved Queries

Create reusable queries:

1. Write a query in the Query Console
2. Click "Save Query"
3. Give it a name and description
4. Load it anytime from the saved queries list

🔄 Common Workflows

Workflow 1: Create and Populate a Table

# 1. Create database
Click "Create Database" → Enter "my-app-db"

# 2. Open Query Console
Click "Query" on the new database

# 3. Create table
CREATE TABLE users (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  name TEXT NOT NULL,
  email TEXT UNIQUE NOT NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

# 4. Insert data
INSERT INTO users (name, email) VALUES
  ('Alice', 'alice@example.com'),
  ('Bob', 'bob@example.com');

# 5. Browse data
Navigate to database → Click "Browse" on users table

Workflow 2: Export and Import Data

# Export
1. Navigate to a database
2. Select tables using checkboxes
3. Click "Download Selected"
4. Choose format (SQL or CSV)
5. Save the ZIP file

# Import
1. From home page, click "Upload Database"
2. Choose "Create new database" or "Import into existing"
3. Select your SQL file
4. Click "Upload"

Workflow 3: Database Optimization

# Optimize one or more databases
1. Select databases using checkboxes
2. Click "Optimize Selected"
3. Confirm the operation
4. Wait for ANALYZE to complete

This updates query statistics for better query performance.

🐛 Troubleshooting Quick Fixes

Can't See Any Databases

• Local Dev: Make sure both frontend and Worker API are running
• Production: Check Cloudflare API credentials and permissions

Query Console Not Working

• Check that the Worker API is accessible
• Look for errors in the browser console (F12)
• Verify your SQL syntax

Tables Not Loading

• Refresh the page
• Check browser console for errors
• Verify database permissions

Authentication Loop

• Clear browser cache and cookies
• Check Cloudflare Access configuration
• Verify TEAM_DOMAIN and POLICY_AUD are correct

📚 Next Steps

Now that you know the basics:

1. Database Management - Deep dive into database operations
2. Table Operations - Master table management
3. Query Console - Advanced SQL querying
4. Configuration - Customize your setup
5. Production Deployment - Deploy to Cloudflare Workers

🎯 Try the Live Demo

Want to see it in action without installing?

Visit: https://d1.adamic.tech/

Note: The live demo uses Cloudflare Access authentication.

---

Questions? Check Troubleshooting or open an issue.