pi-cloudflare 0.1.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 (410) hide show
  1. package/LICENSE +674 -0
  2. package/README.md +67 -0
  3. package/bin/setup.mjs +103 -0
  4. package/dist/auth-flow.d.ts +15 -0
  5. package/dist/auth-flow.d.ts.map +1 -0
  6. package/dist/auth-flow.js +90 -0
  7. package/dist/auth-flow.js.map +1 -0
  8. package/dist/client.d.ts +18 -0
  9. package/dist/client.d.ts.map +1 -0
  10. package/dist/client.js +47 -0
  11. package/dist/client.js.map +1 -0
  12. package/dist/config.d.ts +13 -0
  13. package/dist/config.d.ts.map +1 -0
  14. package/dist/config.js +10 -0
  15. package/dist/config.js.map +1 -0
  16. package/dist/index.d.ts +24 -0
  17. package/dist/index.d.ts.map +1 -0
  18. package/dist/index.js +109 -0
  19. package/dist/index.js.map +1 -0
  20. package/dist/oauth.d.ts +44 -0
  21. package/dist/oauth.d.ts.map +1 -0
  22. package/dist/oauth.js +135 -0
  23. package/dist/oauth.js.map +1 -0
  24. package/dist/proxy.d.ts +29 -0
  25. package/dist/proxy.d.ts.map +1 -0
  26. package/dist/proxy.js +39 -0
  27. package/dist/proxy.js.map +1 -0
  28. package/dist/servers.d.ts +19 -0
  29. package/dist/servers.d.ts.map +1 -0
  30. package/dist/servers.js +40 -0
  31. package/dist/servers.js.map +1 -0
  32. package/dist/token-store.d.ts +23 -0
  33. package/dist/token-store.d.ts.map +1 -0
  34. package/dist/token-store.js +47 -0
  35. package/dist/token-store.js.map +1 -0
  36. package/package.json +67 -0
  37. package/skills/agents-sdk/SKILL.md +221 -0
  38. package/skills/agents-sdk/references/browse-the-web.md +63 -0
  39. package/skills/agents-sdk/references/callable.md +92 -0
  40. package/skills/agents-sdk/references/client-sdk.md +110 -0
  41. package/skills/agents-sdk/references/codemode.md +110 -0
  42. package/skills/agents-sdk/references/configuration.md +72 -0
  43. package/skills/agents-sdk/references/durable-execution.md +51 -0
  44. package/skills/agents-sdk/references/email.md +146 -0
  45. package/skills/agents-sdk/references/human-in-the-loop.md +67 -0
  46. package/skills/agents-sdk/references/mcp.md +188 -0
  47. package/skills/agents-sdk/references/observability.md +44 -0
  48. package/skills/agents-sdk/references/queue-retries.md +79 -0
  49. package/skills/agents-sdk/references/routing.md +75 -0
  50. package/skills/agents-sdk/references/server-driven-messages.md +63 -0
  51. package/skills/agents-sdk/references/state-scheduling.md +171 -0
  52. package/skills/agents-sdk/references/streaming-chat.md +198 -0
  53. package/skills/agents-sdk/references/think.md +112 -0
  54. package/skills/agents-sdk/references/voice.md +68 -0
  55. package/skills/agents-sdk/references/webhooks-push.md +86 -0
  56. package/skills/agents-sdk/references/workflows.md +132 -0
  57. package/skills/cloudflare/SKILL.md +248 -0
  58. package/skills/cloudflare/references/agents-sdk/README.md +89 -0
  59. package/skills/cloudflare/references/agents-sdk/api.md +190 -0
  60. package/skills/cloudflare/references/agents-sdk/configuration.md +182 -0
  61. package/skills/cloudflare/references/agents-sdk/gotchas.md +158 -0
  62. package/skills/cloudflare/references/agents-sdk/patterns.md +192 -0
  63. package/skills/cloudflare/references/ai-gateway/README.md +175 -0
  64. package/skills/cloudflare/references/ai-gateway/configuration.md +111 -0
  65. package/skills/cloudflare/references/ai-gateway/dynamic-routing.md +82 -0
  66. package/skills/cloudflare/references/ai-gateway/features.md +96 -0
  67. package/skills/cloudflare/references/ai-gateway/sdk-integration.md +114 -0
  68. package/skills/cloudflare/references/ai-gateway/troubleshooting.md +88 -0
  69. package/skills/cloudflare/references/ai-search/README.md +138 -0
  70. package/skills/cloudflare/references/ai-search/api.md +87 -0
  71. package/skills/cloudflare/references/ai-search/configuration.md +88 -0
  72. package/skills/cloudflare/references/ai-search/gotchas.md +81 -0
  73. package/skills/cloudflare/references/ai-search/patterns.md +85 -0
  74. package/skills/cloudflare/references/analytics-engine/README.md +94 -0
  75. package/skills/cloudflare/references/analytics-engine/api.md +112 -0
  76. package/skills/cloudflare/references/analytics-engine/configuration.md +112 -0
  77. package/skills/cloudflare/references/analytics-engine/gotchas.md +85 -0
  78. package/skills/cloudflare/references/analytics-engine/patterns.md +83 -0
  79. package/skills/cloudflare/references/api/README.md +66 -0
  80. package/skills/cloudflare/references/api/api.md +204 -0
  81. package/skills/cloudflare/references/api/configuration.md +160 -0
  82. package/skills/cloudflare/references/api/gotchas.md +225 -0
  83. package/skills/cloudflare/references/api/patterns.md +204 -0
  84. package/skills/cloudflare/references/api-shield/README.md +44 -0
  85. package/skills/cloudflare/references/api-shield/api.md +141 -0
  86. package/skills/cloudflare/references/api-shield/configuration.md +192 -0
  87. package/skills/cloudflare/references/api-shield/gotchas.md +125 -0
  88. package/skills/cloudflare/references/api-shield/patterns.md +180 -0
  89. package/skills/cloudflare/references/argo-smart-routing/README.md +90 -0
  90. package/skills/cloudflare/references/argo-smart-routing/api.md +240 -0
  91. package/skills/cloudflare/references/argo-smart-routing/configuration.md +197 -0
  92. package/skills/cloudflare/references/argo-smart-routing/gotchas.md +111 -0
  93. package/skills/cloudflare/references/argo-smart-routing/patterns.md +104 -0
  94. package/skills/cloudflare/references/artifacts/README.md +79 -0
  95. package/skills/cloudflare/references/artifacts/api.md +128 -0
  96. package/skills/cloudflare/references/artifacts/configuration.md +92 -0
  97. package/skills/cloudflare/references/bindings/README.md +122 -0
  98. package/skills/cloudflare/references/bindings/api.md +203 -0
  99. package/skills/cloudflare/references/bindings/configuration.md +188 -0
  100. package/skills/cloudflare/references/bindings/gotchas.md +208 -0
  101. package/skills/cloudflare/references/bindings/patterns.md +200 -0
  102. package/skills/cloudflare/references/bot-management/README.md +94 -0
  103. package/skills/cloudflare/references/bot-management/api.md +169 -0
  104. package/skills/cloudflare/references/bot-management/configuration.md +163 -0
  105. package/skills/cloudflare/references/bot-management/gotchas.md +114 -0
  106. package/skills/cloudflare/references/bot-management/patterns.md +182 -0
  107. package/skills/cloudflare/references/browser-rendering/README.md +78 -0
  108. package/skills/cloudflare/references/browser-rendering/api.md +108 -0
  109. package/skills/cloudflare/references/browser-rendering/configuration.md +78 -0
  110. package/skills/cloudflare/references/browser-rendering/gotchas.md +88 -0
  111. package/skills/cloudflare/references/browser-rendering/patterns.md +91 -0
  112. package/skills/cloudflare/references/c3/README.md +111 -0
  113. package/skills/cloudflare/references/c3/api.md +71 -0
  114. package/skills/cloudflare/references/c3/configuration.md +81 -0
  115. package/skills/cloudflare/references/c3/gotchas.md +92 -0
  116. package/skills/cloudflare/references/c3/patterns.md +82 -0
  117. package/skills/cloudflare/references/cache-reserve/README.md +147 -0
  118. package/skills/cloudflare/references/cache-reserve/api.md +194 -0
  119. package/skills/cloudflare/references/cache-reserve/configuration.md +169 -0
  120. package/skills/cloudflare/references/cache-reserve/gotchas.md +132 -0
  121. package/skills/cloudflare/references/cache-reserve/patterns.md +197 -0
  122. package/skills/cloudflare/references/containers/README.md +85 -0
  123. package/skills/cloudflare/references/containers/api.md +187 -0
  124. package/skills/cloudflare/references/containers/configuration.md +188 -0
  125. package/skills/cloudflare/references/containers/gotchas.md +178 -0
  126. package/skills/cloudflare/references/containers/patterns.md +202 -0
  127. package/skills/cloudflare/references/cron-triggers/README.md +99 -0
  128. package/skills/cloudflare/references/cron-triggers/api.md +196 -0
  129. package/skills/cloudflare/references/cron-triggers/configuration.md +180 -0
  130. package/skills/cloudflare/references/cron-triggers/gotchas.md +199 -0
  131. package/skills/cloudflare/references/cron-triggers/patterns.md +190 -0
  132. package/skills/cloudflare/references/d1/README.md +133 -0
  133. package/skills/cloudflare/references/d1/api.md +196 -0
  134. package/skills/cloudflare/references/d1/configuration.md +191 -0
  135. package/skills/cloudflare/references/d1/gotchas.md +98 -0
  136. package/skills/cloudflare/references/d1/patterns.md +189 -0
  137. package/skills/cloudflare/references/ddos/README.md +41 -0
  138. package/skills/cloudflare/references/ddos/api.md +164 -0
  139. package/skills/cloudflare/references/ddos/configuration.md +93 -0
  140. package/skills/cloudflare/references/ddos/gotchas.md +107 -0
  141. package/skills/cloudflare/references/ddos/patterns.md +174 -0
  142. package/skills/cloudflare/references/do-storage/README.md +75 -0
  143. package/skills/cloudflare/references/do-storage/api.md +102 -0
  144. package/skills/cloudflare/references/do-storage/configuration.md +112 -0
  145. package/skills/cloudflare/references/do-storage/gotchas.md +150 -0
  146. package/skills/cloudflare/references/do-storage/patterns.md +194 -0
  147. package/skills/cloudflare/references/do-storage/testing.md +183 -0
  148. package/skills/cloudflare/references/durable-objects/README.md +185 -0
  149. package/skills/cloudflare/references/durable-objects/api.md +187 -0
  150. package/skills/cloudflare/references/durable-objects/configuration.md +160 -0
  151. package/skills/cloudflare/references/durable-objects/gotchas.md +197 -0
  152. package/skills/cloudflare/references/durable-objects/patterns.md +201 -0
  153. package/skills/cloudflare/references/email-routing/README.md +89 -0
  154. package/skills/cloudflare/references/email-routing/api.md +195 -0
  155. package/skills/cloudflare/references/email-routing/configuration.md +186 -0
  156. package/skills/cloudflare/references/email-routing/gotchas.md +196 -0
  157. package/skills/cloudflare/references/email-routing/patterns.md +229 -0
  158. package/skills/cloudflare/references/email-workers/README.md +151 -0
  159. package/skills/cloudflare/references/email-workers/api.md +237 -0
  160. package/skills/cloudflare/references/email-workers/configuration.md +112 -0
  161. package/skills/cloudflare/references/email-workers/gotchas.md +125 -0
  162. package/skills/cloudflare/references/email-workers/patterns.md +102 -0
  163. package/skills/cloudflare/references/flagship/README.md +59 -0
  164. package/skills/cloudflare/references/flagship/api.md +390 -0
  165. package/skills/cloudflare/references/flagship/configuration.md +202 -0
  166. package/skills/cloudflare/references/flagship/gotchas.md +178 -0
  167. package/skills/cloudflare/references/flagship/patterns.md +469 -0
  168. package/skills/cloudflare/references/graphql-api/README.md +147 -0
  169. package/skills/cloudflare/references/graphql-api/api.md +175 -0
  170. package/skills/cloudflare/references/graphql-api/configuration.md +118 -0
  171. package/skills/cloudflare/references/graphql-api/gotchas.md +110 -0
  172. package/skills/cloudflare/references/graphql-api/patterns.md +225 -0
  173. package/skills/cloudflare/references/hyperdrive/README.md +82 -0
  174. package/skills/cloudflare/references/hyperdrive/api.md +143 -0
  175. package/skills/cloudflare/references/hyperdrive/configuration.md +159 -0
  176. package/skills/cloudflare/references/hyperdrive/gotchas.md +77 -0
  177. package/skills/cloudflare/references/hyperdrive/patterns.md +190 -0
  178. package/skills/cloudflare/references/images/README.md +61 -0
  179. package/skills/cloudflare/references/images/api.md +96 -0
  180. package/skills/cloudflare/references/images/configuration.md +211 -0
  181. package/skills/cloudflare/references/images/gotchas.md +99 -0
  182. package/skills/cloudflare/references/images/patterns.md +115 -0
  183. package/skills/cloudflare/references/kv/README.md +89 -0
  184. package/skills/cloudflare/references/kv/api.md +160 -0
  185. package/skills/cloudflare/references/kv/configuration.md +144 -0
  186. package/skills/cloudflare/references/kv/gotchas.md +131 -0
  187. package/skills/cloudflare/references/kv/patterns.md +196 -0
  188. package/skills/cloudflare/references/miniflare/README.md +105 -0
  189. package/skills/cloudflare/references/miniflare/api.md +187 -0
  190. package/skills/cloudflare/references/miniflare/configuration.md +173 -0
  191. package/skills/cloudflare/references/miniflare/gotchas.md +160 -0
  192. package/skills/cloudflare/references/miniflare/patterns.md +181 -0
  193. package/skills/cloudflare/references/network-interconnect/README.md +99 -0
  194. package/skills/cloudflare/references/network-interconnect/api.md +199 -0
  195. package/skills/cloudflare/references/network-interconnect/configuration.md +114 -0
  196. package/skills/cloudflare/references/network-interconnect/gotchas.md +165 -0
  197. package/skills/cloudflare/references/network-interconnect/patterns.md +166 -0
  198. package/skills/cloudflare/references/observability/README.md +88 -0
  199. package/skills/cloudflare/references/observability/api.md +164 -0
  200. package/skills/cloudflare/references/observability/configuration.md +169 -0
  201. package/skills/cloudflare/references/observability/gotchas.md +115 -0
  202. package/skills/cloudflare/references/observability/patterns.md +105 -0
  203. package/skills/cloudflare/references/pages/README.md +88 -0
  204. package/skills/cloudflare/references/pages/api.md +204 -0
  205. package/skills/cloudflare/references/pages/configuration.md +201 -0
  206. package/skills/cloudflare/references/pages/gotchas.md +203 -0
  207. package/skills/cloudflare/references/pages/patterns.md +204 -0
  208. package/skills/cloudflare/references/pages-functions/README.md +98 -0
  209. package/skills/cloudflare/references/pages-functions/api.md +143 -0
  210. package/skills/cloudflare/references/pages-functions/configuration.md +122 -0
  211. package/skills/cloudflare/references/pages-functions/gotchas.md +94 -0
  212. package/skills/cloudflare/references/pages-functions/patterns.md +137 -0
  213. package/skills/cloudflare/references/pipelines/README.md +90 -0
  214. package/skills/cloudflare/references/pipelines/api.md +124 -0
  215. package/skills/cloudflare/references/pipelines/configuration.md +155 -0
  216. package/skills/cloudflare/references/pipelines/gotchas.md +58 -0
  217. package/skills/cloudflare/references/pipelines/patterns.md +130 -0
  218. package/skills/cloudflare/references/pulumi/README.md +100 -0
  219. package/skills/cloudflare/references/pulumi/api.md +200 -0
  220. package/skills/cloudflare/references/pulumi/configuration.md +198 -0
  221. package/skills/cloudflare/references/pulumi/gotchas.md +181 -0
  222. package/skills/cloudflare/references/pulumi/patterns.md +191 -0
  223. package/skills/cloudflare/references/queues/README.md +96 -0
  224. package/skills/cloudflare/references/queues/api.md +206 -0
  225. package/skills/cloudflare/references/queues/configuration.md +144 -0
  226. package/skills/cloudflare/references/queues/gotchas.md +206 -0
  227. package/skills/cloudflare/references/queues/patterns.md +220 -0
  228. package/skills/cloudflare/references/r2/README.md +95 -0
  229. package/skills/cloudflare/references/r2/api.md +200 -0
  230. package/skills/cloudflare/references/r2/configuration.md +165 -0
  231. package/skills/cloudflare/references/r2/gotchas.md +190 -0
  232. package/skills/cloudflare/references/r2/patterns.md +193 -0
  233. package/skills/cloudflare/references/r2-data-catalog/README.md +75 -0
  234. package/skills/cloudflare/references/r2-data-catalog/api.md +122 -0
  235. package/skills/cloudflare/references/r2-data-catalog/configuration.md +98 -0
  236. package/skills/cloudflare/references/r2-data-catalog/gotchas.md +55 -0
  237. package/skills/cloudflare/references/r2-data-catalog/patterns.md +122 -0
  238. package/skills/cloudflare/references/r2-sql/README.md +64 -0
  239. package/skills/cloudflare/references/r2-sql/api.md +121 -0
  240. package/skills/cloudflare/references/r2-sql/configuration.md +50 -0
  241. package/skills/cloudflare/references/r2-sql/gotchas.md +39 -0
  242. package/skills/cloudflare/references/r2-sql/patterns.md +118 -0
  243. package/skills/cloudflare/references/realtime-sfu/README.md +65 -0
  244. package/skills/cloudflare/references/realtime-sfu/api.md +158 -0
  245. package/skills/cloudflare/references/realtime-sfu/configuration.md +137 -0
  246. package/skills/cloudflare/references/realtime-sfu/gotchas.md +133 -0
  247. package/skills/cloudflare/references/realtime-sfu/patterns.md +174 -0
  248. package/skills/cloudflare/references/realtimekit/README.md +113 -0
  249. package/skills/cloudflare/references/realtimekit/api.md +212 -0
  250. package/skills/cloudflare/references/realtimekit/configuration.md +203 -0
  251. package/skills/cloudflare/references/realtimekit/gotchas.md +169 -0
  252. package/skills/cloudflare/references/realtimekit/patterns.md +223 -0
  253. package/skills/cloudflare/references/sandbox/README.md +96 -0
  254. package/skills/cloudflare/references/sandbox/api.md +198 -0
  255. package/skills/cloudflare/references/sandbox/configuration.md +143 -0
  256. package/skills/cloudflare/references/sandbox/gotchas.md +194 -0
  257. package/skills/cloudflare/references/sandbox/patterns.md +201 -0
  258. package/skills/cloudflare/references/secrets-store/README.md +74 -0
  259. package/skills/cloudflare/references/secrets-store/api.md +200 -0
  260. package/skills/cloudflare/references/secrets-store/configuration.md +185 -0
  261. package/skills/cloudflare/references/secrets-store/gotchas.md +97 -0
  262. package/skills/cloudflare/references/secrets-store/patterns.md +207 -0
  263. package/skills/cloudflare/references/smart-placement/README.md +138 -0
  264. package/skills/cloudflare/references/smart-placement/api.md +183 -0
  265. package/skills/cloudflare/references/smart-placement/configuration.md +196 -0
  266. package/skills/cloudflare/references/smart-placement/gotchas.md +174 -0
  267. package/skills/cloudflare/references/smart-placement/patterns.md +183 -0
  268. package/skills/cloudflare/references/snippets/README.md +68 -0
  269. package/skills/cloudflare/references/snippets/api.md +198 -0
  270. package/skills/cloudflare/references/snippets/configuration.md +227 -0
  271. package/skills/cloudflare/references/snippets/gotchas.md +86 -0
  272. package/skills/cloudflare/references/snippets/patterns.md +135 -0
  273. package/skills/cloudflare/references/spectrum/README.md +52 -0
  274. package/skills/cloudflare/references/spectrum/api.md +181 -0
  275. package/skills/cloudflare/references/spectrum/configuration.md +194 -0
  276. package/skills/cloudflare/references/spectrum/gotchas.md +145 -0
  277. package/skills/cloudflare/references/spectrum/patterns.md +196 -0
  278. package/skills/cloudflare/references/static-assets/README.md +65 -0
  279. package/skills/cloudflare/references/static-assets/api.md +199 -0
  280. package/skills/cloudflare/references/static-assets/configuration.md +186 -0
  281. package/skills/cloudflare/references/static-assets/gotchas.md +162 -0
  282. package/skills/cloudflare/references/static-assets/patterns.md +189 -0
  283. package/skills/cloudflare/references/stream/README.md +114 -0
  284. package/skills/cloudflare/references/stream/api-live.md +195 -0
  285. package/skills/cloudflare/references/stream/api.md +199 -0
  286. package/skills/cloudflare/references/stream/configuration.md +141 -0
  287. package/skills/cloudflare/references/stream/gotchas.md +130 -0
  288. package/skills/cloudflare/references/stream/patterns.md +184 -0
  289. package/skills/cloudflare/references/tail-workers/README.md +89 -0
  290. package/skills/cloudflare/references/tail-workers/api.md +200 -0
  291. package/skills/cloudflare/references/tail-workers/configuration.md +176 -0
  292. package/skills/cloudflare/references/tail-workers/gotchas.md +192 -0
  293. package/skills/cloudflare/references/tail-workers/patterns.md +180 -0
  294. package/skills/cloudflare/references/terraform/README.md +102 -0
  295. package/skills/cloudflare/references/terraform/api.md +178 -0
  296. package/skills/cloudflare/references/terraform/configuration.md +197 -0
  297. package/skills/cloudflare/references/terraform/gotchas.md +150 -0
  298. package/skills/cloudflare/references/terraform/patterns.md +174 -0
  299. package/skills/cloudflare/references/tunnel/README.md +129 -0
  300. package/skills/cloudflare/references/tunnel/api.md +193 -0
  301. package/skills/cloudflare/references/tunnel/configuration.md +157 -0
  302. package/skills/cloudflare/references/tunnel/gotchas.md +147 -0
  303. package/skills/cloudflare/references/tunnel/networking.md +168 -0
  304. package/skills/cloudflare/references/tunnel/patterns.md +192 -0
  305. package/skills/cloudflare/references/turn/README.md +82 -0
  306. package/skills/cloudflare/references/turn/api.md +239 -0
  307. package/skills/cloudflare/references/turn/configuration.md +179 -0
  308. package/skills/cloudflare/references/turn/gotchas.md +231 -0
  309. package/skills/cloudflare/references/turn/patterns.md +213 -0
  310. package/skills/cloudflare/references/turnstile/README.md +99 -0
  311. package/skills/cloudflare/references/turnstile/api.md +240 -0
  312. package/skills/cloudflare/references/turnstile/configuration.md +222 -0
  313. package/skills/cloudflare/references/turnstile/gotchas.md +218 -0
  314. package/skills/cloudflare/references/turnstile/patterns.md +193 -0
  315. package/skills/cloudflare/references/vectorize/README.md +133 -0
  316. package/skills/cloudflare/references/vectorize/api.md +88 -0
  317. package/skills/cloudflare/references/vectorize/configuration.md +88 -0
  318. package/skills/cloudflare/references/vectorize/gotchas.md +76 -0
  319. package/skills/cloudflare/references/vectorize/patterns.md +90 -0
  320. package/skills/cloudflare/references/waf/README.md +113 -0
  321. package/skills/cloudflare/references/waf/api.md +202 -0
  322. package/skills/cloudflare/references/waf/configuration.md +203 -0
  323. package/skills/cloudflare/references/waf/gotchas.md +204 -0
  324. package/skills/cloudflare/references/waf/patterns.md +197 -0
  325. package/skills/cloudflare/references/web-analytics/README.md +141 -0
  326. package/skills/cloudflare/references/web-analytics/configuration.md +76 -0
  327. package/skills/cloudflare/references/web-analytics/gotchas.md +82 -0
  328. package/skills/cloudflare/references/web-analytics/integration.md +60 -0
  329. package/skills/cloudflare/references/web-analytics/patterns.md +91 -0
  330. package/skills/cloudflare/references/workerd/README.md +78 -0
  331. package/skills/cloudflare/references/workerd/api.md +185 -0
  332. package/skills/cloudflare/references/workerd/configuration.md +183 -0
  333. package/skills/cloudflare/references/workerd/gotchas.md +139 -0
  334. package/skills/cloudflare/references/workerd/patterns.md +192 -0
  335. package/skills/cloudflare/references/workers/README.md +108 -0
  336. package/skills/cloudflare/references/workers/api.md +195 -0
  337. package/skills/cloudflare/references/workers/configuration.md +185 -0
  338. package/skills/cloudflare/references/workers/frameworks.md +197 -0
  339. package/skills/cloudflare/references/workers/gotchas.md +137 -0
  340. package/skills/cloudflare/references/workers/patterns.md +198 -0
  341. package/skills/cloudflare/references/workers-ai/README.md +197 -0
  342. package/skills/cloudflare/references/workers-ai/api.md +112 -0
  343. package/skills/cloudflare/references/workers-ai/configuration.md +97 -0
  344. package/skills/cloudflare/references/workers-ai/gotchas.md +114 -0
  345. package/skills/cloudflare/references/workers-ai/patterns.md +120 -0
  346. package/skills/cloudflare/references/workers-for-platforms/README.md +89 -0
  347. package/skills/cloudflare/references/workers-for-platforms/api.md +196 -0
  348. package/skills/cloudflare/references/workers-for-platforms/configuration.md +167 -0
  349. package/skills/cloudflare/references/workers-for-platforms/gotchas.md +134 -0
  350. package/skills/cloudflare/references/workers-for-platforms/patterns.md +188 -0
  351. package/skills/cloudflare/references/workers-playground/README.md +127 -0
  352. package/skills/cloudflare/references/workers-playground/api.md +101 -0
  353. package/skills/cloudflare/references/workers-playground/configuration.md +163 -0
  354. package/skills/cloudflare/references/workers-playground/gotchas.md +88 -0
  355. package/skills/cloudflare/references/workers-playground/patterns.md +132 -0
  356. package/skills/cloudflare/references/workers-vpc/README.md +127 -0
  357. package/skills/cloudflare/references/workers-vpc/api.md +202 -0
  358. package/skills/cloudflare/references/workers-vpc/configuration.md +147 -0
  359. package/skills/cloudflare/references/workers-vpc/gotchas.md +167 -0
  360. package/skills/cloudflare/references/workers-vpc/patterns.md +209 -0
  361. package/skills/cloudflare/references/workflows/README.md +77 -0
  362. package/skills/cloudflare/references/workflows/api.md +218 -0
  363. package/skills/cloudflare/references/workflows/configuration.md +152 -0
  364. package/skills/cloudflare/references/workflows/gotchas.md +90 -0
  365. package/skills/cloudflare/references/workflows/patterns.md +175 -0
  366. package/skills/cloudflare/references/wrangler/README.md +135 -0
  367. package/skills/cloudflare/references/wrangler/api.md +188 -0
  368. package/skills/cloudflare/references/wrangler/configuration.md +197 -0
  369. package/skills/cloudflare/references/wrangler/gotchas.md +197 -0
  370. package/skills/cloudflare/references/wrangler/patterns.md +209 -0
  371. package/skills/cloudflare/references/zaraz/IMPLEMENTATION_SUMMARY.md +121 -0
  372. package/skills/cloudflare/references/zaraz/README.md +111 -0
  373. package/skills/cloudflare/references/zaraz/api.md +112 -0
  374. package/skills/cloudflare/references/zaraz/configuration.md +90 -0
  375. package/skills/cloudflare/references/zaraz/gotchas.md +81 -0
  376. package/skills/cloudflare/references/zaraz/patterns.md +74 -0
  377. package/skills/cloudflare-email-service/SKILL.md +103 -0
  378. package/skills/cloudflare-email-service/references/cli-and-mcp.md +125 -0
  379. package/skills/cloudflare-email-service/references/deliverability.md +285 -0
  380. package/skills/cloudflare-email-service/references/rest-api.md +184 -0
  381. package/skills/cloudflare-email-service/references/routing.md +199 -0
  382. package/skills/cloudflare-email-service/references/sending.md +252 -0
  383. package/skills/cloudflare-one/SKILL.md +176 -0
  384. package/skills/cloudflare-one-migrations/SKILL.md +110 -0
  385. package/skills/durable-objects/SKILL.md +186 -0
  386. package/skills/durable-objects/references/rules.md +295 -0
  387. package/skills/durable-objects/references/testing.md +264 -0
  388. package/skills/durable-objects/references/workers.md +346 -0
  389. package/skills/sandbox-migrate-to-next/SKILL.md +185 -0
  390. package/skills/sandbox-next/SKILL.md +91 -0
  391. package/skills/sandbox-next/references/api-quick-ref.md +94 -0
  392. package/skills/sandbox-next/references/examples.md +15 -0
  393. package/skills/sandbox-stable/SKILL.md +110 -0
  394. package/skills/turnstile-spin/README.md +51 -0
  395. package/skills/turnstile-spin/SKILL.md +330 -0
  396. package/skills/turnstile-spin/references/astro.md +199 -0
  397. package/skills/turnstile-spin/references/hugo.md +114 -0
  398. package/skills/turnstile-spin/references/nextjs-app.md +261 -0
  399. package/skills/turnstile-spin/references/nextjs-pages.md +82 -0
  400. package/skills/turnstile-spin/references/sveltekit.md +191 -0
  401. package/skills/turnstile-spin/references/vanilla-html.md +157 -0
  402. package/skills/turnstile-spin/scripts/auth-probe.sh +285 -0
  403. package/skills/turnstile-spin/scripts/persist-skill.sh +114 -0
  404. package/skills/turnstile-spin/scripts/validate.sh +137 -0
  405. package/skills/turnstile-spin/scripts/widget-create.sh +121 -0
  406. package/skills/turnstile-spin/tests/validation.md +62 -0
  407. package/skills/workers-best-practices/SKILL.md +127 -0
  408. package/skills/workers-best-practices/references/review.md +174 -0
  409. package/skills/workers-best-practices/references/rules.md +467 -0
  410. package/skills/wrangler/SKILL.md +922 -0
