okengine 0.9.0 → 0.10.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.
Files changed (175) hide show
  1. package/AGENTS.md +1 -1
  2. package/manifest.v1.schema.json +9 -1
  3. package/package.json +3 -3
  4. package/site/content/docs/console/runs.mdx +10 -0
  5. package/site/content/docs/console/traces.mdx +4 -0
  6. package/site/content/docs/elements/ai.mdx +54 -32
  7. package/site/content/docs/elements/channel.mdx +105 -14
  8. package/site/content/docs/elements/clock.mdx +1 -0
  9. package/site/content/docs/elements/flow.mdx +42 -8
  10. package/site/content/docs/get-started/basic-usage.mdx +5 -1
  11. package/site/content/docs/get-started/installation.mdx +9 -5
  12. package/site/content/docs/meta.json +2 -0
  13. package/site/content/docs/plugins/otp.mdx +58 -46
  14. package/site/content/docs/providers/azure-redis.mdx +85 -0
  15. package/site/content/docs/providers/cockroachdb.mdx +86 -0
  16. package/site/content/docs/providers/digitalocean-caching.mdx +88 -0
  17. package/site/content/docs/providers/dragonfly-cloud.mdx +82 -0
  18. package/site/content/docs/providers/elasticache.mdx +92 -0
  19. package/site/content/docs/providers/index.mdx +101 -0
  20. package/site/content/docs/providers/memorystore.mdx +89 -0
  21. package/site/content/docs/providers/meta.json +20 -0
  22. package/site/content/docs/providers/neon.mdx +115 -0
  23. package/site/content/docs/providers/redis-cloud.mdx +93 -0
  24. package/site/content/docs/providers/supabase.mdx +117 -0
  25. package/site/content/docs/providers/upstash.mdx +91 -0
  26. package/site/content/docs/providers/yugabytedb.mdx +95 -0
  27. package/site/content/docs/recipes/caddy.mdx +128 -0
  28. package/site/content/docs/recipes/cockroachdb.mdx +127 -0
  29. package/site/content/docs/recipes/dragonfly.mdx +125 -0
  30. package/site/content/docs/recipes/index.mdx +146 -0
  31. package/site/content/docs/recipes/llama-cpp.mdx +153 -0
  32. package/site/content/docs/recipes/mailpit.mdx +136 -0
  33. package/site/content/docs/recipes/meilisearch.mdx +139 -0
  34. package/site/content/docs/recipes/meta.json +31 -0
  35. package/site/content/docs/recipes/ollama.mdx +142 -0
  36. package/site/content/docs/recipes/openbao.mdx +141 -0
  37. package/site/content/docs/recipes/pgdog.mdx +137 -0
  38. package/site/content/docs/recipes/postgres.mdx +136 -0
  39. package/site/content/docs/recipes/redis.mdx +130 -0
  40. package/site/content/docs/recipes/rustfs.mdx +148 -0
  41. package/site/content/docs/recipes/sglang.mdx +105 -0
  42. package/site/content/docs/recipes/supabase-docker.mdx +145 -0
  43. package/site/content/docs/recipes/timescale.mdx +129 -0
  44. package/site/content/docs/recipes/traefik.mdx +136 -0
  45. package/site/content/docs/recipes/valkey.mdx +121 -0
  46. package/site/content/docs/recipes/vllm.mdx +106 -0
  47. package/site/content/docs/recipes/yugabytedb.mdx +135 -0
  48. package/site/content/docs/reference/cli.md +42 -6
  49. package/site/content/docs/reference/configuration.mdx +5 -3
  50. package/site/content/docs/reference/environment-variables.mdx +12 -12
  51. package/site/content/docs/reference/fx.mdx +38 -4
  52. package/src/auth/otp-capability.ts +14 -14
  53. package/src/cli/ai-setup/ai-setup.test.ts +32 -12
  54. package/src/cli/ai-setup/apply.ts +65 -23
  55. package/src/cli/ai-setup/catalog.ts +1316 -35
  56. package/src/cli/ai-setup/detect-ollama.ts +47 -0
  57. package/src/cli/ai-setup/index.ts +44 -7
  58. package/src/cli/ai-setup/prompts.ts +430 -486
  59. package/src/cli/ai-setup/recommend.test.ts +150 -50
  60. package/src/cli/ai-setup/recommend.ts +118 -101
  61. package/src/cli/ask-seed.test.ts +68 -0
  62. package/src/cli/ask-seed.ts +79 -0
  63. package/src/cli/db-seed-redact.test.ts +25 -0
  64. package/src/cli/db-seed.ts +36 -7
  65. package/src/cli/db.test.ts +1 -1
  66. package/src/cli/db.ts +2 -2
  67. package/src/cli/dev-controls.test.ts +107 -0
  68. package/src/cli/dev-controls.ts +354 -0
  69. package/src/cli/dev-schema-sync.ts +12 -4
  70. package/src/cli/dev.test.ts +50 -30
  71. package/src/cli/dev.ts +607 -66
  72. package/src/cli/drizzle-env.test.ts +40 -6
  73. package/src/cli/drizzle-env.ts +22 -1
  74. package/src/cli/ensure-drizzle-config.ts +6 -4
  75. package/src/cli/hero-meta.test.ts +13 -1
  76. package/src/cli/hero-meta.ts +28 -6
  77. package/src/cli/index.ts +5 -0
  78. package/src/cli/registry.ts +24 -0
  79. package/src/cli/replay.test.ts +105 -0
  80. package/src/cli/replay.ts +206 -0
  81. package/src/compiler/extract.ts +3 -3
  82. package/src/config/index.ts +3 -3
  83. package/src/console/server/claim.ts +3 -1
  84. package/src/console/ui/dist/assets/{index-ClX0ZCe5.js → index-D-9KFce5.js} +2 -2
  85. package/src/console/ui/dist/assets/panel-overview-CW0CQEc2.js +1 -0
  86. package/src/console/ui/dist/assets/panel-runs-BxuyDI3x.js +1 -0
  87. package/src/console/ui/dist/assets/{panel-signals-Dsxdu_AR.js → panel-signals-BXofbj7v.js} +1 -1
  88. package/src/console/ui/dist/assets/{panel-store-hy7O8HOs.js → panel-store-B8mH-arU.js} +1 -1
  89. package/src/console/ui/dist/assets/{panel-traces-CBiAe5go.js → panel-traces-DSA-ZWnf.js} +1 -1
  90. package/src/console/ui/dist/index.html +1 -1
  91. package/src/console/ui/overview/slo.ts +31 -3
  92. package/src/console/ui/overview/types.ts +6 -0
  93. package/src/console/ui/runs/errors.test.ts +53 -0
  94. package/src/console/ui/runs/errors.ts +88 -0
  95. package/src/console/ui/runs/index.ts +8 -0
  96. package/src/console/ui/runs/search.ts +16 -0
  97. package/src/console/ui/shell/panels/runs/RunsPanel.tsx +72 -1
  98. package/src/docker/ai-model-status.test.ts +101 -0
  99. package/src/docker/ai-model-status.ts +276 -0
  100. package/src/docker/compose-health.test.ts +115 -0
  101. package/src/docker/compose-health.ts +234 -0
  102. package/src/docker/compose.ts +24 -8
  103. package/src/docker/derive.ts +35 -9
  104. package/src/docker/docker.test.ts +304 -12
  105. package/src/docker/helpers.ts +56 -0
  106. package/src/docker/index.ts +52 -0
  107. package/src/docker/ollama-pull.ts +232 -0
  108. package/src/docker/recipes/cockroach.ts +24 -0
  109. package/src/docker/recipes/index.ts +32 -0
  110. package/src/docker/recipes/llama-cpp.ts +273 -0
  111. package/src/docker/recipes/ollama.ts +19 -23
  112. package/src/docker/recipes/pgdog.ts +4 -1
  113. package/src/docker/recipes/postgres.ts +5 -18
  114. package/src/docker/recipes/sglang.ts +55 -0
  115. package/src/docker/recipes/supabase.ts +21 -0
  116. package/src/docker/recipes/timescale.ts +18 -0
  117. package/src/docker/recipes/vllm.ts +44 -0
  118. package/src/docker/recipes/yugabyte.ts +23 -0
  119. package/src/docker/stack-id.test.ts +22 -0
  120. package/src/docker/stack-id.ts +38 -4
  121. package/src/docker/types.ts +15 -0
  122. package/src/drivers/ai-ollama.integration.test.ts +7 -4
  123. package/src/drivers/signal-engine.ts +10 -0
  124. package/src/drivers/signal-postgres.ts +24 -2
  125. package/src/drivers/signal-types.ts +10 -0
  126. package/src/elements/channel/fallback.test.ts +91 -0
  127. package/src/elements/channel/hard-bounce.test.ts +82 -0
  128. package/src/elements/channel/injection.test.ts +153 -0
  129. package/src/elements/channel/locale-ar.test.ts +102 -0
  130. package/src/elements/channel/otp-delivery.ts +5 -2
  131. package/src/elements/channel/receipts-ledger.test.ts +100 -0
  132. package/src/elements/channel/runtime.ts +24 -1
  133. package/src/elements/channel/test-helpers.ts +60 -0
  134. package/src/elements/channel/whatsapp-compliance.test.ts +124 -0
  135. package/src/elements/store/cache.ts +1 -1
  136. package/src/elements/store/emit-drizzle.ts +43 -9
  137. package/src/elements/store/runtime.ts +1 -1
  138. package/src/elements/store/schema-decl.test.ts +2 -0
  139. package/src/elements/store/schema-decl.ts +15 -0
  140. package/src/elements/store/seed.ts +1 -1
  141. package/src/index.ts +1 -0
  142. package/src/kernel/app.ts +118 -11
  143. package/src/kernel/boot-bind/signal.ts +6 -2
  144. package/src/kernel/boot-bind/store.ts +2 -1
  145. package/src/kernel/boot.test.ts +6 -5
  146. package/src/kernel/boot.ts +8 -3
  147. package/src/kernel/compensate.test.ts +131 -0
  148. package/src/kernel/correlation.test.ts +108 -0
  149. package/src/kernel/effect-timing.test.ts +82 -0
  150. package/src/kernel/flow.ts +38 -0
  151. package/src/kernel/fx-runs.test.ts +49 -0
  152. package/src/kernel/fx.test.ts +14 -0
  153. package/src/kernel/fx.ts +111 -1
  154. package/src/manifest/types.ts +8 -2
  155. package/src/plugins/auth-delivery.mailpit.integration.test.ts +1 -1
  156. package/src/plugins/auth-methods.security.test.ts +3 -3
  157. package/src/plugins/auth-methods.test.ts +1 -1
  158. package/src/plugins/index.ts +2 -2
  159. package/src/plugins/otp.test.ts +21 -19
  160. package/src/plugins/otp.ts +36 -34
  161. package/src/plugins/taqnyat.live.test.ts +3 -3
  162. package/src/runs/collect.ts +3 -0
  163. package/src/runs/export-otlp.ts +64 -0
  164. package/src/runs/index.ts +16 -0
  165. package/src/runs/parquet.ts +9 -0
  166. package/src/runs/types.ts +5 -0
  167. package/src/runs/window.test.ts +68 -0
  168. package/src/runs/window.ts +148 -0
  169. package/src/runtime/boot-warn.test.ts +45 -0
  170. package/src/runtime/boot-warn.ts +17 -0
  171. package/src/runtime/dev-request-log.ts +5 -5
  172. package/src/term.test.ts +95 -10
  173. package/src/term.ts +369 -14
  174. package/src/console/ui/dist/assets/panel-overview-DONDzBd2.js +0 -1
  175. package/src/console/ui/dist/assets/panel-runs-D5zf-D9c.js +0 -1
