@quickback-dev/cli 0.10.16 → 0.11.0
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.
- package/dist/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +40 -2
- package/dist/commands/compile.js.map +1 -1
- package/dist/docs/content.d.ts.map +1 -1
- package/dist/docs/content.js +15 -10
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/skill/SKILL.md +142 -1051
- package/dist/skill/agents/quickback-specialist/AGENT.md +36 -0
- package/dist/skill/docs/changelog.md +1225 -0
- package/dist/skill/docs/compiler/claude-code-skill.md +312 -0
- package/dist/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
- package/dist/skill/docs/compiler/cloud-compiler/cli.md +307 -0
- package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
- package/dist/skill/docs/compiler/cloud-compiler/index.md +65 -0
- package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
- package/dist/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
- package/dist/skill/docs/compiler/config/agents.md +144 -0
- package/dist/skill/docs/compiler/config/auth.md +109 -0
- package/dist/skill/docs/compiler/config/bindings.md +176 -0
- package/dist/skill/docs/compiler/config/domains.md +149 -0
- package/dist/skill/docs/compiler/config/index.md +419 -0
- package/dist/skill/docs/compiler/config/output.md +338 -0
- package/dist/skill/docs/compiler/config/providers.md +248 -0
- package/dist/skill/docs/compiler/config/security.md +255 -0
- package/dist/skill/docs/compiler/config/single-tenant.md +128 -0
- package/dist/skill/docs/compiler/config/variables.md +157 -0
- package/dist/skill/docs/compiler/definitions/access.md +445 -0
- package/dist/skill/docs/compiler/definitions/actions.md +884 -0
- package/dist/skill/docs/compiler/definitions/concepts.md +52 -0
- package/dist/skill/docs/compiler/definitions/feature.md +164 -0
- package/dist/skill/docs/compiler/definitions/firewall.md +285 -0
- package/dist/skill/docs/compiler/definitions/guards.md +241 -0
- package/dist/skill/docs/compiler/definitions/index.md +219 -0
- package/dist/skill/docs/compiler/definitions/masking.md +241 -0
- package/dist/skill/docs/compiler/definitions/read.md +220 -0
- package/dist/skill/docs/compiler/definitions/schema.md +697 -0
- package/dist/skill/docs/compiler/definitions/validation.md +35 -0
- package/dist/skill/docs/compiler/definitions/views.md +292 -0
- package/dist/skill/docs/compiler/getting-started/claude-code.md +126 -0
- package/dist/skill/docs/compiler/getting-started/full-example.md +431 -0
- package/dist/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
- package/dist/skill/docs/compiler/getting-started/index.md +192 -0
- package/dist/skill/docs/compiler/getting-started/patterns.md +225 -0
- package/dist/skill/docs/compiler/getting-started/template-blog.md +280 -0
- package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
- package/dist/skill/docs/compiler/getting-started/template-empty.md +112 -0
- package/dist/skill/docs/compiler/getting-started/templates.md +111 -0
- package/dist/skill/docs/compiler/index.md +85 -0
- package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
- package/dist/skill/docs/compiler/targets/hono-api/index.md +37 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
- package/dist/skill/docs/compiler/targets/index.md +47 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
- package/dist/skill/docs/compiler/troubleshooting.md +120 -0
- package/dist/skill/docs/index.md +77 -0
- package/dist/skill/docs/stack/account-ui/customization.md +378 -0
- package/dist/skill/docs/stack/account-ui/environment-variables.md +325 -0
- package/dist/skill/docs/stack/account-ui/features/admin.md +76 -0
- package/dist/skill/docs/stack/account-ui/features/api-keys.md +22 -0
- package/dist/skill/docs/stack/account-ui/features/avatars.md +37 -0
- package/dist/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
- package/dist/skill/docs/stack/account-ui/features/index.md +291 -0
- package/dist/skill/docs/stack/account-ui/features/organizations.md +29 -0
- package/dist/skill/docs/stack/account-ui/features/passkeys.md +31 -0
- package/dist/skill/docs/stack/account-ui/features/passwordless.md +28 -0
- package/dist/skill/docs/stack/account-ui/features/sessions.md +20 -0
- package/dist/skill/docs/stack/account-ui/hooks.md +209 -0
- package/dist/skill/docs/stack/account-ui/index.md +147 -0
- package/dist/skill/docs/stack/account-ui/library-usage.md +257 -0
- package/dist/skill/docs/stack/account-ui/standalone.md +149 -0
- package/dist/skill/docs/stack/account-ui/with-quickback.md +160 -0
- package/dist/skill/docs/stack/account-ui/worker.md +362 -0
- package/dist/skill/docs/stack/auth/api-keys.md +15 -0
- package/dist/skill/docs/stack/auth/device-auth.md +14 -0
- package/dist/skill/docs/stack/auth/index.md +64 -0
- package/dist/skill/docs/stack/auth/jwt-optimization.md +245 -0
- package/dist/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
- package/dist/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
- package/dist/skill/docs/stack/auth/plugins/index.md +340 -0
- package/dist/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
- package/dist/skill/docs/stack/auth/security.md +455 -0
- package/dist/skill/docs/stack/auth/using-auth.md +39 -0
- package/dist/skill/docs/stack/cms/actions.md +199 -0
- package/dist/skill/docs/stack/cms/components.md +479 -0
- package/dist/skill/docs/stack/cms/connecting.md +199 -0
- package/dist/skill/docs/stack/cms/dashboard.md +39 -0
- package/dist/skill/docs/stack/cms/index.md +158 -0
- package/dist/skill/docs/stack/cms/inline-editing.md +136 -0
- package/dist/skill/docs/stack/cms/pages.md +275 -0
- package/dist/skill/docs/stack/cms/record-layouts.md +151 -0
- package/dist/skill/docs/stack/cms/schema-format.md +437 -0
- package/dist/skill/docs/stack/cms/schema-registry.md +200 -0
- package/dist/skill/docs/stack/cms/security.md +203 -0
- package/dist/skill/docs/stack/cms/table-views.md +142 -0
- package/dist/skill/docs/stack/index.md +65 -0
- package/dist/skill/docs/stack/queues/handlers.md +317 -0
- package/dist/skill/docs/stack/queues/index.md +56 -0
- package/dist/skill/docs/stack/queues/using-queues.md +192 -0
- package/dist/skill/docs/stack/realtime/durable-objects.md +488 -0
- package/dist/skill/docs/stack/realtime/index.md +73 -0
- package/dist/skill/docs/stack/realtime/partyserver-rooms.md +146 -0
- package/dist/skill/docs/stack/realtime/using-realtime.md +211 -0
- package/dist/skill/docs/stack/storage/index.md +17 -0
- package/dist/skill/docs/stack/storage/kv.md +204 -0
- package/dist/skill/docs/stack/storage/r2.md +232 -0
- package/dist/skill/docs/stack/storage/using-kv.md +70 -0
- package/dist/skill/docs/stack/storage/using-r2.md +55 -0
- package/dist/skill/docs/stack/vector/embeddings.md +554 -0
- package/dist/skill/docs/stack/vector/index.md +44 -0
- package/dist/skill/docs/stack/vector/using-embeddings.md +186 -0
- package/dist/skill/docs/stack/webhooks/inbound.md +186 -0
- package/dist/skill/docs/stack/webhooks/index.md +36 -0
- package/dist/skill/docs/stack/webhooks/outbound.md +281 -0
- package/package.json +1 -1
- package/src/skill/SKILL.md +142 -1051
- package/src/skill/agents/quickback-specialist/AGENT.md +36 -0
- package/src/skill/docs/changelog.md +1225 -0
- package/src/skill/docs/compiler/claude-code-skill.md +312 -0
- package/src/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
- package/src/skill/docs/compiler/cloud-compiler/cli.md +307 -0
- package/src/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
- package/src/skill/docs/compiler/cloud-compiler/index.md +65 -0
- package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
- package/src/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
- package/src/skill/docs/compiler/config/agents.md +144 -0
- package/src/skill/docs/compiler/config/auth.md +109 -0
- package/src/skill/docs/compiler/config/bindings.md +176 -0
- package/src/skill/docs/compiler/config/domains.md +149 -0
- package/src/skill/docs/compiler/config/index.md +419 -0
- package/src/skill/docs/compiler/config/output.md +338 -0
- package/src/skill/docs/compiler/config/providers.md +248 -0
- package/src/skill/docs/compiler/config/security.md +255 -0
- package/src/skill/docs/compiler/config/single-tenant.md +128 -0
- package/src/skill/docs/compiler/config/variables.md +157 -0
- package/src/skill/docs/compiler/definitions/access.md +445 -0
- package/src/skill/docs/compiler/definitions/actions.md +884 -0
- package/src/skill/docs/compiler/definitions/concepts.md +52 -0
- package/src/skill/docs/compiler/definitions/feature.md +164 -0
- package/src/skill/docs/compiler/definitions/firewall.md +285 -0
- package/src/skill/docs/compiler/definitions/guards.md +241 -0
- package/src/skill/docs/compiler/definitions/index.md +219 -0
- package/src/skill/docs/compiler/definitions/masking.md +241 -0
- package/src/skill/docs/compiler/definitions/read.md +220 -0
- package/src/skill/docs/compiler/definitions/schema.md +697 -0
- package/src/skill/docs/compiler/definitions/validation.md +35 -0
- package/src/skill/docs/compiler/definitions/views.md +292 -0
- package/src/skill/docs/compiler/getting-started/claude-code.md +126 -0
- package/src/skill/docs/compiler/getting-started/full-example.md +431 -0
- package/src/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
- package/src/skill/docs/compiler/getting-started/index.md +192 -0
- package/src/skill/docs/compiler/getting-started/patterns.md +225 -0
- package/src/skill/docs/compiler/getting-started/template-blog.md +280 -0
- package/src/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
- package/src/skill/docs/compiler/getting-started/template-empty.md +112 -0
- package/src/skill/docs/compiler/getting-started/templates.md +111 -0
- package/src/skill/docs/compiler/index.md +85 -0
- package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
- package/src/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
- package/src/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
- package/src/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
- package/src/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
- package/src/skill/docs/compiler/targets/hono-api/index.md +37 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
- package/src/skill/docs/compiler/targets/index.md +47 -0
- package/src/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
- package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
- package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
- package/src/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
- package/src/skill/docs/compiler/troubleshooting.md +120 -0
- package/src/skill/docs/index.md +77 -0
- package/src/skill/docs/stack/account-ui/customization.md +378 -0
- package/src/skill/docs/stack/account-ui/environment-variables.md +325 -0
- package/src/skill/docs/stack/account-ui/features/admin.md +76 -0
- package/src/skill/docs/stack/account-ui/features/api-keys.md +22 -0
- package/src/skill/docs/stack/account-ui/features/avatars.md +37 -0
- package/src/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
- package/src/skill/docs/stack/account-ui/features/index.md +291 -0
- package/src/skill/docs/stack/account-ui/features/organizations.md +29 -0
- package/src/skill/docs/stack/account-ui/features/passkeys.md +31 -0
- package/src/skill/docs/stack/account-ui/features/passwordless.md +28 -0
- package/src/skill/docs/stack/account-ui/features/sessions.md +20 -0
- package/src/skill/docs/stack/account-ui/hooks.md +209 -0
- package/src/skill/docs/stack/account-ui/index.md +147 -0
- package/src/skill/docs/stack/account-ui/library-usage.md +257 -0
- package/src/skill/docs/stack/account-ui/standalone.md +149 -0
- package/src/skill/docs/stack/account-ui/with-quickback.md +160 -0
- package/src/skill/docs/stack/account-ui/worker.md +362 -0
- package/src/skill/docs/stack/auth/api-keys.md +15 -0
- package/src/skill/docs/stack/auth/device-auth.md +14 -0
- package/src/skill/docs/stack/auth/index.md +64 -0
- package/src/skill/docs/stack/auth/jwt-optimization.md +245 -0
- package/src/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
- package/src/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
- package/src/skill/docs/stack/auth/plugins/index.md +340 -0
- package/src/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
- package/src/skill/docs/stack/auth/security.md +455 -0
- package/src/skill/docs/stack/auth/using-auth.md +39 -0
- package/src/skill/docs/stack/cms/actions.md +199 -0
- package/src/skill/docs/stack/cms/components.md +479 -0
- package/src/skill/docs/stack/cms/connecting.md +199 -0
- package/src/skill/docs/stack/cms/dashboard.md +39 -0
- package/src/skill/docs/stack/cms/index.md +158 -0
- package/src/skill/docs/stack/cms/inline-editing.md +136 -0
- package/src/skill/docs/stack/cms/pages.md +275 -0
- package/src/skill/docs/stack/cms/record-layouts.md +151 -0
- package/src/skill/docs/stack/cms/schema-format.md +437 -0
- package/src/skill/docs/stack/cms/schema-registry.md +200 -0
- package/src/skill/docs/stack/cms/security.md +203 -0
- package/src/skill/docs/stack/cms/table-views.md +142 -0
- package/src/skill/docs/stack/index.md +65 -0
- package/src/skill/docs/stack/queues/handlers.md +317 -0
- package/src/skill/docs/stack/queues/index.md +56 -0
- package/src/skill/docs/stack/queues/using-queues.md +192 -0
- package/src/skill/docs/stack/realtime/durable-objects.md +488 -0
- package/src/skill/docs/stack/realtime/index.md +73 -0
- package/src/skill/docs/stack/realtime/partyserver-rooms.md +146 -0
- package/src/skill/docs/stack/realtime/using-realtime.md +211 -0
- package/src/skill/docs/stack/storage/index.md +17 -0
- package/src/skill/docs/stack/storage/kv.md +204 -0
- package/src/skill/docs/stack/storage/r2.md +232 -0
- package/src/skill/docs/stack/storage/using-kv.md +70 -0
- package/src/skill/docs/stack/storage/using-r2.md +55 -0
- package/src/skill/docs/stack/vector/embeddings.md +554 -0
- package/src/skill/docs/stack/vector/index.md +44 -0
- package/src/skill/docs/stack/vector/using-embeddings.md +186 -0
- package/src/skill/docs/stack/webhooks/inbound.md +186 -0
- package/src/skill/docs/stack/webhooks/index.md +36 -0
- package/src/skill/docs/stack/webhooks/outbound.md +281 -0
|
@@ -0,0 +1,246 @@
|
|
|
1
|
+
# D1 Database
|
|
2
|
+
|
|
3
|
+
Cloudflare D1 is SQLite at the edge. Quickback uses D1 as the primary database for Cloudflare deployments, with a multi-database pattern for separation of concerns.
|
|
4
|
+
|
|
5
|
+
## What is D1?
|
|
6
|
+
|
|
7
|
+
D1 is Cloudflare's serverless SQL database built on SQLite:
|
|
8
|
+
|
|
9
|
+
- **Edge-native** - Runs in Cloudflare's global network
|
|
10
|
+
- **SQLite compatible** - Use familiar SQL syntax
|
|
11
|
+
- **Zero configuration** - No connection strings or pooling
|
|
12
|
+
- **Automatic replication** - Read replicas at every edge location
|
|
13
|
+
|
|
14
|
+
## Multi-Database Pattern
|
|
15
|
+
|
|
16
|
+
Quickback generates separate D1 databases for different concerns:
|
|
17
|
+
|
|
18
|
+
| Database | Binding | Purpose |
|
|
19
|
+
|----------|---------|---------|
|
|
20
|
+
| `AUTH_DB` | `AUTH_DB` | Better Auth tables (user, session, account) |
|
|
21
|
+
| `DB` | `DB` | Your application data |
|
|
22
|
+
| `FILES_DB` | `FILES_DB` | File metadata for R2 uploads |
|
|
23
|
+
| `WEBHOOKS_DB` | `WEBHOOKS_DB` | Webhook delivery tracking |
|
|
24
|
+
|
|
25
|
+
This separation provides:
|
|
26
|
+
- **Independent scaling** - Auth traffic doesn't affect app queries
|
|
27
|
+
- **Isolation** - Auth schema changes don't touch your data
|
|
28
|
+
- **Clarity** - Clear ownership of each database
|
|
29
|
+
|
|
30
|
+
## Drizzle ORM Integration
|
|
31
|
+
|
|
32
|
+
Quickback uses [Drizzle ORM](https://orm.drizzle.team/) for type-safe database access:
|
|
33
|
+
|
|
34
|
+
```ts
|
|
35
|
+
// schema/tables.ts - Your schema definition
|
|
36
|
+
import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
|
|
37
|
+
|
|
38
|
+
export const posts = sqliteTable("posts", {
|
|
39
|
+
id: text("id").primaryKey(),
|
|
40
|
+
title: text("title").notNull(),
|
|
41
|
+
content: text("content"),
|
|
42
|
+
authorId: text("author_id").notNull(),
|
|
43
|
+
createdAt: integer("created_at", { mode: "timestamp" }),
|
|
44
|
+
});
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
The compiler generates Drizzle queries based on your security rules:
|
|
48
|
+
|
|
49
|
+
```ts
|
|
50
|
+
// Generated query with firewall applied
|
|
51
|
+
const result = await db
|
|
52
|
+
.select()
|
|
53
|
+
.from(posts)
|
|
54
|
+
.where(eq(posts.authorId, userId)); // Firewall injects ownership
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## Migrations
|
|
58
|
+
|
|
59
|
+
Quickback generates migrations automatically at compile time based on your schema changes:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
# Compile your project (generates migrations)
|
|
63
|
+
quickback compile
|
|
64
|
+
|
|
65
|
+
# Apply migrations locally
|
|
66
|
+
wrangler d1 migrations apply DB --local
|
|
67
|
+
|
|
68
|
+
# Apply to production D1
|
|
69
|
+
wrangler d1 migrations apply DB --remote
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Migration files are generated in `quickback/drizzle/` and version-controlled with your code. You never need to manually generate migrations—just define your schema and compile.
|
|
73
|
+
|
|
74
|
+
## wrangler.toml Bindings
|
|
75
|
+
|
|
76
|
+
The compiler generates D1 bindings in `wrangler.toml` automatically. To get production-ready IDs in the output, set them in your `quickback.config.ts`:
|
|
77
|
+
|
|
78
|
+
```typescript
|
|
79
|
+
providers: {
|
|
80
|
+
database: defineDatabase("cloudflare-d1", {
|
|
81
|
+
databaseId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", // Features DB → binding "DB"
|
|
82
|
+
authDatabaseId: "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy", // Auth DB → binding "AUTH_DB"
|
|
83
|
+
filesDatabaseId: "zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz", // Files DB → binding "FILES_DB"
|
|
84
|
+
}),
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
This generates:
|
|
89
|
+
|
|
90
|
+
```toml
|
|
91
|
+
[[d1_databases]]
|
|
92
|
+
binding = "AUTH_DB"
|
|
93
|
+
database_name = "my-app-auth"
|
|
94
|
+
database_id = "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"
|
|
95
|
+
|
|
96
|
+
[[d1_databases]]
|
|
97
|
+
binding = "DB"
|
|
98
|
+
database_name = "my-app-features"
|
|
99
|
+
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
|
|
100
|
+
|
|
101
|
+
[[d1_databases]]
|
|
102
|
+
binding = "FILES_DB"
|
|
103
|
+
database_name = "my-app-files"
|
|
104
|
+
database_id = "zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz"
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
If database IDs are omitted, the compiler uses local-dev placeholders — you'll need to replace them manually before deploying.
|
|
108
|
+
|
|
109
|
+
Create databases via Wrangler:
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
wrangler d1 create my-app-features
|
|
113
|
+
wrangler d1 create my-app-auth
|
|
114
|
+
wrangler d1 create my-app-files
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
## Accessing Data via API
|
|
118
|
+
|
|
119
|
+
All data access in Quickback goes through the generated API endpoints—never direct database queries. This ensures security rules (firewall, access, guards, masking) are always enforced.
|
|
120
|
+
|
|
121
|
+
### CRUD Operations
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
# List posts (firewall automatically filters by ownership)
|
|
125
|
+
GET /api/v1/posts
|
|
126
|
+
|
|
127
|
+
# Get a single post
|
|
128
|
+
GET /api/v1/posts/:id
|
|
129
|
+
|
|
130
|
+
# Create a post (guards validate allowed fields)
|
|
131
|
+
POST /api/v1/posts
|
|
132
|
+
{ "title": "Hello World", "content": "..." }
|
|
133
|
+
|
|
134
|
+
# Update a post (guards validate updatable fields)
|
|
135
|
+
PATCH /api/v1/posts/:id
|
|
136
|
+
{ "title": "Updated Title" }
|
|
137
|
+
|
|
138
|
+
# Delete a post
|
|
139
|
+
DELETE /api/v1/posts/:id
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
### Filtering and Pagination
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
# Filter by field
|
|
146
|
+
GET /api/v1/posts?status=published
|
|
147
|
+
|
|
148
|
+
# Pagination
|
|
149
|
+
GET /api/v1/posts?limit=10&offset=20
|
|
150
|
+
|
|
151
|
+
# Sort
|
|
152
|
+
GET /api/v1/posts?sort=createdAt&order=desc
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
### Why No Direct Database Access?
|
|
156
|
+
|
|
157
|
+
Direct database queries bypass Quickback's security layers:
|
|
158
|
+
- **Firewall** - Data isolation by user/org/team
|
|
159
|
+
- **Access** - Role-based permissions
|
|
160
|
+
- **Guards** - Field-level create/update restrictions
|
|
161
|
+
- **Masking** - Sensitive data redaction
|
|
162
|
+
|
|
163
|
+
Always use the API endpoints. For custom business logic, use [Actions](/compiler/definitions/actions).
|
|
164
|
+
|
|
165
|
+
## Local Development
|
|
166
|
+
|
|
167
|
+
D1 works locally with Wrangler:
|
|
168
|
+
|
|
169
|
+
```bash
|
|
170
|
+
# Start local dev server with D1
|
|
171
|
+
wrangler dev
|
|
172
|
+
|
|
173
|
+
# D1 data persists in .wrangler/state/
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
Local D1 uses SQLite files in `.wrangler/state/v3/d1/`, which you can inspect with any SQLite client.
|
|
177
|
+
|
|
178
|
+
## Security Architecture
|
|
179
|
+
|
|
180
|
+
For all Quickback-generated code, D1's application-layer security provides equivalent protection to Supabase RLS. The key difference is where enforcement happens — and this matters if you write custom routes.
|
|
181
|
+
|
|
182
|
+
### How Security Works
|
|
183
|
+
|
|
184
|
+
| Component | Enforcement | Notes |
|
|
185
|
+
|-----------|-------------|-------|
|
|
186
|
+
| CRUD endpoints | ✅ Firewall auto-applied | All generated routes enforce security |
|
|
187
|
+
| Actions | ✅ Firewall auto-applied | Both standalone and record-based |
|
|
188
|
+
| Manual routes | ⚠️ Must apply firewall | Use `withFirewall` helper |
|
|
189
|
+
|
|
190
|
+
### Why D1 is Secure
|
|
191
|
+
|
|
192
|
+
1. **No external database access** - D1 can only be queried through your Worker. There's no connection string or external endpoint.
|
|
193
|
+
2. **Generated code enforces rules** - All CRUD and Action endpoints automatically apply firewall, access, guards, and masking.
|
|
194
|
+
3. **Single entry point** - Every request flows through your API where security is enforced.
|
|
195
|
+
|
|
196
|
+
Unlike Supabase where PostgreSQL RLS provides database-level enforcement (protecting data even if application code has bugs), D1's security comes from architecture: the database is inaccessible except through your Worker, and all generated routes apply the four security pillars. The trade-off is that **custom routes you write outside Quickback must manually apply security** — there is no database-level safety net.
|
|
197
|
+
|
|
198
|
+
### Comparison with Supabase RLS
|
|
199
|
+
|
|
200
|
+
| Scenario | Supabase | D1 |
|
|
201
|
+
|----------|----------|-----|
|
|
202
|
+
| CRUD endpoints | ✅ Secure (RLS + App) | ✅ Secure (App) |
|
|
203
|
+
| Actions | ✅ Secure (RLS + App) | ✅ Secure (App) |
|
|
204
|
+
| Manual routes | ✅ RLS still protects | ⚠️ Must apply firewall |
|
|
205
|
+
| External DB access | ⚠️ Possible with credentials | ✅ Not possible |
|
|
206
|
+
| Dashboard queries | Via Supabase Studio | ⚠️ Admin only (audit logged) |
|
|
207
|
+
|
|
208
|
+
### Writing Manual Routes
|
|
209
|
+
|
|
210
|
+
If you write custom routes outside of Quickback compilation (e.g., custom reports, integrations), use the generated `withFirewall` helper to ensure security:
|
|
211
|
+
|
|
212
|
+
```ts
|
|
213
|
+
import { withFirewall } from '../features/invoices/resource';
|
|
214
|
+
|
|
215
|
+
app.get('/reports/monthly', async (c) => {
|
|
216
|
+
return withFirewall(c, async (ctx, firewall) => {
|
|
217
|
+
const results = await db.select()
|
|
218
|
+
.from(invoices)
|
|
219
|
+
.where(firewall);
|
|
220
|
+
return c.json(results);
|
|
221
|
+
});
|
|
222
|
+
});
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
The `withFirewall` helper:
|
|
226
|
+
- Validates authentication
|
|
227
|
+
- Builds the correct WHERE conditions for the current user/org
|
|
228
|
+
- Returns 401 if not authenticated
|
|
229
|
+
|
|
230
|
+
### Best Practices
|
|
231
|
+
|
|
232
|
+
1. **Use generated endpoints** - Prefer CRUD and Actions over manual routes
|
|
233
|
+
2. **Always apply firewall** - When writing manual routes, always use `withFirewall`
|
|
234
|
+
3. **Avoid raw SQL** - Raw SQL bypasses application security; use Drizzle ORM
|
|
235
|
+
4. **Review custom code** - Manual routes should be code-reviewed for security
|
|
236
|
+
|
|
237
|
+
## Limitations
|
|
238
|
+
|
|
239
|
+
D1 is built on SQLite, which means:
|
|
240
|
+
|
|
241
|
+
- **No stored procedures** - Business logic lives in your Worker
|
|
242
|
+
- **Single-writer** - One write connection at a time (reads scale horizontally)
|
|
243
|
+
- **Size limits** - 10GB per database (free tier: 500MB)
|
|
244
|
+
- **No PostgreSQL extensions** - Use Supabase if you need PostGIS, etc.
|
|
245
|
+
|
|
246
|
+
For most applications, these limits are non-issues. D1's edge distribution and zero-config setup outweigh the constraints.
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# Database
|
|
2
|
+
|
|
3
|
+
The Quickback Stack supports multiple database providers. Choose the one that fits your deployment target.
|
|
4
|
+
|
|
5
|
+
## Providers
|
|
6
|
+
|
|
7
|
+
| Provider | Best For | Features |
|
|
8
|
+
|----------|----------|----------|
|
|
9
|
+
| [Cloudflare D1](/compiler/targets/hono-api/database/d1) | Edge-first apps | SQLite at the edge, zero-latency reads |
|
|
10
|
+
| [Neon](/compiler/targets/hono-api/database/neon) | Postgres apps | Serverless Postgres, branching, autoscaling |
|
|
11
|
+
|
|
12
|
+
## Getting Started
|
|
13
|
+
|
|
14
|
+
- **[D1 Setup](/compiler/targets/hono-api/database/d1)** — Bindings, wrangler config, migrations
|
|
15
|
+
- **[Using D1](/compiler/targets/hono-api/database/using-d1)** — Drizzle queries, dual-DB mode, schema patterns
|
|
16
|
+
- **[Neon](/compiler/targets/hono-api/database/neon)** — Serverless Postgres setup and usage
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
# Neon
|
|
2
|
+
|
|
3
|
+
Neon provides serverless PostgreSQL that works with Cloudflare Workers via HTTP connections. Choose Neon when you need PostgreSQL features (JSON operators, full-text search, advanced indexing) or want database-level Row Level Security alongside the generated Hono API.
|
|
4
|
+
|
|
5
|
+
## Why Neon
|
|
6
|
+
|
|
7
|
+
- **Full PostgreSQL** — Advanced queries, joins, PostGIS, full-text search
|
|
8
|
+
- **Database-level security** — RLS policies enforce access even if the API is bypassed
|
|
9
|
+
- **Serverless** — HTTP connection mode for Cloudflare Workers
|
|
10
|
+
- **Neon Authorize** — JWT-based RLS via the `auth.user_id()` function
|
|
11
|
+
- **Better Auth integration** — Works seamlessly with the Quickback auth provider
|
|
12
|
+
|
|
13
|
+
## Configuration
|
|
14
|
+
|
|
15
|
+
```typescript title="quickback/quickback.config.ts"
|
|
16
|
+
import { defineConfig, defineRuntime, defineDatabase, defineAuth } from "@quickback/compiler";
|
|
17
|
+
|
|
18
|
+
export default defineConfig({
|
|
19
|
+
name: "my-app",
|
|
20
|
+
providers: {
|
|
21
|
+
runtime: defineRuntime("cloudflare"),
|
|
22
|
+
database: defineDatabase("neon", {
|
|
23
|
+
connectionMode: "auto", // detects runtime
|
|
24
|
+
pooled: true,
|
|
25
|
+
}),
|
|
26
|
+
auth: defineAuth("better-auth"),
|
|
27
|
+
},
|
|
28
|
+
});
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Connection modes
|
|
32
|
+
|
|
33
|
+
| Mode | Best for | How it works |
|
|
34
|
+
|------|----------|--------------|
|
|
35
|
+
| **HTTP** | Cloudflare Workers, edge functions | Stateless HTTP queries via `@neondatabase/serverless` |
|
|
36
|
+
| **WebSocket** | Node.js, Bun | Persistent WebSocket connection for lower latency |
|
|
37
|
+
| **Auto** (default) | Mixed environments | Detects runtime and picks the best mode |
|
|
38
|
+
|
|
39
|
+
## Environment variables
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
# For Cloudflare Workers
|
|
43
|
+
npx wrangler secret put DATABASE_URL
|
|
44
|
+
# Paste: postgresql://user:pwd@ep-xxx.region.neon.tech/db?sslmode=require
|
|
45
|
+
|
|
46
|
+
# For local development (.env)
|
|
47
|
+
DATABASE_URL=postgresql://user:pwd@ep-xxx.region.neon.tech/db?sslmode=require
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Migrations
|
|
51
|
+
|
|
52
|
+
Neon uses PostgreSQL migrations, distinct from D1's SQLite migrations:
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
quickback compile # generates migrations under quickback/drizzle/
|
|
56
|
+
npm run db:migrate # applies them
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Row Level Security
|
|
60
|
+
|
|
61
|
+
Quickback emits RLS policies from your `firewall` and `access` config. The Neon target uses Neon Authorize's `auth.user_id()` JWT claim function (the Supabase target uses `auth.uid()` instead — same pattern, different function).
|
|
62
|
+
|
|
63
|
+
```typescript
|
|
64
|
+
firewall: [
|
|
65
|
+
{ field: 'organizationId', equals: 'ctx.activeOrgId' },
|
|
66
|
+
]
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
```sql
|
|
70
|
+
CREATE POLICY "documents_select" ON documents FOR SELECT
|
|
71
|
+
USING (
|
|
72
|
+
organization_id = get_active_org_id()
|
|
73
|
+
AND (has_any_role(ARRAY['admin']) OR user_id = auth.user_id())
|
|
74
|
+
);
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
### Firewall patterns
|
|
78
|
+
|
|
79
|
+
**Organization-scoped:**
|
|
80
|
+
|
|
81
|
+
```sql
|
|
82
|
+
CREATE POLICY "projects_select" ON projects FOR SELECT
|
|
83
|
+
USING (organization_id = public.get_active_org_id());
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
**User-scoped:**
|
|
87
|
+
|
|
88
|
+
```sql
|
|
89
|
+
CREATE POLICY "preferences_select" ON preferences FOR SELECT
|
|
90
|
+
USING (user_id = auth.user_id());
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
**Public tables:**
|
|
94
|
+
|
|
95
|
+
```sql
|
|
96
|
+
CREATE POLICY "categories_deny_anon" ON categories FOR ALL TO anon USING (false);
|
|
97
|
+
CREATE POLICY "categories_all" ON categories FOR ALL TO authenticated USING (true) WITH CHECK (true);
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
### Helper functions
|
|
101
|
+
|
|
102
|
+
| Function | Purpose |
|
|
103
|
+
|----------|---------|
|
|
104
|
+
| `get_active_org_id()` | Returns the user's active organization from `user_sessions` |
|
|
105
|
+
| `has_any_role(roles[])` | Checks if the user has any specified role |
|
|
106
|
+
| `has_org_role(role)` | Checks for a single specific role |
|
|
107
|
+
| `is_org_member()` | Checks org membership |
|
|
108
|
+
| `is_owner(owner_id)` | Checks record ownership |
|
|
109
|
+
|
|
110
|
+
## Setting up Neon Authorize
|
|
111
|
+
|
|
112
|
+
1. Open **Project Settings → Authorize** in the Neon console
|
|
113
|
+
2. Add your JWKS URL: `https://your-api.example.com/auth/v1/.well-known/jwks.json`
|
|
114
|
+
3. The `auth.user_id()` function will return the authenticated user's ID from the JWT
|
|
115
|
+
|
|
116
|
+
## Generated files
|
|
117
|
+
|
|
118
|
+
```
|
|
119
|
+
quickback/drizzle/
|
|
120
|
+
├── migrations/
|
|
121
|
+
│ ├── 0100_create_rls_helpers.sql
|
|
122
|
+
│ ├── 0101_create_rls_policies.sql
|
|
123
|
+
│ └── 0102_create_indexes.sql
|
|
124
|
+
src/
|
|
125
|
+
├── db/schema.ts # Drizzle schema
|
|
126
|
+
├── auth/schema.ts # Better Auth schema
|
|
127
|
+
└── lib/neon.ts # Connection helper
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
## When to choose Neon vs D1
|
|
131
|
+
|
|
132
|
+
| Factor | Neon | D1 |
|
|
133
|
+
|--------|------|-----|
|
|
134
|
+
| SQL dialect | PostgreSQL | SQLite |
|
|
135
|
+
| Security model | RLS + application-layer | Application-layer only |
|
|
136
|
+
| Multi-region | Built-in replication | Single region per database |
|
|
137
|
+
| Pricing | Free tier, then usage-based | Free tier, then usage-based |
|
|
138
|
+
| Best for | Complex queries, existing Postgres apps | Edge-first, simple schemas |
|
|
139
|
+
|
|
140
|
+
## See also
|
|
141
|
+
|
|
142
|
+
- [D1](/compiler/targets/hono-api/database/d1) — SQLite at the edge
|
|
143
|
+
- [Providers](/compiler/config/providers) — All database provider options
|
|
144
|
+
- [Quickback for Supabase](/compiler/targets/supabase-rls) — A different Postgres+RLS path that uses Supabase Auth instead of Better Auth
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Using D1
|
|
2
|
+
|
|
3
|
+
This page covers how to use Cloudflare D1 with Drizzle ORM in your Quickback Stack application.
|
|
4
|
+
|
|
5
|
+
## Drizzle Queries
|
|
6
|
+
|
|
7
|
+
The generated API uses Drizzle ORM for all database operations:
|
|
8
|
+
|
|
9
|
+
```typescript
|
|
10
|
+
import { db } from '../db';
|
|
11
|
+
import { rooms } from '../schema';
|
|
12
|
+
import { eq } from 'drizzle-orm';
|
|
13
|
+
|
|
14
|
+
// Select
|
|
15
|
+
const allRooms = await db.select().from(rooms);
|
|
16
|
+
|
|
17
|
+
// Where clause
|
|
18
|
+
const room = await db.select().from(rooms).where(eq(rooms.id, id));
|
|
19
|
+
|
|
20
|
+
// Insert
|
|
21
|
+
await db.insert(rooms).values({ name: 'Conference A' });
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## Dual-DB Mode
|
|
25
|
+
|
|
26
|
+
Quickback supports separate databases for auth and application data, useful for multi-tenant SaaS apps.
|
|
27
|
+
|
|
28
|
+
## Migrations
|
|
29
|
+
|
|
30
|
+
Migrations are generated by the compiler using `drizzle-kit generate`. Apply them with:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
npx wrangler d1 migrations apply my-db
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## Related
|
|
37
|
+
|
|
38
|
+
- [D1 Setup](/compiler/targets/hono-api/database/d1) — Bindings and wrangler config
|
|
39
|
+
- [Schema](/compiler/definitions/schema) — Defining your database schema
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Quickback for Hono API
|
|
2
|
+
|
|
3
|
+
**Quickback for Hono API** is the default compile target. Your `defineTable()` and `defineActions()` files become a complete Hono application: routes, middleware, types, OpenAPI spec, and an MCP server, all generated and ready to deploy.
|
|
4
|
+
|
|
5
|
+
## What you ship
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
src/
|
|
9
|
+
├── routes/ # One file per resource — GET/POST/PATCH/DELETE + batch
|
|
10
|
+
├── middleware/ # Auth, firewall, access, guards, masking
|
|
11
|
+
├── types/ # TypeScript interfaces inferred from your schema
|
|
12
|
+
├── openapi.json # Generated spec, served at /openapi.json
|
|
13
|
+
└── index.ts # Hono app entry point
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
The generated app runs on **Cloudflare Workers** (recommended) or any Hono-compatible runtime. Pair it with **Cloudflare D1** for SQLite-at-the-edge or **Neon** for full PostgreSQL with database-level RLS.
|
|
17
|
+
|
|
18
|
+
## Pick your database
|
|
19
|
+
|
|
20
|
+
| Database | Best for | Notes |
|
|
21
|
+
|----------|----------|-------|
|
|
22
|
+
| [**Cloudflare D1**](/compiler/targets/hono-api/database/d1) | Most projects | SQLite at the edge. Application-level security. Free tier covers a lot. |
|
|
23
|
+
| [**Neon**](/compiler/targets/hono-api/database/neon) | PostgreSQL features needed | Full Postgres with database-level RLS via Neon Authorize. |
|
|
24
|
+
|
|
25
|
+
## Pick your runtime
|
|
26
|
+
|
|
27
|
+
| Runtime | Notes |
|
|
28
|
+
|---------|-------|
|
|
29
|
+
| [**Cloudflare Workers**](/compiler/targets/hono-api/cloudflare) | Default. Edge-native, integrates with the rest of [Quickback Stack](/stack). |
|
|
30
|
+
| Bun / Node | Supported via the same Hono output. Less first-class for Stack services. |
|
|
31
|
+
|
|
32
|
+
## In this section
|
|
33
|
+
|
|
34
|
+
- **[Cloudflare](/compiler/targets/hono-api/cloudflare)** — Compile and deploy to Workers
|
|
35
|
+
- **[Neon](/compiler/targets/hono-api/database/neon)** — Compile to PostgreSQL with RLS
|
|
36
|
+
- **[Database](/compiler/targets/hono-api/database)** — D1, Neon, schema and migrations
|
|
37
|
+
- **[Using the API](/compiler/targets/hono-api/using-the-api)** — CRUD, batch operations, query params, OpenAPI, errors
|