blog.dopana

Back

When you run wrangler dev, a Cloudflare D1 database appears on your local machine. But what happens under the hood? This article dives deep into how EmDash handles SQLite3 and API during local development.

1. Local Development Overview#

Local Dev EnvironmentLocalProductionLocalProductionBrowserhttp://localhost:4321Astro Dev ServerNode.jsEmDash RuntimeDB Adapterbetter-sqlite3data.dbCloudflare D1env.DBStorage Adapterlocal filesystem./uploadsCloudflare R2env.MEDIA

2. Miniflare: Local D1 Simulator#

Running wrangler dev starts Miniflare (Cloudflare’s local simulator).

How Miniflare Works#

wrangler devInitialize MiniflareGenerate .sqlite fileRead/write dataProvide Worker Runtimelocalhost:4321 readyDeveloperwrangler devMiniflareSQLite3 FileDeveloperwrangler devMiniflareSQLite3 File

SQLite File Structure#

.wrangler/
  state/
    v3/
      d1/
        miniflare-D1DatabaseObject/
          <hash>.sqlite          # Database file
          <hash>.sqlite-shm      # Shared memory (WAL)
          <hash>.sqlite-wal      # Write-Ahead Log
text
FileRole
<hash>.sqliteActual SQLite database
<hash>.sqlite-shmShared memory for WAL mode
<hash>.sqlite-walWrite-ahead log (concurrency control)

[!NOTE] <hash> is an HMAC hex hash derived from database_id. Same Binding ID always maps to same hash.

WAL Mode Benefits#

Default uses WAL (Write-Ahead Logging) mode:

  • Read and write simultaneously
  • Writes don’t block reads
  • Same mode as production D1

Direct Local DB Access#

Open SQLite files with external tools:

# SQLite CLI
sqlite3 .wrangler/state/v3/d1/miniflare-D1DatabaseObject/<hash>.sqlite

# Also works with Beekeeper Studio, SQLiteFlow, etc.
bash

3. EmDash’s Two DB Adapters#

EmDash specifies DB adapter in astro.config.mjs. Different adapters for local and production.

Local: sqlite() adapter#

import emdash from "emdash/astro";
import { sqlite } from "emdash/db";

export default defineConfig({
  integrations: [
    emdash({
      database: sqlite({
        url: "file:./data.db",  // Local SQLite file
      }),
    }),
  ],
});
js

Production: d1() adapter#

import emdash from "emdash/astro";
import { d1 } from "emdash/db";

export default defineConfig({
  integrations: [
    emdash({
      database: d1(),  // Cloudflare D1 binding
    }),
  ],
});
js

Comparison#

ItemLocal (sqlite())Production (d1())
Enginebetter-sqlite3Cloudflare D1
Storagedata.db fileCloudflare infrastructure
TransactionsStandard SQLitebatch() API
Concurrent writesSingle-writer (SQLite limit)Managed by Cloudflare
SchemaSharedShared

[!TIP] Both adapters share Kysely (SQL query builder). Schema and migrations are identical between local and production.

4. Local Data Flow#

GET /postsgetEmDashCollection("posts")SELECT * FROM postsExecute SQLResponseDataContentHTML responseBrowserAstro Dev ServerEmDash RuntimeKysely Query BuilderSQLite3 DatabaseBrowserAstro Dev ServerEmDash RuntimeKysely Query BuilderSQLite3 Database

5. EmDash REST API Endpoints#

EmDash serves API on the same port as Astro Dev Server.

Local Dev URLs#

http://localhost:4321/_emdash/api/    # REST API
http://localhost:4321/_emdash/admin/  # Admin UI
text

Key API Endpoints#

CategoryEndpoints
Content CRUDGET/POST /content/{collection}, GET/PUT/DELETE /content/{collection}/{id}
PublishingPOST /content/{collection}/{id}/publish, /unpublish, /schedule
MediaGET/POST /media, POST /media/upload-url
SchemaGET/POST /schema/collections
TaxonomiesGET/POST /taxonomies, GET/POST /taxonomies/{name}/terms
MenusGET/POST /menus, GET/PUT/DELETE /menus/{name}
SettingsGET/PUT /settings
SearchGET /search, GET /search/suggest, POST /search/rebuild

Authentication#

# Bearer token auth
curl -H "Authorization: Bearer $EMDASH_TOKEN" \
  http://localhost:4321/_emdash/api/content/posts

# Session auth (from admin panel)
# CSRF protection: X-EmDash-Request: 1 header required
bash

OpenAPI Spec#

# Get API specification
curl http://localhost:4321/_emdash/api/openapi.json
bash

6. Seed Data Application#

On first startup, if the database is empty, seed data from seed/seed.json is applied.

Manual Application#

# Apply seed to local DB
npx emdash seed seed/seed.json --local

# Export schema
npx emdash export-seed > .emdash/seed.json
bash

Application Flow#

YesNowrangler dev startFirst requestDB empty?Apply seed.jsonNormal processingRun migrationsCreate collectionsCreate taxonomiesCreate menusApply settings

7. Local vs Remote: Detailed Comparison#

ItemLocal (SQLite)Remote (D1)
Enginebetter-sqlite3Cloudflare D1
DB Adaptersqlite({ url: "file:./data.db" })d1({ binding: "DB" })
Storage Adapterlocal({ directory: "./uploads" })r2({ binding: "MEDIA" })
Persistence.wrangler/state/ or data.dbCloudflare infrastructure
Concurrent writesSingle-writer (SQLite limit)Managed, but still single-writer
TransactionsStandard SQLitebatch() API
Read ReplicasN/AD1 Sessions API
BackupCopy .sqlite filewrangler d1 export

8. Development Tips#

Reset Data#

# Delete SQLite files to reset
rm .wrangler/state/v3/d1/miniflare-D1DatabaseObject/*.sqlite
rm .wrangler/state/v3/d1/miniflare-D1DatabaseObject/*.sqlite-*

# Restart to recreate
wrangler dev
bash

Shared Team Database#

# Persist to shared directory
wrangler dev --persist-to=./shared-db
bash

Inspect Local DB#

# List tables
sqlite3 .wrangler/state/v3/d1/miniflare-D1DatabaseObject/<hash>.sqlite ".tables"

# Check data
sqlite3 .wrangler/state/v3/d1/miniflare-D1DatabaseObject/<hash>.sqlite \
  "SELECT * FROM posts LIMIT 5;"
bash

9. Summary#

ComponentLocal Dev Behavior
MiniflareCreates SQLite3 files in .wrangler/state/
better-sqlite3Bridge to local SQLite
KyselySQL query builder (shared local/production)
EmDash APIREST API at /_emdash/api/
seed.jsonBootstraps schema on first startup

EmDash + Cloudflare’s local dev environment reproduces D1’s SQL semantics using SQLite3. Miniflare bridges the gap, letting developers verify production behavior locally.

References#