d1-studio

Get started

Installation

# Install globally using npm
npm install -g d1s

# Or using yarn
yarn global add d1s

Configuration

Your project must have a configuration file with your D1 database settings. D1 Studio now supports both the traditional wrangler.toml format as well as the newer JSON-based configuration (wrangler.jsonc or wrangler.json).

# wrangler.toml
name = "your-project"

[[d1_databases]]
binding = "DB"                        # Environment binding name
database_name = "your-database-name"  # Your database name
database_id = "your-database-id"      # Database ID from Cloudflare

Note: If you haven't created a D1 database yet, you can do so using:

wrangler d1 create your-database-name

Then copy the provided configuration into your configuration file.

Database configuration

Local development setup
  • D1 Studio automatically detects and uses your local SQLite database located in .wrangler/state/d1/
  • No additional configuration needed for local development
  • Local changes are tracked through migrations
Remote database setup
  • Ensure your database is created in Cloudflare D1
  • Enter your Account ID and D1 API Token from your Cloudflare account
  • Verify the database_id in your configuration file matches your Cloudflare D1 instance

First-time setup

Start d1-studio

npx d1s

Initial Launch

d1-studio will automatically:

  • Locate your configuration file (wrangler.toml or wrangler.jsonc)
  • Identify configured D1 databases
  • Launch the web interface (default: http://localhost:4000)

Verify setup

The console will display:

┌─────────────────────────────────────────┐
│                                         │
│   D1 Studio is running on port 4000     │
│                                         │
│   Local:  http://localhost:4000         │
│                                         │
└─────────────────────────────────────────┘

Authentication and remote operations

API Token Requirements

Before performing any remote operations (pull/push), you'll need a Cloudflare API token with:

  • D1: Read and Write
  • Account Settings: Read

Token Scope

  • The token is stored at the browser level, not per project/database
  • Once authenticated, the same token is used across all projects and databases
  • You don't need to re-enter the token for different projects/databases as long as:
    • You're using the same browser
    • The token hasn't expired
    • The token hasn't been cleared

When Token Re-entry is Required

  • First time using d1-studio in a new browser
  • After manually clearing the token
  • After clearing browser data
  • If the token has expired or been revoked in Cloudflare
  • If the token lacks permissions for a specific database

Authentication flow

1. Click "Pull Remote" or "Push Remote" in sidebar
2. If no token exists, authentication dialog appears
3. Enter your cloudflare account ID and D1 API token
4. Token is verified with Cloudflare
5. If valid, token is stored in localStorage

Remote operations

Pull and push remote databases

  • Click "pull/push remote" in the environment controls
  • If not authenticated, enter your D1 API token
  • Token is verified before proceeding
  • Pull: Remote database state is pulled to local
  • Push: Changes are pushed to remote database

Security Considerations

  • Token is stored only in browser localStorage under key cloudflare_token
  • No server-side storage or transmission of tokens
  • Clear tokens using environment controls or clearing browser data
  • Each new browser/device requires re-authentication
  • Token validation occurs on every remote operation

Each of these components works together to provide a smooth start with D1 Studio. Once configured, you can begin managing your D1 databases through the intuitive web interface, all while maintaining full compatibility with your existing Cloudflare D1 setup.