@@ -0,0 +1,225 @@
1
+ # GraphQL Analytics API Patterns & Best Practices
2
+
3
+ ## Time-Series Queries
4
+
5
+ Use time dimension granularity matching your range (see Best Practices below).
6
+
7
+ ```graphql
8
+ query TrafficTimeSeries($zoneTag: string!, $start: Time!, $end: Time!) {
9
+ viewer {
10
+ zones(filter: { zoneTag: $zoneTag }) {
11
+ httpRequestsAdaptiveGroups(
12
+ filter: { datetime_gt: $start, datetime_lt: $end }
13
+ limit: 1000
14
+ orderBy: [datetimeFiveMinutes_ASC] # or datetimeHour_ASC for longer ranges
15
+ ) {
16
+ count
17
+ dimensions { datetimeFiveMinutes }
18
+ sum { edgeResponseBytes }
19
+ ratio { status4xx status5xx }
20
+ }
21
+ }
22
+ }
23
+ }
24
+ ```
25
+
26
+ ## Top-N Queries
27
+
28
+ ### Top Countries by Request Count
29
+
30
+ ```graphql
31
+ query TopCountries($zoneTag: string!, $start: Time!, $end: Time!) {
32
+ viewer {
33
+ zones(filter: { zoneTag: $zoneTag }) {
34
+ httpRequestsAdaptiveGroups(
35
+ filter: { datetime_gt: $start, datetime_lt: $end }
36
+ limit: 10
37
+ orderBy: [count_DESC]
38
+ ) {
39
+ count
40
+ dimensions { clientCountryName }
41
+ }
42
+ }
43
+ }
44
+ }
45
+ ```
46
+
47
+ Use `orderBy: [sum_edgeResponseBytes_DESC]` for top paths by bandwidth. Add `edgeResponseStatus_geq: 400` to the filter for top error status codes.
48
+
49
+ ## Workers Analytics
50
+
51
+ ```graphql
52
+ query WorkersOverview($accountTag: string!, $start: Time!, $end: Time!) {
53
+ viewer {
54
+ accounts(filter: { accountTag: $accountTag }) {
55
+ workersInvocationsAdaptive(
56
+ filter: { datetime_gt: $start, datetime_lt: $end }
57
+ limit: 100
58
+ orderBy: [sum_requests_DESC]
59
+ ) {
60
+ sum { requests errors subrequests wallTime }
61
+ quantiles { cpuTimeP50 cpuTimeP99 wallTimeP50 wallTimeP99 }
62
+ dimensions { scriptName }
63
+ }
64
+ }
65
+ }
66
+ }
67
+ ```
68
+
69
+ Filter by `scriptName` for a specific Worker. Add `datetimeFiveMinutes` dimension + `orderBy: [datetimeFiveMinutes_ASC]` for error rate over time.
70
+
71
+ ## Firewall / Security
72
+
73
+ ```graphql
74
+ query RecentFirewallEvents($zoneTag: string!, $start: Time!) {
75
+ viewer {
76
+ zones(filter: { zoneTag: $zoneTag }) {
77
+ firewallEventsAdaptive(
78
+ filter: { datetime_gt: $start }
79
+ limit: 50
80
+ orderBy: [datetime_DESC]
81
+ ) {
82
+ action source clientIP clientCountryName userAgent
83
+ clientRequestHTTPHost clientRequestPath ruleId datetime
84
+ }
85
+ }
86
+ }
87
+ }
88
+ ```
89
+
90
+ For aggregated firewall stats, use `firewallEventsAdaptiveGroups` with `action: "block"` filter and group by `ruleId`, `source`, `datetimeHour`.
91
+
92
+ ## DNS Analytics
93
+
94
+ ```graphql
95
+ query DNSQueryVolume($zoneTag: string!, $start: Time!, $end: Time!) {
96
+ viewer {
97
+ zones(filter: { zoneTag: $zoneTag }) {
98
+ dnsAnalyticsAdaptiveGroups(
99
+ filter: { datetime_gt: $start, datetime_lt: $end }
100
+ limit: 500
101
+ orderBy: [datetimeFiveMinutes_ASC]
102
+ ) {
103
+ count
104
+ dimensions { datetimeFiveMinutes }
105
+ }
106
+ }
107
+ }
108
+ }
109
+ ```
110
+
111
+ ## Storage Analytics (Account-Scoped)
112
+
113
+ R2, KV, and D1 use `date` (Date type) filters instead of `datetime` (Time type).
114
+
115
+ ```graphql
116
+ # R2 operations
117
+ r2OperationsAdaptiveGroups(filter: { date_geq: $start, date_leq: $end }, limit: 100, orderBy: [date_DESC]) {
118
+ dimensions { date bucketName actionType }
119
+ sum { requests }
120
+ }
121
+
122
+ # KV operations
123
+ kvOperationsAdaptiveGroups(filter: { date_geq: $start, date_leq: $end }, limit: 100, orderBy: [date_DESC]) {
124
+ dimensions { date actionType }
125
+ sum { requests }
126
+ }
127
+
128
+ # D1 analytics
129
+ d1AnalyticsAdaptiveGroups(filter: { date_geq: $start, date_leq: $end }, limit: 100, orderBy: [date_DESC]) {
130
+ dimensions { date databaseId }
131
+ sum { readQueries writeQueries rowsRead rowsWritten }
132
+ }
133
+ ```
134
+
135
+ ## Cache Analytics
136
+
137
+ ```graphql
138
+ query CacheStatusBreakdown($zoneTag: string!, $start: Time!, $end: Time!) {
139
+ viewer {
140
+ zones(filter: { zoneTag: $zoneTag }) {
141
+ httpRequestsAdaptiveGroups(
142
+ filter: { datetime_gt: $start, datetime_lt: $end }
143
+ limit: 20
144
+ orderBy: [count_DESC]
145
+ ) {
146
+ count
147
+ dimensions { cacheStatus }
148
+ sum { edgeResponseBytes }
149
+ }
150
+ }
151
+ }
152
+ }
153
+ ```
154
+
155
+ For cache hit ratio over time, use aliases to query the same dataset twice — once with `cacheStatus: "hit"` filter and once without — then compute the ratio client-side.
156
+
157
+ ## Multi-Dataset Queries
158
+
159
+ A single request can query multiple datasets, avoiding extra HTTP round-trips:
160
+
161
+ ```graphql
162
+ query DashboardOverview($zoneTag: string!, $start: Time!, $end: Time!) {
163
+ viewer {
164
+ zones(filter: { zoneTag: $zoneTag }) {
165
+ httpTraffic: httpRequestsAdaptiveGroups(
166
+ filter: { datetime_gt: $start, datetime_lt: $end }, limit: 1
167
+ ) { count sum { edgeResponseBytes } ratio { status4xx status5xx } }
168
+ firewallEvents: firewallEventsAdaptiveGroups(
169
+ filter: { datetime_gt: $start, datetime_lt: $end }, limit: 5, orderBy: [count_DESC]
170
+ ) { count dimensions { action source } }
171
+ dnsQueries: dnsAnalyticsAdaptiveGroups(
172
+ filter: { datetime_gt: $start, datetime_lt: $end }, limit: 1
173
+ ) { count }
174
+ }
175
+ }
176
+ }
177
+ ```
178
+
179
+ ## AI & Gateway Analytics
180
+
181
+ ```graphql
182
+ # Workers AI inference
183
+ aiInferenceAdaptiveGroups(
184
+ filter: { datetime_gt: $start, datetime_lt: $end }, limit: 100, orderBy: [datetimeHour_DESC]
185
+ ) {
186
+ count
187
+ sum { totalInputTokens totalOutputTokens totalRequestBytesIn }
188
+ dimensions { modelId datetimeHour }
189
+ }
190
+
191
+ # AI Gateway requests
192
+ aiGatewayRequestsAdaptiveGroups(
193
+ filter: { datetime_gt: $start, datetime_lt: $end }, limit: 100, orderBy: [datetimeHour_DESC]
194
+ ) {
195
+ count
196
+ dimensions { gateway provider model datetimeHour }
197
+ sum { cachedTokensIn cachedTokensOut uncachedTokensIn uncachedTokensOut }
198
+ }
199
+ ```
200
+
201
+ Both are account-scoped — nest under `accounts(filter: { accountTag: $accountTag })`.
202
+
203
+ ## Best Practices
204
+
205
+ **Always include time filters.** Queries without time filters scan all data and are slow/expensive.
206
+
207
+ **Match time granularity to range:**
208
+
209
+ | Time Range | Recommended Dimension |
210
+ |------------|----------------------|
211
+ | < 6 hours | `datetimeMinute` or `datetimeFiveMinutes` |
212
+ | 6-48 hours | `datetimeFiveMinutes` or `datetimeFifteenMinutes` |
213
+ | 2-14 days | `datetimeHour` |
214
+ | 14+ days | `date` |
215
+
216
+ **Use aliases** for querying the same dataset with different filters in one request.
217
+
218
+ **Request only needed fields.** Extra dimensions and metrics increase query cost.
219
+
220
+ ## See Also
221
+
222
+ - [README.md](README.md) - Overview, decision tree, dataset index
223
+ - [api.md](api.md) - Query structure, aggregation fields, filtering operators
224
+ - [configuration.md](configuration.md) - Authentication, client setup, introspection queries
225
+ - [gotchas.md](gotchas.md) - Rate limits, sampling, troubleshooting
@@ -0,0 +1,82 @@
1
+ # Hyperdrive
2
+
3
+ Accelerates database queries from Workers via connection pooling, edge setup, query caching.
4
+
5
+ ## Key Features
6
+
7
+ - **Connection Pooling**: Persistent connections eliminate TCP/TLS/auth handshakes (~7 round-trips)
8
+ - **Edge Setup**: Connection negotiation at edge, pooling near origin
9
+ - **Query Caching**: Auto-cache non-mutating queries (default 60s TTL)
10
+ - **Support**: PostgreSQL, MySQL + compatibles (CockroachDB, Timescale, PlanetScale, Neon, Supabase)
11
+
12
+ ## Architecture
13
+
14
+ ```
15
+ Worker → Edge (setup) → Pool (near DB) → Origin
16
+ ↓ cached reads
17
+ Cache
18
+ ```
19
+
20
+ ## Quick Start
21
+
22
+ ```bash
23
+ # Create config
24
+ npx wrangler hyperdrive create my-db \
25
+ --connection-string="postgres://user:pass@host:5432/db"
26
+
27
+ # wrangler.jsonc
28
+ {
29
+ "compatibility_flags": ["nodejs_compat"],
30
+ "hyperdrive": [{"binding": "HYPERDRIVE", "id": "<ID>"}]
31
+ }
32
+ ```
33
+
34
+ ```typescript
35
+ import { Client } from "pg";
36
+
37
+ export default {
38
+ async fetch(req: Request, env: Env): Promise<Response> {
39
+ const client = new Client({
40
+ connectionString: env.HYPERDRIVE.connectionString,
41
+ });
42
+ await client.connect();
43
+ const result = await client.query("SELECT * FROM users WHERE id = $1", [123]);
44
+ await client.end();
45
+ return Response.json(result.rows);
46
+ },
47
+ };
48
+ ```
49
+
50
+ ## When to Use
51
+
52
+ ✅ Global access to single-region DBs, high read ratios, popular queries, connection-heavy loads
53
+ ❌ Write-heavy, real-time data (<1s), single-region apps close to DB
54
+
55
+ **💡 Pair with Smart Placement** for Workers making multiple queries - executes near DB to minimize latency.
56
+
57
+ ## Driver Choice
58
+
59
+ | Driver | Use When | Notes |
60
+ |--------|----------|-------|
61
+ | **pg** (recommended) | General use, TypeScript, ecosystem compatibility | Stable, widely used, works with most ORMs |
62
+ | **postgres.js** | Advanced features, template literals, streaming | Lighter than pg, `prepare: true` is default |
63
+ | **mysql2** | MySQL/MariaDB/PlanetScale | MySQL only, less mature support |
64
+
65
+ ## Reading Order
66
+
67
+ | New to Hyperdrive | Implementing | Troubleshooting |
68
+ |-------------------|--------------|-----------------|
69
+ | 1. README (this) | 1. [configuration.md](./configuration.md) | 1. [gotchas.md](./gotchas.md) |
70
+ | 2. [configuration.md](./configuration.md) | 2. [api.md](./api.md) | 2. [patterns.md](./patterns.md) |
71
+ | 3. [api.md](./api.md) | 3. [patterns.md](./patterns.md) | 3. [api.md](./api.md) |
72
+
73
+ ## In This Reference
74
+ - [configuration.md](./configuration.md) - Setup, wrangler config, Smart Placement
75
+ - [api.md](./api.md) - Binding APIs, query patterns, driver usage
76
+ - [patterns.md](./patterns.md) - Use cases, ORMs, multi-query optimization
77
+ - [gotchas.md](./gotchas.md) - Limits, troubleshooting, connection management
78
+
79
+ ## See Also
80
+ - [smart-placement](../smart-placement/) - Optimize multi-query Workers near databases
81
+ - [d1](../d1/) - Serverless SQLite alternative for edge-native apps
82
+ - [workers](../workers/) - Worker runtime with database bindings
@@ -0,0 +1,143 @@
1
+ # API Reference
2
+
3
+ See [README.md](./README.md) for overview, [configuration.md](./configuration.md) for setup.
4
+
5
+ ## Binding Interface
6
+
7
+ ```typescript
8
+ interface Hyperdrive {
9
+ connectionString: string; // PostgreSQL
10
+ // MySQL properties:
11
+ host: string;
12
+ port: number;
13
+ user: string;
14
+ password: string;
15
+ database: string;
16
+ }
17
+
18
+ interface Env {
19
+ HYPERDRIVE: Hyperdrive;
20
+ }
21
+ ```
22
+
23
+ **Generate types:** `npx wrangler types` (auto-creates worker-configuration.d.ts from wrangler.jsonc)
24
+
25
+ ## PostgreSQL (node-postgres) - RECOMMENDED
26
+
27
+ ```typescript
28
+ import { Client } from "pg"; // pg@^8.17.2
29
+
30
+ export default {
31
+ async fetch(req: Request, env: Env): Promise<Response> {
32
+ const client = new Client({connectionString: env.HYPERDRIVE.connectionString});
33
+ try {
34
+ await client.connect();
35
+ const result = await client.query("SELECT * FROM users WHERE id = $1", [123]);
36
+ return Response.json(result.rows);
37
+ } finally {
38
+ await client.end();
39
+ }
40
+ },
41
+ };
42
+ ```
43
+
44
+ **⚠️ Workers connection limit: 6 per Worker invocation** - use connection pooling wisely.
45
+
46
+ ## PostgreSQL (postgres.js)
47
+
48
+ ```typescript
49
+ import postgres from "postgres"; // postgres@^3.4.8
50
+
51
+ const sql = postgres(env.HYPERDRIVE.connectionString, {
52
+ max: 5, // Limit per Worker (Workers max: 6)
53
+ prepare: true, // Enabled by default, required for caching
54
+ fetch_types: false, // Reduce latency if not using arrays
55
+ });
56
+
57
+ const users = await sql`SELECT * FROM users WHERE active = ${true} LIMIT 10`;
58
+ ```
59
+
60
+ **⚠️ `prepare: true` is enabled by default and required for Hyperdrive caching.** Setting to `false` disables prepared statements + cache.
61
+
62
+ ## MySQL (mysql2)
63
+
64
+ ```typescript
65
+ import { createConnection } from "mysql2/promise"; // mysql2@^3.16.2
66
+
67
+ const conn = await createConnection({
68
+ host: env.HYPERDRIVE.host,
69
+ user: env.HYPERDRIVE.user,
70
+ password: env.HYPERDRIVE.password,
71
+ database: env.HYPERDRIVE.database,
72
+ port: env.HYPERDRIVE.port,
73
+ disableEval: true, // ⚠️ REQUIRED for Workers
74
+ });
75
+
76
+ const [results] = await conn.query("SELECT * FROM users WHERE active = ? LIMIT ?", [true, 10]);
77
+ ctx.waitUntil(conn.end());
78
+ ```
79
+
80
+ **⚠️ MySQL support is less mature than PostgreSQL** - expect fewer optimizations and potential edge cases.
81
+
82
+ ## Query Caching
83
+
84
+ **Cacheable:**
85
+ ```sql
86
+ SELECT * FROM posts WHERE published = true;
87
+ SELECT COUNT(*) FROM users;
88
+ ```
89
+
90
+ **NOT cacheable:**
91
+ ```sql
92
+ -- Writes
93
+ INSERT/UPDATE/DELETE
94
+
95
+ -- Volatile functions
96
+ SELECT NOW();
97
+ SELECT random();
98
+ SELECT LASTVAL(); -- PostgreSQL
99
+ SELECT UUID(); -- MySQL
100
+ ```
101
+
102
+ **Cache config:**
103
+ - Default: `max_age=60s`, `swr=15s`
104
+ - Max `max_age`: 3600s
105
+ - Disable: `--caching-disabled=true`
106
+
107
+ **Multiple configs pattern:**
108
+ ```typescript
109
+ // Reads: cached
110
+ const sqlCached = postgres(env.HYPERDRIVE_CACHED.connectionString);
111
+ const posts = await sqlCached`SELECT * FROM posts ORDER BY views DESC LIMIT 10`;
112
+
113
+ // Writes/time-sensitive: no cache
114
+ const sqlNoCache = postgres(env.HYPERDRIVE_NO_CACHE.connectionString);
115
+ const orders = await sqlNoCache`SELECT * FROM orders WHERE created_at > NOW() - INTERVAL 5 MINUTE`;
116
+ ```
117
+
118
+ ## ORMs
119
+
120
+ **Drizzle:**
121
+ ```typescript
122
+ import { drizzle } from "drizzle-orm/postgres-js"; // drizzle-orm@^0.45.1
123
+ import postgres from "postgres";
124
+
125
+ const client = postgres(env.HYPERDRIVE.connectionString, {max: 5, prepare: true});
126
+ const db = drizzle(client);
127
+ const users = await db.select().from(users).where(eq(users.active, true)).limit(10);
128
+ ```
129
+
130
+ **Kysely:**
131
+ ```typescript
132
+ import { Kysely, PostgresDialect } from "kysely"; // kysely@^0.27+
133
+ import postgres from "postgres";
134
+
135
+ const db = new Kysely({
136
+ dialect: new PostgresDialect({
137
+ postgres: postgres(env.HYPERDRIVE.connectionString, {max: 5, prepare: true}),
138
+ }),
139
+ });
140
+ const users = await db.selectFrom("users").selectAll().where("active", "=", true).execute();
141
+ ```
142
+
143
+ See [patterns.md](./patterns.md) for use cases, [gotchas.md](./gotchas.md) for limits.
@@ -0,0 +1,159 @@
1
+ # Configuration
2
+
3
+ See [README.md](./README.md) for overview.
4
+
5
+ ## Create Config
6
+
7
+ **PostgreSQL:**
8
+ ```bash
9
+ # Basic
10
+ npx wrangler hyperdrive create my-db \
11
+ --connection-string="postgres://user:pass@host:5432/db"
12
+
13
+ # Custom cache
14
+ npx wrangler hyperdrive create my-db \
15
+ --connection-string="postgres://..." \
16
+ --max-age=120 --swr=30
17
+
18
+ # No cache
19
+ npx wrangler hyperdrive create my-db \
20
+ --connection-string="postgres://..." \
21
+ --caching-disabled=true
22
+ ```
23
+
24
+ **MySQL:**
25
+ ```bash
26
+ npx wrangler hyperdrive create my-db \
27
+ --connection-string="mysql://user:pass@host:3306/db"
28
+ ```
29
+
30
+ ## wrangler.jsonc
31
+
32
+ ```jsonc
33
+ {
34
+ "compatibility_date": "2025-01-01", // Use latest for new projects
35
+ "compatibility_flags": ["nodejs_compat"],
36
+ "hyperdrive": [
37
+ {
38
+ "binding": "HYPERDRIVE",
39
+ "id": "<HYPERDRIVE_ID>",
40
+ "localConnectionString": "postgres://user:pass@localhost:5432/dev"
41
+ }
42
+ ]
43
+ }
44
+ ```
45
+
46
+ **Generate TypeScript types:** Run `npx wrangler types` to auto-generate `worker-configuration.d.ts` from your wrangler.jsonc.
47
+
48
+ **Multiple configs:**
49
+ ```jsonc
50
+ {
51
+ "hyperdrive": [
52
+ {"binding": "HYPERDRIVE_CACHED", "id": "<ID1>"},
53
+ {"binding": "HYPERDRIVE_NO_CACHE", "id": "<ID2>"}
54
+ ]
55
+ }
56
+ ```
57
+
58
+ ## Management
59
+
60
+ ```bash
61
+ npx wrangler hyperdrive list
62
+ npx wrangler hyperdrive get <ID>
63
+ npx wrangler hyperdrive update <ID> --max-age=180
64
+ npx wrangler hyperdrive delete <ID>
65
+ ```
66
+
67
+ ## Config Options
68
+
69
+ Hyperdrive create/update CLI flags:
70
+
71
+ | Option | Default | Notes |
72
+ |--------|---------|-------|
73
+ | `--caching-disabled` | `false` | Disable caching |
74
+ | `--max-age` | `60` | Cache TTL (max 3600s) |
75
+ | `--swr` | `15` | Stale-while-revalidate |
76
+ | `--origin-connection-limit` | 20/100 | Free/paid |
77
+ | `--access-client-id` | - | Tunnel auth |
78
+ | `--access-client-secret` | - | Tunnel auth |
79
+ | `--sslmode` | `require` | PostgreSQL only |
80
+
81
+ ## Smart Placement Integration
82
+
83
+ For Workers making **multiple queries** per request, enable Smart Placement to execute near your database:
84
+
85
+ ```jsonc
86
+ {
87
+ "compatibility_date": "2025-01-01",
88
+ "compatibility_flags": ["nodejs_compat"],
89
+ "placement": {
90
+ "mode": "smart"
91
+ },
92
+ "hyperdrive": [
93
+ {
94
+ "binding": "HYPERDRIVE",
95
+ "id": "<HYPERDRIVE_ID>"
96
+ }
97
+ ]
98
+ }
99
+ ```
100
+
101
+ **Benefits:** Multi-query Workers run closer to DB, reducing round-trip latency. See [patterns.md](./patterns.md) for examples.
102
+
103
+ ## Private DB via Tunnel
104
+
105
+ ```
106
+ Worker → Hyperdrive → Access → Tunnel → Private Network → DB
107
+ ```
108
+
109
+ **Setup:**
110
+ ```bash
111
+ # 1. Create tunnel
112
+ cloudflared tunnel create my-db-tunnel
113
+
114
+ # 2. Configure hostname in Zero Trust dashboard
115
+ # Domain: db-tunnel.example.com
116
+ # Service: TCP -> localhost:5432
117
+
118
+ # 3. Create service token (Zero Trust > Service Auth)
119
+ # Save Client ID/Secret
120
+
121
+ # 4. Create Access app (db-tunnel.example.com)
122
+ # Policy: Service Auth token from step 3
123
+
124
+ # 5. Create Hyperdrive
125
+ npx wrangler hyperdrive create my-private-db \
126
+ --host=db-tunnel.example.com \
127
+ --user=dbuser --password=dbpass --database=prod \
128
+ --access-client-id=<ID> --access-client-secret=<SECRET>
129
+ ```
130
+
131
+ **⚠️ Don't specify `--port` with Tunnel** - port configured in tunnel service settings.
132
+
133
+ ## Local Dev
134
+
135
+ **Option 1: Local (RECOMMENDED):**
136
+ ```bash
137
+ # Env var (takes precedence)
138
+ export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgres://user:pass@localhost:5432/dev"
139
+ npx wrangler dev
140
+
141
+ # wrangler.jsonc
142
+ {"hyperdrive": [{"binding": "HYPERDRIVE", "localConnectionString": "postgres://..."}]}
143
+ ```
144
+
145
+ **Remote DB locally:**
146
+ ```bash
147
+ # PostgreSQL
148
+ export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgres://user:pass@remote:5432/db?sslmode=require"
149
+
150
+ # MySQL
151
+ export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="mysql://user:pass@remote:3306/db?sslMode=REQUIRED"
152
+ ```
153
+
154
+ **Option 2: Remote execution:**
155
+ ```bash
156
+ npx wrangler dev --remote # Uses deployed config, affects production
157
+ ```
158
+
159
+ See [api.md](./api.md), [patterns.md](./patterns.md), [gotchas.md](./gotchas.md).
@@ -0,0 +1,77 @@
1
+ # Gotchas
2
+
3
+ See [README.md](./README.md), [configuration.md](./configuration.md), [api.md](./api.md), [patterns.md](./patterns.md).
4
+
5
+ ## Common Errors
6
+
7
+ ### "Too many open connections" / "Connection limit exceeded"
8
+
9
+ **Cause:** Workers have a hard limit of **6 concurrent connections per invocation**
10
+ **Solution:** Set `max: 5` in driver config, reuse connections, ensure proper cleanup with `client.end()` or `ctx.waitUntil(conn.end())`
11
+
12
+ ### "Failed to acquire a connection (Pool exhausted)"
13
+
14
+ **Cause:** All connections in pool are in use, often due to long-running transactions
15
+ **Solution:** Reduce transaction duration, avoid queries >60s, don't hold connections during external calls, or upgrade to paid plan for more connections
16
+
17
+ ### "connection_refused"
18
+
19
+ **Cause:** Database refusing connections due to firewall, connection limits, or service down
20
+ **Solution:** Check firewall allows Cloudflare IPs, verify DB listening on port, confirm service running, and validate credentials
21
+
22
+ ### "Query timeout (deadline exceeded)"
23
+
24
+ **Cause:** Query execution exceeding 60s timeout limit
25
+ **Solution:** Optimize with indexes, reduce dataset with LIMIT, break into smaller queries, or use async processing
26
+
27
+ ### "password authentication failed"
28
+
29
+ **Cause:** Invalid credentials in Hyperdrive configuration
30
+ **Solution:** Check username and password in Hyperdrive config match database credentials
31
+
32
+ ### "SSL/TLS connection error"
33
+
34
+ **Cause:** SSL/TLS configuration mismatch between Hyperdrive and database
35
+ **Solution:** Add `sslmode=require` (Postgres) or `sslMode=REQUIRED` (MySQL), upload CA cert if self-signed, verify DB has SSL enabled, and check cert expiry
36
+
37
+ ### "Queries not being cached"
38
+
39
+ **Cause:** Query is mutating (INSERT/UPDATE/DELETE), contains volatile functions (NOW(), RANDOM()), or caching disabled
40
+ **Solution:** Verify query is non-mutating SELECT, avoid volatile functions, confirm caching enabled, use `wrangler dev --remote` to test, and set `prepare=true` for postgres.js
41
+
42
+ ### "Slow multi-query Workers despite Hyperdrive"
43
+
44
+ **Cause:** Worker executing at edge, each query round-trips to DB region
45
+ **Solution:** Enable Smart Placement (`"placement": {"mode": "smart"}` in wrangler.jsonc) to execute Worker near DB. See [patterns.md](./patterns.md) Multi-Query pattern.
46
+
47
+ ### "Local database connection failed"
48
+
49
+ **Cause:** `localConnectionString` incorrect or database not running
50
+ **Solution:** Verify `localConnectionString` correct, check DB running, confirm env var name matches binding, and test with psql/mysql client
51
+
52
+ ### "Environment variable not working"
53
+
54
+ **Cause:** Environment variable format incorrect or not exported
55
+ **Solution:** Use format `CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING>`, ensure binding matches wrangler.jsonc, export variable in shell, and restart wrangler dev
56
+
57
+ ## Limits
58
+
59
+ | Limit | Free | Paid | Notes |
60
+ |-------|------|------|-------|
61
+ | Max configs | 10 | 25 | Hyperdrive configurations per account |
62
+ | Worker connections | 6 | 6 | Max concurrent connections per Worker invocation |
63
+ | Username/DB name | 63 bytes | 63 bytes | Maximum length |
64
+ | Connection timeout | 15s | 15s | Time to establish connection |
65
+ | Idle timeout | 10 min | 10 min | Connection idle timeout |
66
+ | Max origin connections | ~20 | ~100 | Connections to origin database |
67
+ | Query duration max | 60s | 60s | Queries >60s terminated |
68
+ | Cached response max | 50 MB | 50 MB | Responses >50MB returned but not cached |
69
+
70
+ ## Resources
71
+
72
+ - [Docs](https://developers.cloudflare.com/hyperdrive/)
73
+ - [Getting Started](https://developers.cloudflare.com/hyperdrive/get-started/)
74
+ - [Wrangler Reference](https://developers.cloudflare.com/hyperdrive/reference/wrangler-commands/)
75
+ - [Supported DBs](https://developers.cloudflare.com/hyperdrive/reference/supported-databases-and-features/)
76
+ - [Discord #hyperdrive](https://discord.cloudflare.com)
77
+ - [Limit Increase Form](https://forms.gle/ukpeZVLWLnKeixDu7)