EmDash + Cloudflare: SQLite3 và API trong Phát Triển Local
EmDash xử lý SQLite3 và API thế nào trong môi trường development local. Giải thích Miniflare, D1, REST API endpoint.
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#
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#
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 Logtext| File | Vai Trò |
|---|---|
<hash>.sqlite | File SQLite database thực tế |
<hash>.sqlite-shm | Shared memory cho WAL mode |
<hash>.sqlite-wal | Write-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 đượcbash3. 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
}),
}),
],
});jsProduction: d1() adapter#
import emdash from "emdash/astro";
import { d1 } from "emdash/db";
export default defineConfig({
integrations: [
emdash({
database: d1(), // Cloudflare D1 binding
}),
],
});jsSo Sánh#
| Mục | Local (sqlite()) | Production (d1()) |
|---|---|---|
| Engine | better-sqlite3 | Cloudflare D1 |
| Storage | File data.db | Cloudflare infrastructure |
| Transaction | SQLite standard | batch() API |
| Concurrent write | Single-writer (SQLite limit) | Managed by Cloudflare |
| Schema | Chung | Chung |
[!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#
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 UItextAPI Endpoints Chính#
| Danh Mục | 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 |
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ếtbashOpenAPI Spec#
# Lấy API specification
curl http://localhost:4321/_emdash/api/openapi.jsonbash6. Á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.jsonbashFlow Đầy Đủ#
7. Local vs Remote: So Sánh Chi Tiết#
| Mục | 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/ hoặc data.db | Cloudflare infrastructure |
| Concurrent write | Single-writer (SQLite limit) | Managed, nhưng vẫn single-writer |
| Transactions | SQLite standard | batch() API |
| Read Replicas | Không có | D1 Sessions API |
| Backup | Copy file .sqlite | wrangler 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 devbashDatabase Chia Sẻ Cho Team#
# Persistent vào thư mục chia sẻ
wrangler dev --persist-to=./shared-dbbashXem 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;"bash9. Tóm Tắt#
| Thành Phần | Hành Vi Khi Phát Triển Local |
|---|---|
| Miniflare | Tạo file SQLite3 trong .wrangler/state/ |
| better-sqlite3 | Bridge nối với SQLite local |
| Kysely | SQL query builder (chung local/production) |
| EmDash API | Cung cấp REST API tại /_emdash/api/ |
| seed.json | Bootstrap 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.