EmDash + Cloudflare: SQLite3 and API at Local Dev
How EmDash handles SQLite3 and API during local development. Miniflare, D1, REST API endpoints explained.
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#
2. Miniflare: Local D1 Simulator#
Running wrangler dev starts Miniflare (Cloudflare’s local simulator).
How Miniflare Works#
SQLite File Structure#
.wrangler/
state/
v3/
d1/
miniflare-D1DatabaseObject/
<hash>.sqlite # Database file
<hash>.sqlite-shm # Shared memory (WAL)
<hash>.sqlite-wal # Write-Ahead Logtext| File | Role |
|---|---|
<hash>.sqlite | Actual SQLite database |
<hash>.sqlite-shm | Shared memory for WAL mode |
<hash>.sqlite-wal | Write-ahead log (concurrency control) |
[!NOTE]
<hash>is an HMAC hex hash derived fromdatabase_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.bash3. 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
}),
}),
],
});jsProduction: d1() adapter#
import emdash from "emdash/astro";
import { d1 } from "emdash/db";
export default defineConfig({
integrations: [
emdash({
database: d1(), // Cloudflare D1 binding
}),
],
});jsComparison#
| Item | Local (sqlite()) | Production (d1()) |
|---|---|---|
| Engine | better-sqlite3 | Cloudflare D1 |
| Storage | data.db file | Cloudflare infrastructure |
| Transactions | Standard SQLite | batch() API |
| Concurrent writes | Single-writer (SQLite limit) | Managed by Cloudflare |
| Schema | Shared | Shared |
[!TIP] Both adapters share Kysely (SQL query builder). Schema and migrations are identical between local and production.
4. Local Data Flow#
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 UItextKey API Endpoints#
| Category | Endpoints |
|---|---|
| Content CRUD | GET/POST /content/{collection}, GET/PUT/DELETE /content/{collection}/{id} |
| Publishing | POST /content/{collection}/{id}/publish, /unpublish, /schedule |
| Media | GET/POST /media, POST /media/upload-url |
| Schema | GET/POST /schema/collections |
| Taxonomies | GET/POST /taxonomies, GET/POST /taxonomies/{name}/terms |
| Menus | GET/POST /menus, GET/PUT/DELETE /menus/{name} |
| Settings | GET/PUT /settings |
| Search | GET /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 requiredbashOpenAPI Spec#
# Get API specification
curl http://localhost:4321/_emdash/api/openapi.jsonbash6. 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.jsonbashApplication Flow#
7. Local vs Remote: Detailed Comparison#
| Item | Local (SQLite) | Remote (D1) |
|---|---|---|
| Engine | better-sqlite3 | Cloudflare D1 |
| DB Adapter | sqlite({ url: "file:./data.db" }) | d1({ binding: "DB" }) |
| Storage Adapter | local({ directory: "./uploads" }) | r2({ binding: "MEDIA" }) |
| Persistence | .wrangler/state/ or data.db | Cloudflare infrastructure |
| Concurrent writes | Single-writer (SQLite limit) | Managed, but still single-writer |
| Transactions | Standard SQLite | batch() API |
| Read Replicas | N/A | D1 Sessions API |
| Backup | Copy .sqlite file | wrangler 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 devbashShared Team Database#
# Persist to shared directory
wrangler dev --persist-to=./shared-dbbashInspect 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;"bash9. Summary#
| Component | Local Dev Behavior |
|---|---|
| Miniflare | Creates SQLite3 files in .wrangler/state/ |
| better-sqlite3 | Bridge to local SQLite |
| Kysely | SQL query builder (shared local/production) |
| EmDash API | REST API at /_emdash/api/ |
| seed.json | Bootstraps 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.