Database
≈ 10 min · you will have an orders table with the right indexes and a repository that returns a paged list with search and filters.
Each app has its own SQLite database. You declare tables in .table.ts files (for example orders.table.ts in a building-supplies app) and query them with Drizzle in repository.ts. manh.run updates the schema on every deploy.
The database sits next to the app’s code on manh.run’s infrastructure, so queries run in place with no network hop. There is no connection to configure, just import { db } from "app/db".
Tables
One file per resource, app/<resource>/<resource>.table.ts, in plain Drizzle. Import table builders from app/db, not from 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), // the list's sort column
index("orders_status_idx").on(t.status), // a filter column
]);SQLite has no boolean type; use integer with 0 / 1. Index every column a list sorts by: requests to one app run one at a time, so a list page that sorts the whole table slows down the whole app. Without the index, check warns perf.order-unindexed.
The schema changes on deploy
On every deploy, manh.run reads the .table.ts files and updates the database. It only adds, never removes: new tables are created, new columns added, indexes and constraints (.unique(), .references(...), index()) built. Columns and tables are never dropped or retyped automatically.
- On a table that already has rows, a new
.notNull()column without.default()is added as nullable, and the deploy notes say so. Give new required columns a default. - To rename a column: add the new one, copy the data with
db_exec, switch the code, then drop the old one.
Queries in the repository
Every database call lives in app/<resource>/repository.ts. A single-table list uses listOf, which returns { data, total } with paging, search, filters and sorting.
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 on these columns
filters: { status: orders.status }, // query key → column
sort: { createdAt: orders.createdAt }, // only these columns can be sorted
});
export async function setStatus(id: number, status: string) {
const [row] = await db.update(orders).set({ status }).where(eq(orders.id, id)).returning();
return row;
}The handler declares its query with listSchema(...) (pageSize at most 100) and its body with schemaOf(orders).insert.pick({...}), both from app/db.
Requests run one at a time
Each app handles requests one after another. A read-then-write (check stock, then decrement) can’t be interleaved with another request, so you don’t need a transaction to avoid races.
The exception: while you await an outside call (fetch, manh/email, manh/openai), other requests may run. So write data first, then send the email.
Transactions
Don’t use db.transaction(async …): with an async callback, statements after the first await run outside the transaction and errors don’t roll back (code.no-async-transaction).
- Default: do every read and every check before the first write.
- Several writes that must succeed together: a synchronous callback, each statement ending in
.run()/.get(), noawait. An error thrown inside rolls back.
Hard limits
Going over these makes the statement fail with 500; there is no setting to raise them:
- At most 100 bound values per statement (
too many SQL variables). A multi-rowinsert(...).values([...])is split for you by manh.run inside one transaction, butinArray(col, ids)with more than 100 ids still fails: filter large id sets with a join or subquery. - At most 32 arguments per SQL function (
json_objectholds 16 pairs), 100 columns per table, 100 KB per statement. - At most 8 MB per row, string or blob: keep files in file storage.
LIKEpatterns up to 50 bytes. - Size by plan (100 MB / 1 GB / 5 GB, warning only), hard ceiling 10 GB. At the ceiling every write fails; tables that only grow (logs, events) need a cron job that deletes old rows.
Good to know
- Foreign keys and unique constraints are enforced. Catch the error in the repository and call
fail(409, ...)with a clear sentence (“This customer still has orders”). - Small side data (settings, counters) lives in a table too: a one-row
settingstable, or akvtable (key → JSON). - Each app has exactly one database; there is no per-customer database mode (
app/tenant.tswas removed,checkreportstenant.removed). A customer whose data must be fully separate gets a clone of the app, one project each. Several companies in one app: add anorgIdcolumn to each table and filter by the signed-in user. - The database region is picked when the project is created (default
asia_pacificfor Vietnam; alsonorth_america_east,north_america_west,europe_west,europe_east,oceania) and is fixed after the first deploy. - manh.run regenerates
app/db.tson every deploy; don’t edit it.
Next steps
- Sign-in and permissions — know who is calling so you can filter data by user and role.
- Build a CRUD feature — table, repository, handlers and page for one object.
- *.table.ts and listOf — every rule for tables and paged lists.