@quickback-dev/cli 0.10.15 → 0.10.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (249) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +40 -2
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/docs/content.js +6 -6
  5. package/dist/docs/content.js.map +1 -1
  6. package/dist/index.js +1 -1
  7. package/dist/skill/SKILL.md +142 -1051
  8. package/dist/skill/agents/quickback-specialist/AGENT.md +36 -0
  9. package/dist/skill/docs/changelog.md +1192 -0
  10. package/dist/skill/docs/compiler/claude-code-skill.md +312 -0
  11. package/dist/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
  12. package/dist/skill/docs/compiler/cloud-compiler/cli.md +307 -0
  13. package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
  14. package/dist/skill/docs/compiler/cloud-compiler/index.md +65 -0
  15. package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
  16. package/dist/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
  17. package/dist/skill/docs/compiler/config/agents.md +144 -0
  18. package/dist/skill/docs/compiler/config/auth.md +109 -0
  19. package/dist/skill/docs/compiler/config/bindings.md +176 -0
  20. package/dist/skill/docs/compiler/config/domains.md +149 -0
  21. package/dist/skill/docs/compiler/config/index.md +419 -0
  22. package/dist/skill/docs/compiler/config/output.md +338 -0
  23. package/dist/skill/docs/compiler/config/providers.md +248 -0
  24. package/dist/skill/docs/compiler/config/security.md +255 -0
  25. package/dist/skill/docs/compiler/config/single-tenant.md +128 -0
  26. package/dist/skill/docs/compiler/config/variables.md +157 -0
  27. package/dist/skill/docs/compiler/definitions/access.md +445 -0
  28. package/dist/skill/docs/compiler/definitions/actions.md +884 -0
  29. package/dist/skill/docs/compiler/definitions/concepts.md +52 -0
  30. package/dist/skill/docs/compiler/definitions/feature.md +164 -0
  31. package/dist/skill/docs/compiler/definitions/firewall.md +285 -0
  32. package/dist/skill/docs/compiler/definitions/guards.md +241 -0
  33. package/dist/skill/docs/compiler/definitions/index.md +219 -0
  34. package/dist/skill/docs/compiler/definitions/masking.md +241 -0
  35. package/dist/skill/docs/compiler/definitions/read.md +220 -0
  36. package/dist/skill/docs/compiler/definitions/schema.md +697 -0
  37. package/dist/skill/docs/compiler/definitions/validation.md +35 -0
  38. package/dist/skill/docs/compiler/definitions/views.md +292 -0
  39. package/dist/skill/docs/compiler/getting-started/claude-code.md +126 -0
  40. package/dist/skill/docs/compiler/getting-started/full-example.md +431 -0
  41. package/dist/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
  42. package/dist/skill/docs/compiler/getting-started/index.md +192 -0
  43. package/dist/skill/docs/compiler/getting-started/patterns.md +225 -0
  44. package/dist/skill/docs/compiler/getting-started/template-blog.md +280 -0
  45. package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
  46. package/dist/skill/docs/compiler/getting-started/template-empty.md +112 -0
  47. package/dist/skill/docs/compiler/getting-started/templates.md +111 -0
  48. package/dist/skill/docs/compiler/index.md +85 -0
  49. package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
  50. package/dist/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
  51. package/dist/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
  52. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
  53. package/dist/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
  54. package/dist/skill/docs/compiler/targets/hono-api/index.md +37 -0
  55. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
  56. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
  57. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
  58. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
  59. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
  60. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
  61. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
  62. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
  63. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
  64. package/dist/skill/docs/compiler/targets/index.md +47 -0
  65. package/dist/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
  66. package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
  67. package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
  68. package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
  69. package/dist/skill/docs/compiler/troubleshooting.md +120 -0
  70. package/dist/skill/docs/index.md +77 -0
  71. package/dist/skill/docs/stack/account-ui/customization.md +378 -0
  72. package/dist/skill/docs/stack/account-ui/environment-variables.md +325 -0
  73. package/dist/skill/docs/stack/account-ui/features/admin.md +76 -0
  74. package/dist/skill/docs/stack/account-ui/features/api-keys.md +22 -0
  75. package/dist/skill/docs/stack/account-ui/features/avatars.md +37 -0
  76. package/dist/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
  77. package/dist/skill/docs/stack/account-ui/features/index.md +291 -0
  78. package/dist/skill/docs/stack/account-ui/features/organizations.md +29 -0
  79. package/dist/skill/docs/stack/account-ui/features/passkeys.md +31 -0
  80. package/dist/skill/docs/stack/account-ui/features/passwordless.md +28 -0
  81. package/dist/skill/docs/stack/account-ui/features/sessions.md +20 -0
  82. package/dist/skill/docs/stack/account-ui/hooks.md +209 -0
  83. package/dist/skill/docs/stack/account-ui/index.md +147 -0
  84. package/dist/skill/docs/stack/account-ui/library-usage.md +257 -0
  85. package/dist/skill/docs/stack/account-ui/standalone.md +149 -0
  86. package/dist/skill/docs/stack/account-ui/with-quickback.md +160 -0
  87. package/dist/skill/docs/stack/account-ui/worker.md +362 -0
  88. package/dist/skill/docs/stack/auth/api-keys.md +15 -0
  89. package/dist/skill/docs/stack/auth/device-auth.md +14 -0
  90. package/dist/skill/docs/stack/auth/index.md +64 -0
  91. package/dist/skill/docs/stack/auth/jwt-optimization.md +245 -0
  92. package/dist/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
  93. package/dist/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
  94. package/dist/skill/docs/stack/auth/plugins/index.md +228 -0
  95. package/dist/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
  96. package/dist/skill/docs/stack/auth/security.md +455 -0
  97. package/dist/skill/docs/stack/auth/using-auth.md +39 -0
  98. package/dist/skill/docs/stack/cms/actions.md +199 -0
  99. package/dist/skill/docs/stack/cms/components.md +479 -0
  100. package/dist/skill/docs/stack/cms/connecting.md +199 -0
  101. package/dist/skill/docs/stack/cms/dashboard.md +39 -0
  102. package/dist/skill/docs/stack/cms/index.md +158 -0
  103. package/dist/skill/docs/stack/cms/inline-editing.md +136 -0
  104. package/dist/skill/docs/stack/cms/pages.md +275 -0
  105. package/dist/skill/docs/stack/cms/record-layouts.md +151 -0
  106. package/dist/skill/docs/stack/cms/schema-format.md +437 -0
  107. package/dist/skill/docs/stack/cms/schema-registry.md +200 -0
  108. package/dist/skill/docs/stack/cms/security.md +203 -0
  109. package/dist/skill/docs/stack/cms/table-views.md +142 -0
  110. package/dist/skill/docs/stack/index.md +65 -0
  111. package/dist/skill/docs/stack/queues/handlers.md +317 -0
  112. package/dist/skill/docs/stack/queues/index.md +56 -0
  113. package/dist/skill/docs/stack/queues/using-queues.md +192 -0
  114. package/dist/skill/docs/stack/realtime/durable-objects.md +488 -0
  115. package/dist/skill/docs/stack/realtime/index.md +67 -0
  116. package/dist/skill/docs/stack/realtime/using-realtime.md +211 -0
  117. package/dist/skill/docs/stack/storage/index.md +17 -0
  118. package/dist/skill/docs/stack/storage/kv.md +204 -0
  119. package/dist/skill/docs/stack/storage/r2.md +232 -0
  120. package/dist/skill/docs/stack/storage/using-kv.md +70 -0
  121. package/dist/skill/docs/stack/storage/using-r2.md +55 -0
  122. package/dist/skill/docs/stack/vector/embeddings.md +554 -0
  123. package/dist/skill/docs/stack/vector/index.md +44 -0
  124. package/dist/skill/docs/stack/vector/using-embeddings.md +186 -0
  125. package/dist/skill/docs/stack/webhooks/inbound.md +186 -0
  126. package/dist/skill/docs/stack/webhooks/index.md +36 -0
  127. package/dist/skill/docs/stack/webhooks/outbound.md +281 -0
  128. package/package.json +1 -1
  129. package/src/skill/SKILL.md +142 -1051
  130. package/src/skill/agents/quickback-specialist/AGENT.md +36 -0
  131. package/src/skill/docs/changelog.md +1192 -0
  132. package/src/skill/docs/compiler/claude-code-skill.md +312 -0
  133. package/src/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
  134. package/src/skill/docs/compiler/cloud-compiler/cli.md +307 -0
  135. package/src/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
  136. package/src/skill/docs/compiler/cloud-compiler/index.md +65 -0
  137. package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
  138. package/src/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
  139. package/src/skill/docs/compiler/config/agents.md +144 -0
  140. package/src/skill/docs/compiler/config/auth.md +109 -0
  141. package/src/skill/docs/compiler/config/bindings.md +176 -0
  142. package/src/skill/docs/compiler/config/domains.md +149 -0
  143. package/src/skill/docs/compiler/config/index.md +419 -0
  144. package/src/skill/docs/compiler/config/output.md +338 -0
  145. package/src/skill/docs/compiler/config/providers.md +248 -0
  146. package/src/skill/docs/compiler/config/security.md +255 -0
  147. package/src/skill/docs/compiler/config/single-tenant.md +128 -0
  148. package/src/skill/docs/compiler/config/variables.md +157 -0
  149. package/src/skill/docs/compiler/definitions/access.md +445 -0
  150. package/src/skill/docs/compiler/definitions/actions.md +884 -0
  151. package/src/skill/docs/compiler/definitions/concepts.md +52 -0
  152. package/src/skill/docs/compiler/definitions/feature.md +164 -0
  153. package/src/skill/docs/compiler/definitions/firewall.md +285 -0
  154. package/src/skill/docs/compiler/definitions/guards.md +241 -0
  155. package/src/skill/docs/compiler/definitions/index.md +219 -0
  156. package/src/skill/docs/compiler/definitions/masking.md +241 -0
  157. package/src/skill/docs/compiler/definitions/read.md +220 -0
  158. package/src/skill/docs/compiler/definitions/schema.md +697 -0
  159. package/src/skill/docs/compiler/definitions/validation.md +35 -0
  160. package/src/skill/docs/compiler/definitions/views.md +292 -0
  161. package/src/skill/docs/compiler/getting-started/claude-code.md +126 -0
  162. package/src/skill/docs/compiler/getting-started/full-example.md +431 -0
  163. package/src/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
  164. package/src/skill/docs/compiler/getting-started/index.md +192 -0
  165. package/src/skill/docs/compiler/getting-started/patterns.md +225 -0
  166. package/src/skill/docs/compiler/getting-started/template-blog.md +280 -0
  167. package/src/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
  168. package/src/skill/docs/compiler/getting-started/template-empty.md +112 -0
  169. package/src/skill/docs/compiler/getting-started/templates.md +111 -0
  170. package/src/skill/docs/compiler/index.md +85 -0
  171. package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
  172. package/src/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
  173. package/src/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
  174. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
  175. package/src/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
  176. package/src/skill/docs/compiler/targets/hono-api/index.md +37 -0
  177. package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
  178. package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
  179. package/src/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
  180. package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
  181. package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
  182. package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
  183. package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
  184. package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
  185. package/src/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
  186. package/src/skill/docs/compiler/targets/index.md +47 -0
  187. package/src/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
  188. package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
  189. package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
  190. package/src/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
  191. package/src/skill/docs/compiler/troubleshooting.md +120 -0
  192. package/src/skill/docs/index.md +77 -0
  193. package/src/skill/docs/stack/account-ui/customization.md +378 -0
  194. package/src/skill/docs/stack/account-ui/environment-variables.md +325 -0
  195. package/src/skill/docs/stack/account-ui/features/admin.md +76 -0
  196. package/src/skill/docs/stack/account-ui/features/api-keys.md +22 -0
  197. package/src/skill/docs/stack/account-ui/features/avatars.md +37 -0
  198. package/src/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
  199. package/src/skill/docs/stack/account-ui/features/index.md +291 -0
  200. package/src/skill/docs/stack/account-ui/features/organizations.md +29 -0
  201. package/src/skill/docs/stack/account-ui/features/passkeys.md +31 -0
  202. package/src/skill/docs/stack/account-ui/features/passwordless.md +28 -0
  203. package/src/skill/docs/stack/account-ui/features/sessions.md +20 -0
  204. package/src/skill/docs/stack/account-ui/hooks.md +209 -0
  205. package/src/skill/docs/stack/account-ui/index.md +147 -0
  206. package/src/skill/docs/stack/account-ui/library-usage.md +257 -0
  207. package/src/skill/docs/stack/account-ui/standalone.md +149 -0
  208. package/src/skill/docs/stack/account-ui/with-quickback.md +160 -0
  209. package/src/skill/docs/stack/account-ui/worker.md +362 -0
  210. package/src/skill/docs/stack/auth/api-keys.md +15 -0
  211. package/src/skill/docs/stack/auth/device-auth.md +14 -0
  212. package/src/skill/docs/stack/auth/index.md +64 -0
  213. package/src/skill/docs/stack/auth/jwt-optimization.md +245 -0
  214. package/src/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
  215. package/src/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
  216. package/src/skill/docs/stack/auth/plugins/index.md +228 -0
  217. package/src/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
  218. package/src/skill/docs/stack/auth/security.md +455 -0
  219. package/src/skill/docs/stack/auth/using-auth.md +39 -0
  220. package/src/skill/docs/stack/cms/actions.md +199 -0
  221. package/src/skill/docs/stack/cms/components.md +479 -0
  222. package/src/skill/docs/stack/cms/connecting.md +199 -0
  223. package/src/skill/docs/stack/cms/dashboard.md +39 -0
  224. package/src/skill/docs/stack/cms/index.md +158 -0
  225. package/src/skill/docs/stack/cms/inline-editing.md +136 -0
  226. package/src/skill/docs/stack/cms/pages.md +275 -0
  227. package/src/skill/docs/stack/cms/record-layouts.md +151 -0
  228. package/src/skill/docs/stack/cms/schema-format.md +437 -0
  229. package/src/skill/docs/stack/cms/schema-registry.md +200 -0
  230. package/src/skill/docs/stack/cms/security.md +203 -0
  231. package/src/skill/docs/stack/cms/table-views.md +142 -0
  232. package/src/skill/docs/stack/index.md +65 -0
  233. package/src/skill/docs/stack/queues/handlers.md +317 -0
  234. package/src/skill/docs/stack/queues/index.md +56 -0
  235. package/src/skill/docs/stack/queues/using-queues.md +192 -0
  236. package/src/skill/docs/stack/realtime/durable-objects.md +488 -0
  237. package/src/skill/docs/stack/realtime/index.md +67 -0
  238. package/src/skill/docs/stack/realtime/using-realtime.md +211 -0
  239. package/src/skill/docs/stack/storage/index.md +17 -0
  240. package/src/skill/docs/stack/storage/kv.md +204 -0
  241. package/src/skill/docs/stack/storage/r2.md +232 -0
  242. package/src/skill/docs/stack/storage/using-kv.md +70 -0
  243. package/src/skill/docs/stack/storage/using-r2.md +55 -0
  244. package/src/skill/docs/stack/vector/embeddings.md +554 -0
  245. package/src/skill/docs/stack/vector/index.md +44 -0
  246. package/src/skill/docs/stack/vector/using-embeddings.md +186 -0
  247. package/src/skill/docs/stack/webhooks/inbound.md +186 -0
  248. package/src/skill/docs/stack/webhooks/index.md +36 -0
  249. package/src/skill/docs/stack/webhooks/outbound.md +281 -0
