blog.dopana

Quay lại

Khi chạy wrangler dev, database D1 của Cloudflare xuất hiện ngay trên máy local. Nhưng điều gì xảy ra bên trong? Bài viết này đi sâu vào cách EmDash xử lý SQLite3 và API trong môi trường phát triển local.

1. Tổng Quan Phát Triển Local#

Môi Trường Phát Triển LocalLocalProductionLocalProductionBrowserhttp://localhost:4321Astro Dev ServerNode.jsEmDash RuntimeDB Adapterbetter-sqlite3data.dbCloudflare D1env.DBStorage Adapterlocal filesystem./uploadsCloudflare R2env.MEDIA

2. Miniflare: Trình Mô Phỏng D1 Local#

Khi chạy wrangler dev, Miniflare (trình mô phỏng local của Cloudflare) được khởi động.

Cơ Chế Miniflare#

wrangler devKhởi tạo MiniflareTạo file .sqliteĐọc ghi dữ liệuCung cấp Worker Runtimelocalhost:4321 readyDeveloperwrangler devMiniflareSQLite3 FileDeveloperwrangler devMiniflareSQLite3 File

Cấu Trúc File SQLite#

.wrangler/
  state/
    v3/
      d1/
        miniflare-D1DatabaseObject/
          <hash>.sqlite          # File database
          <hash>.sqlite-shm      # Shared memory (WAL)
          <hash>.sqlite-wal      # Write-Ahead Log
text
FileVai Trò
<hash>.sqliteFile SQLite database thực tế
<hash>.sqlite-shmShared memory cho WAL mode
<hash>.sqlite-walWrite-ahead log (kiểm soát truy cập đồng thời)

[!NOTE] <hash> là HMAC hex hash bắt nguồn từ database_id. Cùng Binding ID sẽ luôn map cùng hash.

Ưu Điểm WAL Mode#

Mặc định dùng WAL (Write-Ahead Logging) mode:

  • Đọc và ghi đồng thời được
  • Ghi không block đọc
  • Cùng chế độ với D1 production

Truy Cập Trực Tiếp Local DB#

Mở file SQLite bằng tool bên ngoài:

# Kết nối SQLite CLI
sqlite3 .wrangler/state/v3/d1/miniflare-D1DatabaseObject/<hash>.sqlite

# Beekeeper Studio, SQLiteFlow, v.v. cũng kết nối được
bash

3. Hai DB Adapter Của EmDash#

EmDash chọn DB adapter trong astro.config.mjs. Local và production dùng adapter khác nhau.

Local Development: sqlite() adapter#

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

export default defineConfig({
  integrations: [
    emdash({
      database: sqlite({
        url: "file:./data.db",  // File SQLite local
      }),
    }),
  ],
});
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

So Sánh#

MụcLocal (sqlite())Production (d1())
Enginebetter-sqlite3Cloudflare D1
StorageFile data.dbCloudflare infrastructure
TransactionSQLite standardbatch() API
Concurrent writeSingle-writer (SQLite limit)Managed by Cloudflare
SchemaChungChung

[!TIP] Cả hai adapter đều dùng chung Kysely (SQL query builder). Schema và migrations giống nhau giữa local và production.

4. Luồng Dữ Liệu Local#

GET /postsgetEmDashCollection("posts")SELECT * FROM postsThực thi SQL queryResponseDataContentHTML responseBrowserAstro Dev ServerEmDash RuntimeKysely Query BuilderSQLite3 DatabaseBrowserAstro Dev ServerEmDash RuntimeKysely Query BuilderSQLite3 Database

5. REST API Endpoints Của EmDash#

EmDash cung cấp API trên cùng port với Astro Dev Server.

URL Phát Triển Local#

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

API Endpoints Chính#

Danh MụcEndpoints
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

Xác Thực#

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

# Session authentication (từ admin panel)
# CSRF protection: header X-EmDash-Request: 1 cần thiết
bash

OpenAPI Spec#

# Lấy API specification
curl http://localhost:4321/_emdash/api/openapi.json
bash

6. Áp Dụng Seed Data#

Khi khởi động lần đầu, nếu database trống, seed data từ seed/seed.json sẽ được áp dụng.

Áp Dụng Thủ Công#

# Áp dụng seed vào local DB
npx emdash seed seed/seed.json --local

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

Flow Đầy Đủ#

CóKhôngwrangler dev startRequest đầu tiênDB trống?Áp dụng seed.jsonXử lý bình thườngChạy migrationsTạo collectionsTạo taxonomiesTạo menusÁp dụng settings

7. Local vs Remote: So Sánh Chi Tiết#

MụcLocal (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/ hoặc data.dbCloudflare infrastructure
Concurrent writeSingle-writer (SQLite limit)Managed, nhưng vẫn single-writer
TransactionsSQLite standardbatch() API
Read ReplicasKhông cóD1 Sessions API
BackupCopy file .sqlitewrangler d1 export

8. Tips Khi Phát Triển#

Reset Dữ Liệu#

# Xóa file SQLite để reset
rm .wrangler/state/v3/d1/miniflare-D1DatabaseObject/*.sqlite
rm .wrangler/state/v3/d1/miniflare-D1DatabaseObject/*.sqlite-*

# Khởi động lại để tạo mới
wrangler dev
bash

Database Chia Sẻ Cho Team#

# Persistent vào thư mục chia sẻ
wrangler dev --persist-to=./shared-db
bash

Xem Nội Dung Local DB#

# Liệt kê bảng
sqlite3 .wrangler/state/v3/d1/miniflare-D1DatabaseObject/<hash>.sqlite ".tables"

# Kiểm tra dữ liệu
sqlite3 .wrangler/state/v3/d1/miniflare-D1DatabaseObject/<hash>.sqlite \
  "SELECT * FROM posts LIMIT 5;"
bash

9. Tóm Tắt#

Thành PhầnHành Vi Khi Phát Triển Local
MiniflareTạo file SQLite3 trong .wrangler/state/
better-sqlite3Bridge nối với SQLite local
KyselySQL query builder (chung local/production)
EmDash APICung cấp REST API tại /_emdash/api/
seed.jsonBootstrap schema khi khởi động lần đầu

Môi trường phát triển local của EmDash + Cloudflare tái hiện SQL semantics của D1 production bằng SQLite3. Miniflare là cầu nối, developer kiểm tra hành vi production ngay trên local.

Tài Liệu Tham Khảo#