@@ -0,0 +1,101 @@
1
+ ---
2
+ title: "Providers"
3
+ description: "Managed cloud SQL and Redis providers behind oke's postgres and redis drivers — dashboard click-paths, pooling, and gotchas."
4
+ icon: "Cloud"
5
+ source: "docs/spec/unified-theory.md"
6
+ ---
7
+
8
+ Every provider below speaks a protocol oke already drives — Postgres wire or Redis wire.
9
+ Hand the connection string to that driver; no new driver id, no Flow code changes.
10
+
11
+ <Callout title="The one rule">
12
+ Vendor choice lives in a connection URL (`DATABASE_URL` / `REDIS_URL`) — never in
13
+ `drivers.store.sql` / `drivers.store.kv`, which only ever say `postgres` or `redis`.
14
+ </Callout>
15
+
16
+ ## SQL providers
17
+
18
+ Managed Postgres-wire databases — set `DATABASE_URL`, driver stays `postgres`.
19
+
20
+ <Cards>
21
+ <Card
22
+ title="Neon"
23
+ description="Connect widget · pooled vs direct · cold start."
24
+ href="/docs/providers/neon"
25
+ />
26
+ <Card
27
+ title="Supabase"
28
+ description="Connect modes · :6543 vs :5432 · free pause."
29
+ href="/docs/providers/supabase"
30
+ />
31
+ <Card
32
+ title="CockroachDB"
33
+ description="Connect dialog · verify-full · CA cert."
34
+ href="/docs/providers/cockroachdb"
35
+ />
36
+ <Card
37
+ title="YugabyteDB"
38
+ description="YSQL on :5433 · Connect → Application."
39
+ href="/docs/providers/yugabytedb"
40
+ />
41
+ </Cards>
42
+
43
+ ## Redis providers
44
+
45
+ Managed Redis-wire caches — set `REDIS_URL`, driver stays `redis`.
46
+
47
+ <Cards>
48
+ <Card
49
+ title="Redis Cloud"
50
+ description="Configuration tab · Connect wizard · rediss://"
51
+ href="/docs/providers/redis-cloud"
52
+ />
53
+ <Card
54
+ title="Amazon ElastiCache"
55
+ description="Primary Endpoint · Redis OSS ≤7.1."
56
+ href="/docs/providers/elasticache"
57
+ />
58
+ <Card
59
+ title="Google Memorystore"
60
+ description="Primary Endpoint IP · TLS on 6378."
61
+ href="/docs/providers/memorystore"
62
+ />
63
+ <Card
64
+ title="Azure Cache for Redis"
65
+ description="Access keys · TLS port 6380."
66
+ href="/docs/providers/azure-redis"
67
+ />
68
+ <Card
69
+ title="Upstash"
70
+ description="TCP rediss:// — not REST tokens."
71
+ href="/docs/providers/upstash"
72
+ />
73
+ <Card
74
+ title="Dragonfly Cloud"
75
+ description="Data store drawer · Connection URI."
76
+ href="/docs/providers/dragonfly-cloud"
77
+ />
78
+ <Card
79
+ title="DigitalOcean Managed Caching"
80
+ description="Connection Details · trusted sources."
81
+ href="/docs/providers/digitalocean-caching"
82
+ />
83
+ </Cards>
84
+
85
+ ## Learn more
86
+
87
+ - [Recipes](/docs/recipes) — self-hosted recipes for the same protocols
88
+ - [Store](/docs/elements/store) — `sql` / `kv` facets
89
+ - [Environment variables](/docs/reference/environment-variables) — URL precedence
90
+
91
+ ## Next
92
+
93
+ <Cards>
94
+ <Card
95
+ title="Neon"
96
+ description="Start with a serverless SQL option."
97
+ href="/docs/providers/neon"
98
+ />
99
+ <Card title="Recipes" description="Run the same protocols yourself." href="/docs/recipes" />
100
+ <Card title="Store" description="The facets these drivers back." href="/docs/elements/store" />
101
+ </Cards>
@@ -0,0 +1,89 @@
1
+ ---
2
+ title: "Google Cloud Memorystore"
3
+ description: "GCP-managed Redis/Valkey — Instance details Primary Endpoint, AUTH string, TLS on 6378, VPC-only."
4
+ icon: "Zap"
5
+ source: "docs/spec/unified-theory.md"
6
+ ---
7
+
8
+ Memorystore for Redis (and the Valkey offering) is private-IP only inside your VPC.
9
+ `drivers.store.kv` stays `redis`.
10
+
11
+ <Callout title="The one rule">
12
+ Open the instance → **Connections** for **Primary Endpoint** + port; **Security** for the AUTH
13
+ string. There is no public hostname to paste.
14
+ </Callout>
15
+
16
+ ## Find credentials (current console)
17
+
18
+ 1. Google Cloud Console → **Memorystore** → **Redis** (or Valkey) → click **Instance ID**.
19
+ 2. **Connections** section → copy **Primary Endpoint** (private IP) and **Port**
20
+ (usually `6379`).
21
+ 3. If AUTH is enabled: **Security** section → **AUTH string** (or
22
+ `gcloud redis instances get-auth-string INSTANCE --region=REGION`).
23
+ 4. If **in-transit encryption** is on: download the **TLS server certificate** from the
24
+ instance page; clients use port **6378** with that CA (not plain 6379).
25
+
26
+ ```bash title="process env"
27
+ # AUTH on, transit encryption off (common default)
28
+ REDIS_URL=redis://:AUTH_STRING@10.0.0.3:6379
29
+
30
+ # Transit encryption on → port 6378 + rediss:// + CA configured in the client
31
+ # REDIS_URL=rediss://:AUTH_STRING@10.0.0.3:6378
32
+ ```
33
+
34
+ Cloud Run / Cloud Functions need a **Serverless VPC Access** connector on the same
35
+ network.
36
+
37
+ ## Production guidance
38
+
39
+ | Topic | Guidance |
40
+ | ---------- | -------------------------------------------------------------------------------- |
41
+ | Networking | Private IP only — never a public endpoint option |
42
+ | AUTH | Optional but recommended; string is on the instance Security panel |
43
+ | TLS | **Not** default — enable in-transit encryption explicitly; port becomes **6378** |
44
+ | Tiers | Basic vs Standard (replica) — pick before you need HA |
45
+
46
+ ## Real gotcha — TLS port flip
47
+
48
+ Enabling in-transit encryption changes the client port to **6378** and requires the
49
+ server CA. Leaving `REDIS_URL` on `:6379` after enabling TLS looks like a mysterious
50
+ timeout — update port and scheme together.
51
+
52
+ ## Troubleshooting
53
+
54
+ <Accordions>
55
+ <Accordion title="Connection refused / timeout from Cloud Run">
56
+
57
+ Missing Serverless VPC Access connector, or connector on the wrong VPC. Memorystore is
58
+ unreachable from the public internet by design.
59
+
60
+ </Accordion>
61
+ <Accordion title="NOAUTH Authentication required">
62
+
63
+ AUTH enabled but password omitted from `REDIS_URL`. Copy the AUTH string from
64
+ **Security** and use `redis://:AUTH@ip:port`.
65
+
66
+ </Accordion>
67
+ </Accordions>
68
+
69
+ ## Learn more
70
+
71
+ - [Redis (image)](/docs/recipes/redis) · [Valkey (image)](/docs/recipes/valkey)
72
+ - [ElastiCache](/docs/providers/elasticache) — AWS equivalent
73
+ - [Store · KV](/docs/elements/store#kv)
74
+
75
+ ## Next
76
+
77
+ <Cards>
78
+ <Card title="ElastiCache" description="AWS's equivalent." href="/docs/providers/elasticache" />
79
+ <Card
80
+ title="Azure Cache for Redis"
81
+ description="Azure's equivalent."
82
+ href="/docs/providers/azure-redis"
83
+ />
84
+ <Card
85
+ title="Dragonfly Cloud"
86
+ description="Public TLS endpoint option."
87
+ href="/docs/providers/dragonfly-cloud"
88
+ />
89
+ </Cards>
@@ -0,0 +1,20 @@
1
+ {
2
+ "title": "Providers",
3
+ "icon": "Cloud",
4
+ "pages": [
5
+ "index",
6
+ "---SQL providers---",
7
+ "neon",
8
+ "supabase",
9
+ "cockroachdb",
10
+ "yugabytedb",
11
+ "---Redis providers---",
12
+ "redis-cloud",
13
+ "elasticache",
14
+ "memorystore",
15
+ "azure-redis",
16
+ "upstash",
17
+ "dragonfly-cloud",
18
+ "digitalocean-caching"
19
+ ]
20
+ }
@@ -0,0 +1,115 @@
1
+ ---
2
+ title: "Neon"
3
+ description: "Serverless Postgres — Connect widget, pooled vs direct, scale-to-zero cold start, neon_superuser for pgvector."
4
+ icon: "Database"
5
+ source: "docs/spec/unified-theory.md"
6
+ ---
7
+
8
+ Neon separates storage from compute: branches are cheap copy-on-write metadata, and idle
9
+ compute scales to zero. Wire protocol is plain Postgres — `drivers.store.sql` stays
10
+ `postgres`.
11
+
12
+ <Callout title="The one rule">
13
+ Copy the connection string from Neon's **Connect** widget. Prefer the pooled hostname for app
14
+ traffic and the direct hostname for migrations — never invent the `-pooler` suffix by hand.
15
+ </Callout>
16
+
17
+ ## Find credentials (current console)
18
+
19
+ 1. Open [console.neon.tech](https://console.neon.tech) → your **project**.
20
+ 2. On the **Project Dashboard**, click **Connect**.
21
+ 3. In **Connect to your database**, pick **Branch**, **Compute**, **Database**, and
22
+ **Role**.
23
+ 4. Toggle **Connection pooling** **on** for the pooled string (hostname gains `-pooler`),
24
+ or **off** for the direct string.
25
+ 5. Copy the connection string into `DATABASE_URL` (add `?sslmode=require` if missing).
26
+
27
+ ```bash title="process env"
28
+ # Runtime (pooled) — ep-….…-pooler.…neon.tech
29
+ DATABASE_URL=postgresql://neondb_owner:…@ep-xxxx-pooler.region.aws.neon.tech/neondb?sslmode=require
30
+
31
+ # Migrations / pg_dump / LISTEN — same host without -pooler
32
+ # OKE_STORE_SQL_URL=postgresql://neondb_owner:…@ep-xxxx.region.aws.neon.tech/neondb?sslmode=require
33
+ ```
34
+
35
+ No `images["store.sql"]` pin — Neon runs the server.
36
+
37
+ ## Pooled vs direct
38
+
39
+ | Use | Which string | Why |
40
+ | ------------------------------------------------------------- | ------------------------- | -------------------------------------------------------- |
41
+ | App / serverless / Drizzle runtime | **Pooled** (`-pooler`) | PgBouncer transaction mode; up to 10k client connections |
42
+ | `oke db migrate` / `pg_dump` / logical replication / `LISTEN` | **Direct** (no `-pooler`) | Session features break under transaction pooling |
43
+
44
+ Do **not** also put [PgDog](/docs/recipes/pgdog) in front of Neon — one pooler only.
45
+
46
+ **Consequence:** seeding or migrations through the pooled URL often fail with prepared-statement
47
+ errors; switch those jobs to the direct URL.
48
+
49
+ ## pgvector and roles
50
+
51
+ `CREATE EXTENSION vector;` works on every plan — no add-on. Roles created in the Neon
52
+ Console / CLI / API get `neon_superuser` membership and can install supported extensions.
53
+
54
+ Roles you create only with raw SQL (`CREATE ROLE`) do **not** get `neon_superuser` — they
55
+ hit permission errors on extension install. Create app roles in the Console (or grant
56
+ deliberately) when you need `pgvector` setup from that role.
57
+
58
+ ## Free tier / production limits
59
+
60
+ | Limit | Free plan |
61
+ | ------------- | ----------------------------------------- |
62
+ | Scale to zero | After **5 min** idle — **cannot disable** |
63
+ | Compute | **100 CU-hours** / project / month |
64
+ | Storage | **0.5 GB** / project |
65
+ | Autoscaling | Up to 2 CU |
66
+
67
+ Hitting CU-hours or storage **suspends compute** until the next billing period or an
68
+ upgrade. Always-on production needs Launch/Scale with scale-to-zero disabled.
69
+
70
+ ## Real gotcha — cold start
71
+
72
+ After scale-to-zero, the first query pays a wake-up (hundreds of ms to a few seconds).
73
+ Health checks that expect sub-100ms on an idle Free project will flap. Paid plans can
74
+ disable scale-to-zero; Free cannot.
75
+
76
+ ## Troubleshooting
77
+
78
+ <Accordions>
79
+ <Accordion title="remaining connection slots are reserved / pooler wait timeout">
80
+
81
+ Too many **direct** connections, or pooler server pool exhausted for your compute size.
82
+ Move runtime traffic to the `-pooler` hostname; keep a small number of direct admin
83
+ sessions. Neon reserves connections for the superuser account on each compute size.
84
+
85
+ </Accordion>
86
+ <Accordion title='permission denied to create extension "vector"'>
87
+
88
+ The role is not a Console-created / `neon_superuser` member. Re-run as `neondb_owner` (or
89
+ another Console role), or grant appropriately — raw SQL roles start with public-schema
90
+ privileges only.
91
+
92
+ </Accordion>
93
+ </Accordions>
94
+
95
+ ## Learn more
96
+
97
+ - [Postgres (image)](/docs/recipes/postgres) — self-hosted peer
98
+ - [Store · Index](/docs/elements/store#index) — `pgvector` usage
99
+ - [PgDog](/docs/recipes/pgdog) — when you self-host pooling instead
100
+
101
+ ## Next
102
+
103
+ <Cards>
104
+ <Card
105
+ title="Supabase"
106
+ description="Another managed Postgres option."
107
+ href="/docs/providers/supabase"
108
+ />
109
+ <Card
110
+ title="CockroachDB"
111
+ description="Distributed SQL alternative."
112
+ href="/docs/providers/cockroachdb"
113
+ />
114
+ <Card title="PgDog" description="Self-hosted pooler comparison." href="/docs/recipes/pgdog" />
115
+ </Cards>
@@ -0,0 +1,93 @@
1
+ ---
2
+ title: "Redis Cloud"
3
+ description: "Redis Ltd. managed Redis — Configuration tab endpoints, Connect wizard, rediss://, dynamic vs static endpoints."
4
+ icon: "Zap"
5
+ source: "docs/spec/unified-theory.md"
6
+ ---
7
+
8
+ Redis Cloud is Redis Ltd.'s first-party managed service — RESP over TCP/TLS, no separate
9
+ REST layer. `drivers.store.kv` stays `redis`.
10
+
11
+ <Callout title="The one rule">
12
+ Use `rediss://` (double **s**) with the endpoint from **Configuration** or the **Connect** wizard.
13
+ Prefer **dynamic** endpoints when both are offered.
14
+ </Callout>
15
+
16
+ ## Find credentials (current console)
17
+
18
+ 1. Open Redis Cloud → your **database**.
19
+ 2. Open the **Configuration** tab:
20
+ - **Essentials:** endpoint under **Access**
21
+ - **Pro:** endpoint under **General** (expand **Dynamic endpoints** if shown)
22
+ 3. Credentials:
23
+ - **Essentials:** **Default user → Configure** → eye icon for password (`default`)
24
+ - **Pro:** **Security** section on Configuration → eye icon for default user password
25
+ 4. Or click **Connect** → connection wizard → copy the ready-made client / `redis-cli`
26
+ snippet (fills host, port, user, password).
27
+
28
+ ```bash title="process env"
29
+ REDIS_URL=rediss://default:PASSWORD@redis-12345.c1.region.cloud.redislabs.com:12345
30
+ # or dynamic: …@horse-battery-staple-12345.db.redis.io:…
31
+ ```
32
+
33
+ Port is a **per-database high port**, not always `6379` — copy it from the panel.
34
+
35
+ ## Production guidance
36
+
37
+ | Topic | Guidance |
38
+ | ------------- | --------------------------------------------------------------------------------- |
39
+ | TLS | Public endpoints expect TLS → `rediss://` |
40
+ | Endpoint type | **Dynamic** (`*.db.redis.io`) can be redirected later; static `redis-….c…` cannot |
41
+ | Private | Pro private endpoint needs VPC peering / PrivateLink / PSC first |
42
+ | Modules | RediSearch / RedisJSON optional — unused by oke's KV driver |
43
+ | Port | Per-database high port from Configuration — never assume `6379` |
44
+
45
+ Essentials vs Pro panels differ (Access vs General), but **Connect** always opens the
46
+ wizard with a filled client snippet — prefer that when the Configuration layout feels
47
+ unfamiliar after a UI refresh.
48
+
49
+ ## Real gotcha — dynamic vs static
50
+
51
+ Apps hard-coded to a **static** `redis-….c…` host cannot follow a later “redirect
52
+ dynamic endpoint” migration. Copy the **dynamic** endpoint from Configuration when both
53
+ exist so you can repoint without code changes.
54
+
55
+ ## Troubleshooting
56
+
57
+ <Accordions>
58
+ <Accordion title="NOAUTH / WRONGPASS">
59
+
60
+ Password not in the URL, or default user disabled under RBAC. Format:
61
+ `rediss://default:PASSWORD@host:port`. If default user is off, use a data-access role
62
+ username/password from Access Control.
63
+
64
+ </Accordion>
65
+ <Accordion title="Connection timeout to public endpoint">
66
+
67
+ Pro databases can block public endpoints. Use the private endpoint after peering, or
68
+ re-enable public access in security settings.
69
+
70
+ </Accordion>
71
+ </Accordions>
72
+
73
+ ## Learn more
74
+
75
+ - [Redis (image)](/docs/recipes/redis) — self-hosted peer
76
+ - [Store · KV](/docs/elements/store#kv) — TTL physics
77
+ - [Upstash](/docs/providers/upstash) — serverless alternative
78
+
79
+ ## Next
80
+
81
+ <Cards>
82
+ <Card
83
+ title="Upstash"
84
+ description="Serverless-friendly alternative."
85
+ href="/docs/providers/upstash"
86
+ />
87
+ <Card
88
+ title="ElastiCache"
89
+ description="AWS-native alternative."
90
+ href="/docs/providers/elasticache"
91
+ />
92
+ <Card title="Neon" description="Managed SQL-side pair." href="/docs/providers/neon" />
93
+ </Cards>
@@ -0,0 +1,117 @@
1
+ ---
2
+ title: "Supabase"
3
+ description: "Managed Postgres — Connect button modes, transaction :6543 vs direct :5432, IPv6, free-tier pause."
4
+ icon: "Database"
5
+ source: "docs/spec/unified-theory.md"
6
+ ---
7
+
8
+ Supabase wraps Postgres with Auth, Storage, Realtime, and generated APIs. oke only needs
9
+ the Postgres connection underneath — `drivers.store.sql` stays `postgres`.
10
+
11
+ <Callout title="The one rule">
12
+ Use the dashboard **Connect** button and pick the mode that matches your runtime — Transaction
13
+ pooler for serverless, Direct for migrations. Do not guess ports.
14
+ </Callout>
15
+
16
+ ## Find credentials (current dashboard)
17
+
18
+ 1. Open your project in [supabase.com/dashboard](https://supabase.com/dashboard).
19
+ 2. Click **Connect** in the project top bar
20
+ (`?showConnect=true` on the project URL).
21
+ 3. Choose a method:
22
+ - **Transaction pooler** — `aws-[region].pooler.supabase.com:6543` (Supavisor
23
+ transaction mode)
24
+ - **Session pooler** — same host, port **5432** (IPv4-friendly persistent clients)
25
+ - **Direct connection** — `db.[project-ref].supabase.co:5432`
26
+ 4. Copy the URI; substitute the database password from **Project Settings → Database**
27
+ if the string still shows a placeholder.
28
+
29
+ Alternate path: **Project Settings → Database** → connection string / connection info
30
+ panels (same values as Connect).
31
+
32
+ ```bash title="process env"
33
+ # Serverless / many short-lived clients
34
+ DATABASE_URL=postgres://postgres.[ref]:…@aws-0-[region].pooler.supabase.com:6543/postgres
35
+
36
+ # Migrations / pg_dump / long session features
37
+ # Direct (IPv6 by default on Free unless IPv4 add-on):
38
+ # DATABASE_URL=postgres://postgres:…@db.[ref].supabase.co:5432/postgres
39
+ ```
40
+
41
+ ## Pooled vs direct
42
+
43
+ | Mode | Host:port | Best for |
44
+ | -------------------------- | --------------------------- | ---------------------------------------------- |
45
+ | Transaction (Supavisor) | `…pooler.supabase.com:6543` | Serverless / edge — default app `DATABASE_URL` |
46
+ | Session (Supavisor) | `…pooler.supabase.com:5432` | Persistent backends on **IPv4-only** networks |
47
+ | Direct | `db.[ref].supabase.co:5432` | Migrations, `pg_dump`, replication |
48
+ | Dedicated PgBouncer (paid) | `db.[ref].supabase.co:6543` | High-performance pooled traffic on paid tiers |
49
+
50
+ **Do not stack** [PgDog](/docs/recipes/pgdog) on top of Supavisor. Transaction mode does
51
+ not support prepared statements — turn them off in the client if you see related errors.
52
+
53
+ **IPv6 gotcha:** Direct (and dedicated pooler) are IPv6 unless you buy the IPv4 add-on.
54
+ IPv4-only app hosts must use the shared pooler hostnames.
55
+
56
+ ## pgvector
57
+
58
+ Available on every plan. Enable from the dashboard **Database → Extensions** (or
59
+ `CREATE EXTENSION vector;`). Same `store.index` + `pgvector` driver path as self-hosted
60
+ Postgres.
61
+
62
+ ## Free tier — breaks real production
63
+
64
+ | Limit | Free |
65
+ | -------------------------- | ------------------------------------------------------ |
66
+ | Inactivity pause | **7 days** without enough DB activity → project paused |
67
+ | Active projects | **2** |
68
+ | DB size | **500 MB** |
69
+ | Restore window after pause | Finite (platform retention) |
70
+
71
+ Paused projects wake slowly and will fail uptime checks. Paid plans do not auto-pause.
72
+ Do not run user-facing production on Free.
73
+
74
+ ## Real gotcha — Connect port mix-ups
75
+
76
+ Since Feb 2025, **6543 is transaction-only** on the shared pooler; session mode is
77
+ **5432** on the pooler host. An old snippet that assumed “6543 = session” will break
78
+ session features or auth in subtle ways — re-copy from **Connect** today.
79
+
80
+ ## Troubleshooting
81
+
82
+ <Accordions>
83
+ <Accordion title="Connection refused / timeout to db.[ref].supabase.co">
84
+
85
+ Often IPv4 client → IPv6-only direct endpoint. Switch `DATABASE_URL` to the **Session**
86
+ or **Transaction** pooler host (`pooler.supabase.com`), or enable the IPv4 add-on.
87
+
88
+ </Accordion>
89
+ <Accordion title="Project paused after a quiet week">
90
+
91
+ Free-tier inactivity pause. Restore from the dashboard, then upgrade or keep real DB
92
+ traffic above the pause threshold. Dashboard page views alone may not count.
93
+
94
+ </Accordion>
95
+ </Accordions>
96
+
97
+ ## Learn more
98
+
99
+ - [Supabase recipe](/docs/recipes/supabase-docker) — Postgres image only, no platform
100
+ - [Store · Index](/docs/elements/store#index) — `pgvector`
101
+ - [Environment variables](/docs/reference/environment-variables) — `DATABASE_URL`
102
+
103
+ ## Next
104
+
105
+ <Cards>
106
+ <Card
107
+ title="Supabase (image)"
108
+ description="Run just the Postgres image."
109
+ href="/docs/recipes/supabase-docker"
110
+ />
111
+ <Card title="Neon" description="Serverless alternative." href="/docs/providers/neon" />
112
+ <Card
113
+ title="YugabyteDB"
114
+ description="Distributed Apache-2.0 option."
115
+ href="/docs/providers/yugabytedb"
116
+ />
117
+ </Cards>
@@ -0,0 +1,91 @@
1
+ ---
2
+ title: "Upstash"
3
+ description: "Serverless Redis — Details tab TCP endpoint vs REST URL/token; oke needs rediss:// only."
4
+ icon: "Zap"
5
+ source: "docs/spec/unified-theory.md"
6
+ ---
7
+
8
+ Upstash exposes the **same database** two ways: Redis protocol over TLS (TCP) and a
9
+ separate HTTP REST API. oke's `redis` driver speaks **TCP only**.
10
+
11
+ <Callout title="The one rule">
12
+ From the database **Details** / **Connect** panel, copy the **Redis** / TCP connection
13
+ (`rediss://…`), never `UPSTASH_REDIS_REST_URL` / `UPSTASH_REDIS_REST_TOKEN`.
14
+ </Callout>
15
+
16
+ ## Find credentials (current console)
17
+
18
+ 1. Open [console.upstash.com](https://console.upstash.com) → **Redis** → your database.
19
+ 2. On the database page (**Details**):
20
+ - **Endpoint**, **Port**, **Password** (token) for TCP clients
21
+ - Ready-made `redis-cli` / `rediss://` snippets under **Connect** / **Redis**
22
+ 3. Ignore the **REST** tab values (`UPSTASH_REDIS_REST_URL`,
23
+ `UPSTASH_REDIS_REST_TOKEN`) for oke — those are for `@upstash/redis` / HTTP only.
24
+
25
+ ```bash title="process env"
26
+ REDIS_URL=rediss://default:PASSWORD@usw1-example-12345.upstash.io:6379
27
+ ```
28
+
29
+ TLS is mandatory — `redis://` without TLS fails.
30
+
31
+ ## Production guidance
32
+
33
+ | Topic | Guidance |
34
+ | ----------- | --------------------------------------------------------------------------- |
35
+ | Transport | TCP `rediss://` for Bun / long-running servers |
36
+ | REST | Edge/serverless SDKs only — **not** wired to `fx.store` |
37
+ | Pricing | Per-request — watch command fan-out in hot KV paths |
38
+ | Eviction | Plan max size / eviction; serverless still has quotas |
39
+ | Consistency | Global replication options are product-specific — confirm region in Details |
40
+
41
+ Do not put [PgDog](/docs/recipes/pgdog)-style thinking on Redis: there is no separate
42
+ “pooled hostname” toggle. Connection count pressure shows up as Upstash plan limits /
43
+ timeouts, not a Neon-style `-pooler` suffix.
44
+
45
+ When debugging, open **Details** and confirm you are reading the **Redis** column, not
46
+ the REST env var block that sits beside it on the same page.
47
+
48
+ ## Real gotcha — REST token ≠ Redis password
49
+
50
+ Using `UPSTASH_REDIS_REST_TOKEN` inside a `rediss://` URL (or the reverse) yields
51
+ `WRONGPASS` / `NOAUTH`. REST token and TCP password are different credentials on the
52
+ same console page — copy from the **Redis/TCP** section.
53
+
54
+ ## Troubleshooting
55
+
56
+ <Accordions>
57
+ <Accordion title="WRONGPASS invalid or missing auth token">
58
+
59
+ Often a REST token pasted into a TCP client. Re-copy **Password** from Details for
60
+ Redis protocol, build `rediss://:PASSWORD@ENDPOINT:PORT`.
61
+
62
+ </Accordion>
63
+ <Accordion title="NOAUTH Authentication required">
64
+
65
+ Password missing from the URL. ioredis-style URLs need the colon before the password:
66
+ `rediss://:PASSWORD@host:port`.
67
+
68
+ </Accordion>
69
+ </Accordions>
70
+
71
+ ## Learn more
72
+
73
+ - [Redis (image)](/docs/recipes/redis)
74
+ - [Redis Cloud](/docs/providers/redis-cloud) — fixed-instance alternative
75
+ - [Store · KV](/docs/elements/store#kv)
76
+
77
+ ## Next
78
+
79
+ <Cards>
80
+ <Card
81
+ title="Redis Cloud"
82
+ description="Fixed-instance alternative."
83
+ href="/docs/providers/redis-cloud"
84
+ />
85
+ <Card
86
+ title="Dragonfly Cloud"
87
+ description="Another managed option."
88
+ href="/docs/providers/dragonfly-cloud"
89
+ />
90
+ <Card title="Neon" description="Managed SQL-side pair." href="/docs/providers/neon" />
91
+ </Cards>