@@ -0,0 +1,697 @@
1
+ # Database Schema
2
+
3
+ Quickback supports three co-equal authoring patterns. All compile to the same generated runtime — the compiler dispatches per file, so every feature in a project may choose independently.
4
+
5
+ - **`feature()`** — single-export sugar for the `q` DSL. One import, one export, everything about the table and its security contract in one call. **Recommended default.** See [feature() — single-export sugar](/compiler/definitions/feature).
6
+ - **`q.table()` + `defineTable()`** — the two-export form. Same DSL, more explicit. Use when you want to reference the table identifier before the default export (e.g. from an action file).
7
+ - **Drizzle `sqliteTable()` / `pgTable()` + `defineTable()`** — interop with existing Drizzle code. Use when you're bringing an existing schema forward or want dialect-specific column options.
8
+
9
+ ## feature() — the one-call form (default)
10
+
11
+ ```typescript
12
+ // quickback/features/jobs/jobs.ts
13
+ import { feature, q } from '@quickback/compiler';
14
+
15
+ export default feature('jobs', {
16
+ columns: {
17
+ id: q.id(),
18
+ title: q.text().required(),
19
+ department: q.text().required(),
20
+ status: q.text().default('draft').required(), // "draft" | "open" | "closed"
21
+ salaryMin: q.int().optional(),
22
+ salaryMax: q.int().optional(),
23
+ organizationId: q.scope('organization'),
24
+ },
25
+ // firewall block omitted — q.scope('organization') triggers auto-derivation
26
+ // of [{ field: 'organizationId', equals: 'ctx.activeOrgId' }, { field: 'deletedAt', isNull: true }].
27
+ guards: {
28
+ createable: ["title", "department", "status", "salaryMin", "salaryMax"],
29
+ updatable: ["title", "department", "status"],
30
+ },
31
+ crud: {
32
+ create: { access: { roles: ["owner", "hiring-manager"] } },
33
+ update: { access: { roles: ["owner", "hiring-manager"] } },
34
+ delete: { access: { roles: ["owner", "hiring-manager"] } },
35
+ },
36
+ read: {
37
+ access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
38
+ },
39
+ });
40
+ ```
41
+
42
+ Type inference still works — `typeof import('./jobs').default.$infer` gives you the row type. In action files, `import jobs from './jobs'` gives you the same typed handle you'd get from `q.table()`, so `defineActions(jobs, { … })` accepts it unchanged.
43
+
44
+ ## q.table() + defineTable() — the two-export form
45
+
46
+ ```typescript
47
+ // quickback/features/jobs/jobs.ts
48
+ import { q, defineTable } from '@quickback/compiler';
49
+
50
+ export const jobs = q.table('jobs', {
51
+ id: q.id(),
52
+ title: q.text().required(),
53
+ department: q.text().required(),
54
+ status: q.text().default('draft').required(),
55
+ salaryMin: q.int().optional(),
56
+ salaryMax: q.int().optional(),
57
+ organizationId: q.scope('organization'),
58
+ });
59
+
60
+ export default defineTable(jobs, {
61
+ guards: { /* ... */ },
62
+ crud: { /* ... */ },
63
+ read: { /* ... */ },
64
+ });
65
+
66
+ export type Job = typeof jobs.$infer;
67
+ ```
68
+
69
+ Produces byte-identical output to the `feature()` form above — the compiler expands `feature()` to exactly this shape internally. Use whichever reads better for the file you're writing.
70
+
71
+ A few mechanics to know:
72
+
73
+ - **Column names** default to snake_case of the JS key — `organizationId` ↔ `organization_id`, `salaryMin` ↔ `salary_min`. Pass a positional argument to override: `q.text('custom_name')`.
74
+ - **`q.id()`** emits `text('id').primaryKey()` with a cuid2 app-layer default.
75
+ - **`.required()` / `.optional()`** control NOT NULL. Chain before or after `.default(x)`.
76
+ - **References:** `q.text().required().references(() => other.id, { onDelete: 'cascade' })`.
77
+ - **Indexes:** column-level `.index()` or table-level `indexes` / `unique` as a third arg to `q.table(name, cols, { indexes, unique })`. With `feature()`, pass `indexes` and `unique` as top-level keys alongside `columns` — the sugar forwards them into the same `q.table` opts.
78
+
79
+ ### Column Types
80
+
81
+ | Builder | Drizzle equivalent | Zod type |
82
+ |---------|---------------------|----------|
83
+ | `q.text()` | `text(...)` | `z.string()` |
84
+ | `q.url()` | `text(...)` | `z.string().url()` |
85
+ | `q.int()` | `integer(...)` | `z.number().int()` |
86
+ | `q.bool()` | `boolean(...)` | `z.boolean()` |
87
+ | `q.uuid()` | `uuid(...)` | `z.string().uuid()` |
88
+ | `q.timestamp()` | `timestamp(...)` (converted to SQLite `text` on sqlite targets) | `z.coerce.date()` |
89
+ | `q.json()` | `jsonb(...)` | `z.unknown()` (or the type you pass in) |
90
+ | `q.enum(['a','b'])` | `text(..., { enum: [...] })` | `z.enum([...])` |
91
+ | `q.id()` | `text('id').primaryKey()` | `z.string()` |
92
+ | `q.scope(kind)` | `text(...).notNull()` | `z.string()` |
93
+
94
+ `q.text()` and `q.url()` accept either a SQL-name string or an options object — `q.text({ sqlName: 'org_id', maxLength: 80 })`. `maxLength` adds `z.string().max(n)` at the validation edge; the SQL column stays `text` (D1 ignores `VARCHAR(n)` length anyway).
95
+
96
+ `q.url()` is `q.text()` plus `z.string().url()` at the validation edge, so `javascript:` / `data:` URIs and free-form strings are rejected before they ever land in storage or get rendered in the CMS.
97
+
98
+ `q.id()` emits a plain text primary key. Actual ID assignment at insert time is driven by the provider's `generateId` setting — prefixed UUIDs for D1, cuid for libsql/bun-sqlite, `crypto.randomUUID()` for supabase, etc. This keeps q's output decoupled from any specific ID library.
99
+
100
+ ### q.scope() — tenant scope columns
101
+
102
+ `q.scope(kind)` is the canonical way to declare a column that holds a tenant-scope value (org / owner / team). It compiles to `text(...).notNull()` like a regular required text column, plus metadata that the compiler reads to:
103
+
104
+ 1. **Auto-derive the firewall predicate** — `q.scope('organization')` produces `[{ field: 'organizationId', equals: 'ctx.activeOrgId' }]` so you can omit the explicit `firewall:` block. (If `deletedAt` is present — and it is whenever the resource uses soft delete, which is the default — the `isNull(deletedAt)` predicate is appended automatically.)
105
+ 2. **Reject the column from client input** — scope fields land in `GUARDS_CONFIG.systemManaged` alongside the audit fields, so `POST { organizationId: 'org_other' }` returns 400 even if guards aren't otherwise configured.
106
+ 3. **Auto-populate on create / upsert** — the value is taken from the request context, not the request body.
107
+
108
+ ```typescript
109
+ columns: {
110
+ organizationId: q.scope('organization'), // → ctx.activeOrgId
111
+ ownerId: q.scope('owner'), // → ctx.userId
112
+ teamId: q.scope('team'), // → ctx.activeTeamId
113
+ }
114
+ ```
115
+
116
+ Override the context source for non-default sources:
117
+
118
+ ```typescript
119
+ ownerId: q.scope('owner', { source: 'ctx.userId' }),
120
+ ```
121
+
122
+ `q.scope()` is preferred over `q.text().required()` for tenant columns. Auto-detection on column names (`organizationId`, `userId`, etc.) still works as a fallback for projects bringing forward Drizzle schemas, but the explicit `q.scope()` form locks in the semantics in the source.
123
+
124
+ ### Naming Convention
125
+
126
+ By default, `q` picks the SQL column name from the JS key using the target database's conventional casing:
127
+
128
+ - **Postgres family (Supabase, Neon, D1)** → `snake_case` (`organizationId` → `organization_id`)
129
+ - **SQLite family (bun-sqlite, better-sqlite3, libsql)** → `camelCase` (`organizationId` → `organizationId`)
130
+
131
+ You can override for any project by setting `namingConvention` on the database provider config:
132
+
133
+ ```ts
134
+ // quickback/quickback.config.ts
135
+ export default {
136
+ providers: {
137
+ database: {
138
+ name: 'bun-sqlite',
139
+ config: {
140
+ path: './data/app.db',
141
+ namingConvention: 'snake_case', // force snake_case everywhere
142
+ },
143
+ },
144
+ },
145
+ };
146
+ ```
147
+
148
+ For one-off overrides on a specific column, pass an explicit name as the positional argument:
149
+
150
+ ```ts
151
+ organizationId: q.scope('organization', { sqlName: 'org_id' }), // SQL name: 'org_id'
152
+ ```
153
+
154
+ ## Defining Tables with Drizzle
155
+
156
+ If you prefer Drizzle — or have an existing schema you're bringing forward — use `pgTable` / `sqliteTable` / `mysqlTable` directly:
157
+
158
+ | Target Database | Import From | Table Function |
159
+ |-----------------|-------------|----------------|
160
+ | Cloudflare D1, Turso, SQLite | `drizzle-orm/sqlite-core` | `sqliteTable` |
161
+ | Supabase, Neon, PostgreSQL | `drizzle-orm/pg-core` | `pgTable` |
162
+ | PlanetScale, MySQL | `drizzle-orm/mysql-core` | `mysqlTable` |
163
+
164
+ ```typescript
165
+ // quickback/features/jobs/jobs.ts
166
+ import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';
167
+ import { defineTable } from '@quickback/compiler';
168
+
169
+ export const jobs = sqliteTable('jobs', {
170
+ id: text('id').primaryKey(),
171
+ organizationId: text('organization_id').notNull(),
172
+ title: text('title').notNull(),
173
+ department: text('department').notNull(),
174
+ status: text('status').notNull(),
175
+ salaryMin: integer('salary_min'),
176
+ salaryMax: integer('salary_max'),
177
+ });
178
+
179
+ export default defineTable(jobs, {
180
+ firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
181
+ guards: {
182
+ createable: ["title", "department", "status", "salaryMin", "salaryMax"],
183
+ updatable: ["title", "department", "status"],
184
+ },
185
+ crud: { /* ... */ },
186
+ });
187
+
188
+ export type Job = typeof jobs.$inferSelect;
189
+ ```
190
+
191
+ When using Drizzle (rather than `q.scope()`), declare the firewall as a predicate array. Auto-detection still works on column names (`organizationId`, `ownerId`, `teamId`) so you can omit `firewall:` entirely if exactly one isolation column is present.
192
+
193
+ ### Choosing Between `q` and Drizzle
194
+
195
+ | Pick `q` when | Pick Drizzle when |
196
+ |---|---|
197
+ | Starting a new feature from scratch | You already have Drizzle schemas to bring forward |
198
+ | You want the same Zod across actions, forms, and routes | You need Drizzle-specific column options not yet in `q` (e.g., `decimal`, `varchar` with length, dialect-specific types) |
199
+ | You prefer concise, Zod-native syntax | You prefer the explicit Drizzle dialect import per target |
200
+
201
+ Features in the same project may mix freely — Quickback dispatches per feature.
202
+
203
+ ### Drizzle Column Types
204
+
205
+ Drizzle supports all standard SQL column types:
206
+
207
+ | Type | Drizzle Function | Example |
208
+ |------|------------------|---------|
209
+ | String | `text()`, `varchar()` | `text('name')` |
210
+ | Integer | `integer()`, `bigint()` | `integer('count')` |
211
+ | Boolean | `boolean()` | `boolean('is_active')` |
212
+ | Timestamp | `timestamp()` | `timestamp('created_at')` |
213
+ | JSON | `json()`, `jsonb()` | `jsonb('metadata')` |
214
+ | UUID | `uuid()` | `uuid('id')` |
215
+ | Decimal | `decimal()`, `numeric()` | `decimal('price', { precision: 10, scale: 2 })` |
216
+
217
+ ### Drizzle Column Modifiers
218
+
219
+ ```typescript
220
+ // Required field
221
+ name: text('name').notNull()
222
+
223
+ // Default value
224
+ isActive: boolean('is_active').default(true)
225
+
226
+ // Primary key
227
+ id: text('id').primaryKey()
228
+
229
+ // Unique constraint
230
+ email: text('email').unique()
231
+
232
+ // Default to current timestamp
233
+ createdAt: timestamp('created_at').defaultNow()
234
+ ```
235
+
236
+ ## File Organization
237
+
238
+ Organize your tables by feature. Each feature directory contains table files:
239
+
240
+ ```
241
+ quickback/
242
+ ├── quickback.config.ts
243
+ └── features/
244
+ ├── jobs/
245
+ │ ├── jobs.ts # Main table + config
246
+ │ ├── applications.ts # Related table + config
247
+ │ └── actions.ts # Custom actions
248
+ ├── candidates/
249
+ │ ├── candidates.ts # Table + config
250
+ │ └── candidate-notes.ts # Related table
251
+ └── organizations/
252
+ └── organizations.ts
253
+ ```
254
+
255
+ **Key points:**
256
+ - Tables with `export default defineTable(...)` get CRUD routes generated
257
+ - Tables without a default export are internal (no routes, used for joins/relations)
258
+ - Route paths are derived from filenames: `applications.ts` → `/api/v1/applications`
259
+
260
+ ### defineTable vs defineResource
261
+
262
+ - **`defineTable`** — The standard function for defining tables with CRUD routes
263
+ - **`defineResource`** — Deprecated. Still works but emits a warning during compilation. Use `defineTable` instead.
264
+
265
+ ```typescript
266
+ // Preferred:
267
+ export default defineTable(jobs, { /* config */ });
268
+ ```
269
+
270
+ ## 1 Resource = 1 Security Boundary
271
+
272
+ Each `defineTable()` call defines a complete, self-contained security boundary. The security config you write — firewall, access, guards, and masking — is compiled into a single resource file that wraps all CRUD routes for that table.
273
+
274
+ This is a deliberate design choice. Mixing two resources with different security rules in one configuration would create ambiguity about which firewall, access, or masking rules apply to which table. By keeping it 1:1, there's never any question.
275
+
276
+ | Scenario | What to do |
277
+ |----------|------------|
278
+ | Table needs its own API routes + security | Own file with `defineTable()` |
279
+ | Table is internal/supporting (no direct API) | Extra `.ts` file in the parent feature directory, no `defineTable()` |
280
+
281
+ A supporting table without `defineTable()` is useful when it's accessed internally — by action handlers, joins, or background jobs — but should never be directly exposed as its own API endpoint.
282
+
283
+ ## Internal Tables (No Routes)
284
+
285
+ For junction tables or internal data structures that shouldn't have API routes, simply omit the `defineTable` export. Add a `// @quickback-internal` marker so the compiler skips the "no defineTable found" warning:
286
+
287
+ ```typescript
288
+ // quickback/features/jobs/interview-scores.ts
289
+
290
+ // @quickback-internal — child table, no CRUD routes intentionally.
291
+ import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';
292
+
293
+ export const interviewScores = sqliteTable('interview_scores', {
294
+ applicationId: text('application_id').notNull(),
295
+ interviewerId: text('interviewer_id').notNull(),
296
+ score: integer('score'),
297
+ organizationId: text('organization_id').notNull(), // Scope junction tables for cascade soft-deletes
298
+ });
299
+
300
+ // No default export = no CRUD routes generated
301
+ ```
302
+
303
+ These internal tables still participate in the database schema and migrations — they just don't get API routes or security configuration. Without the `@quickback-internal` marker the compiler emits a warning per table, since the missing `defineTable` is more often a bug than a deliberate choice.
304
+
305
+ > **Always Include a Scope Column**
306
+ >
307
+ > Internal and junction tables should include `organizationId` (or your relevant scope column) even though they don't have their own firewall config. This ensures the scoped `db` in action handlers automatically filters them correctly, and cascade soft deletes work across org boundaries.
308
+
309
+
310
+ The compiler automatically injects the four **[audit fields](#audit-fields)** (`createdAt`/`createdBy`/`modifiedAt`/`modifiedBy`), the soft-delete pair (`deletedAt`/`deletedBy`, when soft delete is enabled), and **`organizationId`** into child/junction tables when the parent feature is org-scoped. This ensures cascade soft deletes and scoped queries work correctly without manual column definitions.
311
+
312
+ ## Audit Fields
313
+
314
+ Quickback adds four audit columns to **every table** (including child/junction tables without `defineTable`) — never declare them in your schemas:
315
+
316
+ | Field | Type | Description |
317
+ |-------|------|-------------|
318
+ | `createdAt` | timestamp | Set on insert |
319
+ | `createdBy` | text | Actor that performed the insert (`ctx.userId`) |
320
+ | `modifiedAt` | timestamp | Set on every insert and update |
321
+ | `modifiedBy` | text | Actor that performed the latest insert/update (`ctx.userId`) |
322
+
323
+ Audit fields are a separate concept from soft-delete (`deletedAt`/`deletedBy`) — they're always present, regardless of delete mode. See [Soft-Delete Fields](#soft-delete-fields) below.
324
+
325
+ Opt out of audit injection entirely with `compiler.features.auditFields: false` in `quickback.config.ts`. (You almost never want to.)
326
+
327
+ ### How auto-injection works (two layers)
328
+
329
+ "Auto-injection" covers two distinct steps. Conflating them is the most common source of confusion:
330
+
331
+ 1. **Schema injection (compile-time)** — the compiler adds the four columns to every Drizzle table. Idempotent: if you've authored a column with the same name yourself, the compiler leaves yours alone.
332
+ 2. **Runtime injection (per-write)** — a Proxy around the request-context `db` (`createAuditDb`, generated to `src/lib/audit-wrapper.ts`) intercepts `.insert(...).values(...)` and `.update(...).set(...)` and writes the audit columns from `ctx.userId` and the actual write moment.
333
+
334
+ The runtime layer **hard-stamps** every audit field on every write. Caller-supplied values for `createdAt`/`createdBy`/`modifiedAt`/`modifiedBy` are silently overwritten. This is intentional: the audit log can never be forged by a crafted request body or by a client echoing a row back into a PATCH.
335
+
336
+ ```ts
337
+ // In a custom action handler — caller cannot fake audit attribution
338
+ await db.insert(records).values({
339
+ id: createId(),
340
+ status: 'active',
341
+ createdBy: 'admin', // ← ignored; wrapper writes ctx.userId
342
+ modifiedAt: '1999-01-01', // ← ignored; wrapper writes "now"
343
+ });
344
+ ```
345
+
346
+ What the caller is responsible for: `id` (the framework doesn't mint ids for you) and the domain fields.
347
+
348
+ What the caller does *not* need to set: any of the four audit fields, ever.
349
+
350
+ ### Actors: who shows up in `createdBy` / `modifiedBy`
351
+
352
+ The wrapper writes whatever string is in `ctx.userId`. For user-driven requests this is the authenticated user's id — set by auth middleware before the handler runs. For non-user-driven entry points (inbound webhooks, cron, queue workers), you mint a synthetic actor id at the boundary so the audit log preserves provenance.
353
+
354
+ **Inherit before you mint.** If a real user's request triggers cascades, hooks, or enqueues background jobs, every downstream write should carry that user's id — not a synthetic one. The cascade is part of the user's action. Only mint when there is genuinely no upstream user.
355
+
356
+ When you do mint, use a single namespace and a stable convention:
357
+
358
+ | Boundary | Actor id |
359
+ |----------|----------|
360
+ | Inbound webhook | `system:webhook-<provider>` (e.g. `system:webhook-stripe`) |
361
+ | Scheduled / cron | `system:cron-<job>` (e.g. `system:cron-cleanup-stale`) |
362
+ | Queue worker | `system:queue-<queue>` (e.g. `system:queue-embeddings-retry`) |
363
+ | Quickback platform-internal write with no user upstream | `system:quickback` |
364
+ | Out-of-band operator script | `system:script-<name>` |
365
+
366
+ The `system:` prefix marks "not a real user" — readable by anyone joining the audit columns to `users`, and cheap to filter on. Don't use `tenant:admin` or `quickback:admin`: those imply a human role nobody is actually playing. The tenant context is already on the row (in `organizationId`); the actor id is purely about *source*.
367
+
368
+ ### Failure mode: missing `ctx.userId`
369
+
370
+ If a write reaches the wrapper without a `ctx.userId`, the wrapper throws:
371
+
372
+ ```
373
+ audit-wrapper: insert reached without ctx.userId.
374
+ If this is an intentional system-side write, use the unwrapped db directly.
375
+ ```
376
+
377
+ Two paths to fix it, depending on intent:
378
+
379
+ - **Mint a synthetic actor** (preferred — preserves attribution) — populate `ctx.userId` with one of the conventions above before calling into your handler.
380
+ - **Bypass the wrapper entirely** — use the unwrapped `createDb` instead of the request-context `db`. Use this only for migrations, schema repair, or backfill scripts where you genuinely don't want any audit attribution. The audit columns will fall back to DB defaults (`createdAt`/`modifiedAt` populate from `defaultNow()`; `createdBy`/`modifiedBy` end up `NULL`).
381
+
382
+ ### Disabling Audit Fields
383
+
384
+ To disable automatic audit fields for your project:
385
+
386
+ ```typescript
387
+ // quickback.config.ts
388
+ export default defineConfig({
389
+ // ...
390
+ compiler: {
391
+ features: {
392
+ auditFields: false, // Disable for entire project
393
+ }
394
+ }
395
+ });
396
+ ```
397
+
398
+ This turns off both layers — schema injection and the runtime wrapper.
399
+
400
+ ## Soft-Delete Fields
401
+
402
+ `deletedAt` and `deletedBy` are **not** audit fields. They're a separate, per-table mechanism for soft delete:
403
+
404
+ | Field | Type | Description |
405
+ |-------|------|-------------|
406
+ | `deletedAt` | timestamp | Set when the record is soft-deleted |
407
+ | `deletedBy` | text | Actor that performed the soft delete (`ctx.userId`) |
408
+
409
+ The compiler injects them only when the resource uses soft delete — i.e. when neither `crud.delete.mode` nor `crud.batchDelete.mode` is explicitly `'hard'`. Soft is the default, so most tables get the columns. Tables with both delete paths set to `'hard'` skip them entirely, which also drops the `isNull(deletedAt)` predicate from the firewall WHERE clause.
410
+
411
+ ```typescript
412
+ // soft delete (default) — table gets deletedAt + deletedBy
413
+ crud: { delete: {} }
414
+
415
+ // hard delete — no deletedAt/deletedBy columns, no soft-delete predicate
416
+ crud: { delete: { mode: 'hard' }, batchDelete: { mode: 'hard' } }
417
+ ```
418
+
419
+ ### Caller contract
420
+
421
+ In custom-action handlers, **passing `deletedAt` in `.set({})` is the signal** that this update is a soft delete. Any value works — the wrapper detects the field and overwrites both `deletedAt` and `deletedBy` with `now` and `ctx.userId`:
422
+
423
+ ```ts
424
+ await db.update(records)
425
+ .set({ deletedAt: new Date() }) // signal — value is overwritten
426
+ .where(eq(records.id, id));
427
+ ```
428
+
429
+ You don't set `deletedBy` yourself; the wrapper pairs it with the `deletedAt` signal.
430
+
431
+ ### Protected system fields
432
+
433
+ The audit and soft-delete columns are always protected from client input, even with `guards: false`:
434
+
435
+ - `id` (when `generateId` is not `false`)
436
+ - `createdAt`, `createdBy` *(audit — always present)*
437
+ - `modifiedAt`, `modifiedBy` *(audit — always present)*
438
+ - `deletedAt`, `deletedBy` *(soft-delete — present when delete mode allows soft)*
439
+
440
+ Protection is enforced by the runtime wrapper — even if a request body passes one of these, it gets overwritten before the SQL is built.
441
+
442
+ ## Auto-Indexes
443
+
444
+ The compiler injects performance-critical indexes you'd otherwise have to author by hand. The pass runs after audit-field injection (so `deletedAt` is present) and is idempotent — if you already declared a matching index it's left alone.
445
+
446
+ | Trigger | Index | Why |
447
+ |---------|-------|-----|
448
+ | Tenant column (`organizationId` / `organisationId` / `userId`) + `deletedAt` | Composite `(<isolation_col>, deletedAt)` | Every list query filters by isolation AND `deletedAt IS NULL` — a composite index lets D1/SQLite prune both predicates in one btree walk. |
449
+ | Any FK column (`.references(() => other.id)`) | Single-column `(<fk_col>)` | SQLite/D1 don't auto-index FK columns, and the generated FK existence checks read by id on the parent. |
450
+ | Any column that appears in a view's `read.query.sortable` allowlist (or `defaultSort`) | Single-column `(<col>)` | Sort scans go through an index instead of a full-table scan. |
451
+
452
+ Indexes are emitted into the table's Drizzle extras callback (`(t) => ({ ... })`) and named `<table>_<col>_idx` (or `<table>_<col1>_<col2>_idx` for the composite). The `index` import is added to your schema's `drizzle-orm/<dialect>-core` import line if it isn't already there.
453
+
454
+ You can opt out of any auto-injected index by declaring your own with the same name or column set — the injector treats both as already-present and skips.
455
+
456
+ ## Ownership Fields
457
+
458
+ For the firewall to work, declare a tenant-scope column. With `q.scope()` (recommended), the compiler auto-derives the firewall predicate, marks the column as system-managed, and auto-populates it on create:
459
+
460
+ ```typescript
461
+ // q DSL (recommended)
462
+ organizationId: q.scope('organization') // → ctx.activeOrgId
463
+ ownerId: q.scope('owner') // → ctx.userId
464
+ teamId: q.scope('team') // → ctx.activeTeamId
465
+ ```
466
+
467
+ When using Drizzle directly, declare a regular column. Auto-detection picks it up by name; `q.scope()` semantics (systemManaged, auto-populate) still apply because they're keyed off the firewall predicate, not the column DSL:
468
+
469
+ ```typescript
470
+ // Drizzle interop
471
+ organizationId: text('organization_id').notNull()
472
+ ownerId: text('owner_id').notNull()
473
+ teamId: text('team_id').notNull()
474
+ ```
475
+
476
+ ## Display Column
477
+
478
+ When a table has foreign key columns (e.g., `departmentId` referencing `departments`), Quickback can automatically resolve the human-readable label in GET and LIST responses. This eliminates the need for frontend lookup calls.
479
+
480
+ ### Auto-Detection
481
+
482
+ Quickback auto-detects the display column by checking for common column names in this order:
483
+
484
+ `name` → `title` → `label` → `headline` → `subject` → `code` → `displayName` → `fullName` → `description`
485
+
486
+ If your `departments` table has a `name` column, it's automatically used as the display column. No config needed.
487
+
488
+ ### Explicit Override
489
+
490
+ Override the auto-detected column with `displayColumn`:
491
+
492
+ ```typescript
493
+ export default defineTable(interviewStages, {
494
+ displayColumn: 'label', // Use 'label' instead of auto-detected 'name'
495
+ read: { access: { roles: ["hiring-manager", "recruiter"] } },
496
+ });
497
+ ```
498
+
499
+ ### Default Sort
500
+
501
+ Set a default sort order for the CMS table list view with `defaultSort`:
502
+
503
+ ```typescript
504
+ export default defineTable(podcastEpisodes, {
505
+ defaultSort: { field: "createdAt", order: "desc" },
506
+ firewall: [{ exception: true }],
507
+ read: { access: { roles: ["PUBLIC"] } },
508
+ });
509
+ ```
510
+
511
+ The CMS applies this sort when the table first loads. Users can still click column headers to change the sort order.
512
+
513
+ ### How Labels Appear in Responses
514
+
515
+ For any FK column ending in `Id`, the API adds a `_label` field with the resolved display value:
516
+
517
+ ```json
518
+ {
519
+ "id": "job_abc",
520
+ "title": "Senior Engineer",
521
+ "departmentId": "dept_xyz",
522
+ "department_label": "Engineering",
523
+ "locationId": "loc_123",
524
+ "location_label": "San Francisco"
525
+ }
526
+ ```
527
+
528
+ The pattern is `{columnWithoutId}_label`. The frontend can find all labels with:
529
+
530
+ ```typescript
531
+ Object.keys(record).filter(k => k.endsWith('_label'))
532
+ ```
533
+
534
+ Label resolution works within the same feature (tables in the same feature directory). System columns (`organizationId`, `createdBy`, `modifiedBy`) are never resolved.
535
+
536
+ For LIST endpoints, labels are batch-resolved efficiently — one query per FK column, not per record.
537
+
538
+ ## References
539
+
540
+ When your FK columns don't match the target table name by convention (e.g., `vendorId` actually points to the `contact` table), declare explicit references so the CMS and schema registry know the correct target:
541
+
542
+ ```typescript
543
+ export default defineTable(applications, {
544
+ references: {
545
+ candidateId: "candidate",
546
+ jobId: "job",
547
+ referredById: "candidate",
548
+ },
549
+ // ... firewall, guards, crud
550
+ });
551
+ ```
552
+
553
+ Each key is a column name ending in `Id`, and the value is the camelCase table name it references. These mappings flow into the schema registry as `fkTarget` on each column, enabling the CMS to render typeahead/lookup inputs that search the correct table.
554
+
555
+ Convention-based matching (strip `Id` suffix, look for a matching table) still works for simple cases like `projectId` → `project`. Use `references` only for columns where the convention doesn't match.
556
+
557
+ ## Input Hints
558
+
559
+ Control how the CMS renders form inputs for specific columns. By default the CMS infers input types from the column's SQL type — `inputHints` lets you override that:
560
+
561
+ ```typescript
562
+ export default defineTable(jobs, {
563
+ inputHints: {
564
+ status: "select",
565
+ department: "select",
566
+ salaryMin: "currency",
567
+ salaryMax: "currency",
568
+ description: "richtext",
569
+ },
570
+ // ... firewall, guards, crud
571
+ });
572
+ ```
573
+
574
+ ### Available Hint Values
575
+
576
+ | Hint | Renders As |
577
+ |------|-----------|
578
+ | `richtext` | Rich text editor (tiptap) — bold, italic, headings, lists, links. Stores HTML. Lazy-loaded in edit mode, rendered as formatted HTML in view mode. |
579
+ | `select` | Dropdown select (single value) |
580
+ | `multi-select` | Multi-value select |
581
+ | `radio` | Radio button group |
582
+ | `checkbox` | Checkbox toggle |
583
+ | `textarea` | Multi-line text input |
584
+ | `lookup` | FK typeahead search |
585
+ | `hidden` | Hidden from forms |
586
+ | `color` | Color picker |
587
+ | `date` | Date picker |
588
+ | `datetime` | Date + time picker |
589
+ | `time` | Time picker |
590
+ | `currency` | Currency input with formatting |
591
+
592
+ Input hints are emitted in the schema registry as `inputHints` on the table metadata, and the CMS reads them to render the appropriate form controls.
593
+
594
+ ### Rich Text Example
595
+
596
+ For fields that contain HTML content (e.g., blog posts, descriptions from RSS feeds), use `"richtext"`:
597
+
598
+ ```typescript
599
+ export default defineTable(podcastEpisodes, {
600
+ inputHints: { description: "richtext" },
601
+ // ...
602
+ });
603
+ ```
604
+
605
+ The CMS will:
606
+ - **View mode**: Render the HTML with proper formatting (headings, lists, links, etc.)
607
+ - **Edit mode**: Load a tiptap rich text editor with a toolbar (bold, italic, H2, H3, bullet/ordered lists, links, code, undo/redo)
608
+ - **Storage**: HTML strings — no format conversion needed, compatible with external HTML content
609
+
610
+ ## Relations (Optional)
611
+
612
+ Drizzle supports defining relations for type-safe joins:
613
+
614
+ ```typescript
615
+ import { relations } from 'drizzle-orm';
616
+ import { organizations } from '../organizations/organizations';
617
+ import { applications } from './applications';
618
+
619
+ export const jobsRelations = relations(jobs, ({ one, many }) => ({
620
+ organization: one(organizations, {
621
+ fields: [jobs.organizationId],
622
+ references: [organizations.id],
623
+ }),
624
+ applications: many(applications),
625
+ }));
626
+ ```
627
+
628
+ ## Database Configuration
629
+
630
+ Configure database options in your Quickback config:
631
+
632
+ ```typescript
633
+ // quickback.config.ts
634
+ export default defineConfig({
635
+ name: 'my-app',
636
+ providers: {
637
+ database: defineDatabase('cloudflare-d1', {
638
+ generateId: 'prefixed', // 'uuid' | 'cuid' | 'nanoid' | 'short' | 'prefixed' | 'serial' | false
639
+ namingConvention: 'snake_case', // 'camelCase' | 'snake_case'
640
+ usePlurals: false, // Auth table names: 'users' vs 'user'
641
+ }),
642
+ },
643
+ compiler: {
644
+ features: {
645
+ auditFields: true, // Auto-manage audit timestamps
646
+ }
647
+ }
648
+ });
649
+ ```
650
+
651
+ ## Choosing Your Dialect
652
+
653
+ Use the Drizzle dialect that matches your database provider:
654
+
655
+ ### SQLite (D1, Turso, better-sqlite3)
656
+
657
+ ```typescript
658
+ import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';
659
+
660
+ export const jobs = sqliteTable('jobs', {
661
+ id: text('id').primaryKey(),
662
+ title: text('title').notNull(),
663
+ metadata: text('metadata', { mode: 'json' }), // JSON stored as text
664
+ isOpen: integer('is_open', { mode: 'boolean' }).default(false),
665
+ organizationId: text('organization_id').notNull(),
666
+ });
667
+ ```
668
+
669
+ ### PostgreSQL (Supabase, Neon)
670
+
671
+ ```typescript
672
+ import { pgTable, text, serial, jsonb, boolean } from 'drizzle-orm/pg-core';
673
+
674
+ export const jobs = pgTable('jobs', {
675
+ id: serial('id').primaryKey(),
676
+ title: text('title').notNull(),
677
+ metadata: jsonb('metadata'), // Native JSONB
678
+ isOpen: boolean('is_open').default(false),
679
+ organizationId: text('organization_id').notNull(),
680
+ });
681
+ ```
682
+
683
+ ### Key Differences
684
+
685
+ | Feature | SQLite | PostgreSQL |
686
+ |---------|--------|------------|
687
+ | Boolean | `integer({ mode: 'boolean' })` | `boolean()` |
688
+ | JSON | `text({ mode: 'json' })` | `jsonb()` or `json()` |
689
+ | Auto-increment | `integer().primaryKey()` | `serial()` |
690
+ | UUID | `text()` | `uuid()` |
691
+
692
+ ## Next Steps
693
+
694
+ - [Configure the firewall](/compiler/definitions/firewall) for data isolation
695
+ - [Set up access control](/compiler/definitions/access) for CRUD operations
696
+ - [Define guards](/compiler/definitions/guards) for field modification rules
697
+ - [Add custom actions](/compiler/definitions/actions) for business logic