Database
Khoảng 10 phút. Làm xong, app của bạn có bảng đơn hàng với index đúng chỗ và một repository trả danh sách có phân trang, tìm kiếm, lọc.
Mỗi app có một database SQLite riêng. Bạn khai báo bảng trong file .table.ts (ví dụ orders.table.ts của app bán vật tư) và truy vấn bằng Drizzle trong repository.ts. manh.run cập nhật schema mỗi lần deploy.
Database nằm cạnh code của app trên hạ tầng của manh.run, nên truy vấn chạy ngay tại chỗ, không đi qua mạng. Bạn không cần cấu hình kết nối, chỉ việc import { db } from "app/db".
Bảng
Mỗi resource có một file app/<resource>/<resource>.table.ts, viết theo Drizzle chuẩn. Import hàm dựng bảng từ app/db, đừng import từ drizzle-orm.
import { sqliteTable, integer, text, index } from "app/db";
import { products } from "../products/products.table";
export const orders = sqliteTable("orders", {
id: integer("id").primaryKey({ autoIncrement: true }),
customerName: text("customer_name").notNull(),
productId: integer("product_id").notNull()
.references(() => products.id, { onDelete: "restrict" }),
total: integer("total").notNull(),
status: text("status").notNull().default("new"),
createdAt: integer("created_at").notNull(),
}, (t) => [
index("orders_created_at_idx").on(t.createdAt), // cột sắp xếp của danh sách
index("orders_status_idx").on(t.status), // cột lọc
]);SQLite không có kiểu boolean, hãy dùng integer với 0 / 1. Đánh index mọi cột mà danh sách dùng để sắp xếp: request của một app chạy lần lượt, nên một trang danh sách phải sắp xếp cả bảng sẽ làm chậm cả app. Thiếu index thì check cảnh báo perf.order-unindexed.
Schema đổi khi deploy
Mỗi lần deploy, manh.run đọc các file .table.ts và cập nhật database. manh.run chỉ thêm, không xoá: bảng mới thì tạo, cột mới thì thêm, index và ràng buộc (.unique(), .references(...), index()) thì dựng. Cột và bảng không bao giờ bị tự xoá hay đổi kiểu.
- Bảng đã có dữ liệu thì cột mới
.notNull()thiếu.default()được thêm ở dạng cho phép null, và ghi chú deploy báo việc này. Hãy cho cột bắt buộc mới một giá trị mặc định. - Đổi tên cột: thêm cột mới, chép dữ liệu bằng
db_exec, sửa code, rồi mới bỏ cột cũ.
Truy vấn trong repository
Mọi lệnh database nằm trong app/<resource>/repository.ts. Danh sách một bảng dùng listOf, trả { data, total } có phân trang, tìm kiếm, lọc và sắp xếp.
import { db, eq, listOf } from "app/db";
import { orders } from "./orders.table";
export const listOrders = (query: Record<string, unknown>) =>
listOf(orders, query, {
search: [orders.customerName], // `search` → LIKE trên các cột này
filters: { status: orders.status }, // khoá query → cột
sort: { createdAt: orders.createdAt }, // chỉ các cột này được sắp xếp
});
export async function setStatus(id: number, status: string) {
const [row] = await db.update(orders).set({ status }).where(eq(orders.id, id)).returning();
return row;
}Handler khai báo query bằng listSchema(...) (pageSize tối đa 100) và body bằng schemaOf(orders).insert.pick({...}), cả hai từ app/db.
Request chạy lần lượt
Mỗi app xử lý request lần lượt, xong request này mới tới request khác. Việc đọc rồi ghi (kiểm tồn kho rồi trừ kho) không bị request khác chen vào giữa, nên bạn không cần transaction để chống tranh chấp.
Ngoại lệ: trong lúc await một lệnh gọi ra ngoài (fetch, manh/email, manh/openai), request khác có thể chạy. Vì vậy hãy ghi dữ liệu trước rồi mới gửi email.
Transaction
Không dùng db.transaction(async …): với callback async, lệnh sau await đầu tiên nằm ngoài transaction và lỗi không rollback (code.no-async-transaction).
- Mặc định: làm mọi lệnh đọc và mọi phép kiểm trước lệnh ghi đầu tiên.
- Nhiều lệnh ghi phải cùng thành công: callback đồng bộ, mỗi lệnh kết thúc bằng
.run()/.get(), không cóawait. Lỗi ném ra bên trong sẽ rollback.
Giới hạn cứng
Vượt các giới hạn này thì câu lệnh lỗi 500, không có cấu hình để nâng:
- Tối đa 100 giá trị ràng buộc mỗi câu lệnh (
too many SQL variables). Một lệnhinsert(...).values([...])nhiều dòng được manh.run tự chia nhỏ trong một transaction, nhưnginArray(col, ids)với hơn 100 id thì vẫn lỗi: lọc tập id lớn bằng join hoặc subquery. - Tối đa 32 tham số mỗi hàm SQL (
json_objectchứa được 16 cặp), 100 cột mỗi bảng, 100 KB mỗi câu lệnh. - Tối đa 8 MB mỗi dòng, chuỗi hoặc blob: file để ở kho file. Mẫu
LIKEtối đa 50 byte. - Dung lượng theo gói (100 MB / 1 GB / 5 GB, chỉ cảnh báo), trần cứng 10 GB. Chạm trần thì mọi lệnh ghi lỗi; bảng chỉ tăng (log, sự kiện) cần một cron xoá dòng cũ.
Cần biết
- Khoá ngoại và unique được thực thi. Bắt lỗi trong repository và gọi
fail(409, ...)với câu dễ hiểu (“Khách còn đơn hàng, không xoá được”). - Dữ liệu phụ nhỏ (cài đặt, bộ đếm) cũng để trong bảng: bảng
settingsmột dòng, hoặc bảngkv(khoá → JSON). - Mỗi app chỉ có một database, không có chế độ chia database theo khách (
app/tenant.tsđã bỏ,checkbáotenant.removed). Khách cần dữ liệu tách hẳn thì nhân bản app, mỗi khách một project. Nhiều công ty dùng chung một app thì thêm cộtorgIdvào từng bảng và lọc theo người đang đăng nhập. - Vùng đặt database chọn khi tạo project (mặc định
asia_pacificcho Việt Nam; cònnorth_america_east,north_america_west,europe_west,europe_east,oceania), cố định sau lần deploy đầu. app/db.tsdo manh.run sinh lại mỗi lần deploy, không sửa tay.
Bước tiếp theo
- Đăng nhập và phân quyền — biết ai đang gọi để lọc dữ liệu theo người dùng và vai trò.
- Làm một tính năng CRUD — bảng, repository, handler và trang cho một đối tượng.
- *.table.ts và listOf — mọi quy tắc của bảng và danh sách phân trang.