appflare-schema
Define and change the Appflare schema DSL (schema, table, v) and apply D1 migrations. Covers column builders (v.int, v.string, v.boolean, v.date, v.uuid, v.enum, v.array, v.object), modifiers (notNull
SKILL.mdskills/appflare-schema/SKILL.md
GitHubAppflare schema
Workflow
- Open the schema entry (
schemaDsl.entryinappflare.config.ts, usuallyschema.ts) - Edit tables inside the exported
schema({...}) - Run
bun appflare devfrom the backend package and fix any compiler error it prints - Run
bun appflare migrate --localand review the new SQL file indrizzle/ - Update the handlers and client code that use the changed fields
Template
import { schema, table, v } from "appflare";
export const schemas = schema({
projects: table({
id: v.uuid(), // text PK, crypto.randomUUID() on insert
name: v.string().notNull(),
slug: v.string().notNull().unique(),
status: v.enum(["active", "archived"]).notNull().default("active"),
tags: v.array(v.string()), // JSON text
settings: v.object({ color: v.string(), public: v.boolean() }),
createdAt: v.date().defaultNow(), // runtime default on insert
owner: v.one("users"), // ownerId (NOT NULL) → users.id
tasks: v.many("tasks"), // adds projectId to tasks
}),
tasks: table({
id: v.int().primaryKey({ autoIncrement: true }),
title: v.string().notNull(),
done: v.boolean().notNull().default(false),
dueAt: v.date(),
project: v.one("projects"), // projectId: matches v.many above
assignee: v.one("users", { nullable: true }), // assigneeId (nullable)
labels: v.manyToMany("labels"),
}),
labels: table({
id: v.int().primaryKey({ autoIncrement: true }),
name: v.string().notNull().unique(),
tasks: v.manyToMany("tasks"), // junction: labelsTasksLinks (labelId, taskId)
}),
accounts: table(
{
id: v.int().primaryKey({ autoIncrement: true }),
status: v.string().notNull().default("active"),
balanceMinor: v.int().notNull().default(0),
},
{
indexes: [{ columns: ["status", "balanceMinor"] }], // composite index
checks: [{ name: "accounts_balance_non_negative", sql: "balance_minor >= 0" }],
},
),
});
Several relations to the same table
messages: table({
sender: v.one("users", { relationName: "sender" }), // senderId
recipient: v.one("users", { relationName: "recipient", nullable: true }), // recipientId
}),
// on the users side (if you own that table):
sentMessages: v.many("messages", { relationName: "sender" }),
A v.many whose target has more than one matching v.one fails generation unless both sides share a relationName. The named v.many reuses the v.one's foreign key instead of inferring a new column.
Rules to apply
- Primary keys: use
v.uuid()for string ids orv.int().primaryKey({ autoIncrement: true })for numeric ids. - Nullability: plain columns are nullable and optional. Add
.notNull()to required fields. FKs fromv.oneandv.manyare NOT NULL unless{ nullable: true }. - FK names:
field: v.one("t")createsfieldId.source.rel: v.many("target")adds<singular source>Idto the target. Give the inversev.onethe same name (project↔projects.tasks), or pass the name explicitly (v.many("tasks", "parentProjectId")). - Many-to-many: declare
v.manyToManyon both tables with identical options. The junction holds links only. If the link needs data (a role, a timestamp), create an explicit join table with twov.onerelations. - Defaults:
.default(x)is a SQL default..defaultFn(fn),.defaultNow()andv.uuid()are runtime defaults applied on insert (not by rawctx.$db). Any column with a default reads back as non-null and rejects an explicitnull; add.nullable()if it really stores nulls. - Invariants: put rules that must always hold in
checks(or a trigger viamigrate:custom), because a batch can't abort on a condition. They surface asCheckConstraintError/TriggerAbortError→ HTTP 400. - Auth tables (
users,sessions,accounts,verifications) come from Better Auth. Reference them (v.one("users")) but never define them. - SQL naming is camelCase to snake_case automatically. Use
.sql("name")ortable(shape, { sqlName })only to match an existing database.
Gotchas
v.number()is an alias ofv.int()and creates an INTEGER column. There is no float column type.v.date()is stored as epoch milliseconds, and filters acceptDateor numbers..defaultNow()and.defaultFn()don't add a SQL default, so rows inserted with raw SQL (and rows written before the default existed) keepNULLeven though the type says otherwise.checks[].sqluses SQL column names (balance_minor), not field names.- Triggers, views and backfills go in an empty migration:
bun appflare migrate:custom --name add_guards. - Reciprocal
manyToManydeclarations with differentjunctionTableor field options fail generation. onDelete: "set null"requiresnullable: trueon the relation.migratereads the compiled schema, so always runbun appflare devfirst.- Pass only one of
--local,--remoteor--previewtomigrate. - Adding a Better Auth plugin changes auth tables. Regenerate and migrate afterwards.
References
- Read references/column-api.md when you need every
v.*builder, option or modifier, or the SQL and TypeScript mapping. - Read references/relations.md when configuring relation options (custom FK names, reference fields, junction names, FK actions, self-relations) or debugging a relation compile error.