【免费下载链接】autoskillsOne command. Your entire AI skill stack. Installed.项目地址https://gitcode.com/gh_mirrors/au/autoskills点击查看免费下载本文围绕 autoskills 仓库中 Cloudflare 技能包内置的 Hyperdrive 参考文档展开覆盖其连接池化、边缘协商、查询缓存三大核心机制的完整工作原理并继承官方参考文档中的全部配置参数、wrangler 命令行用法、驱动选择与查询缓存规则结合同目录下的 configuration、api、patterns、gotchas 等配套文档系统讲解如何在 Cloudflare Workers 中以生产级方式访问既有数据库。读完本文你将能够独立创建 Hyperdrive 配置、编写带连接池的 Worker 数据库代码并针对连接数限制、缓存失效、私有网络数据库接入等典型问题做出正确取舍。Hyperdrive 解决什么问题在 autoskills 的 Cloudflare 技能索引 的存储决策树中关系型 SQL 的选型规则是edge 原生应用选 D1serverless SQLite而要访问既有的 PostgreSQL/MySQL 数据库则选 Hyperdrive参考文档位于 references/hyperdrive/。Hyperdrive 的定位一句话概括Accelerates database queries from Workers via connection pooling, edge setup, query caching通过连接池化、边缘协商与查询缓存加速 Worker 的数据库查询。其核心特性来自 README连接池化Connection Pooling持久连接复用以消除 TCP/TLS/认证握手约 7 次往返边缘协商Edge Setup连接协商发生在边缘节点而实际连接池部署在靠近源数据库的位置查询缓存Query Caching自动缓存非变更型查询默认 TTL 60 秒支持范围PostgreSQL、MySQL 及兼容数据库CockroachDB、Timescale、PlanetScale、Neon、Supabase。其请求链路架构为Worker → Edge (setup) → Pool (near DB) → Origin ↓ cached reads Cache也就是说用户请求先到达离用户最近的边缘节点完成连接协商随后被转发到离数据库更近的池节点执行读命中缓存时则直接从缓存返回。适用与不适用场景README 给出了明确的使用边界✅适合需要全球访问单区域数据库、读多写少、热门查询重复率高、连接密集型负载。❌不适合写密集负载、要求亚秒级1s实时性的数据、以及本身就在数据库附近区域的单区域应用。 配套建议如果一个 Worker 每次请求要执行多条查询README 建议同时开启 Smart Placement使 Worker 在靠近数据库的位置执行进一步压低每条查询的往返延迟。autoskills 仓库中确有对应的 Smart Placement 参考文档其中说明其通过placement: { mode: smart }启用且只对带fetch事件处理器的 Worker 生效。快速上手创建配置与首个查询创建 Hyperdrive 配置# Create config npx wrangler hyperdrive create my-db \ --connection-stringpostgres://user:passhost:5432/db执行后需将生成的配置写入wrangler.jsonc// wrangler.jsonc { compatibility_flags: [nodejs_compat], hyperdrive: [{binding: HYPERDRIVE, id: ID}] }注意compatibility_flags必须包含nodejs_compat否则数据库驱动如pg无法正常工作。Worker 中查询数据库README 给出的首个可运行示例基于pgnode-postgresimport { Client } from pg; export default { async fetch(req: Request, env: Env): PromiseResponse { const client new Client({ connectionString: env.HYPERDRIVE.connectionString, }); await client.connect(); const result await client.query(SELECT * FROM users WHERE id $1, [123]); await client.end(); return Response.json(result.rows); }, };配套文档 api.md 在更完整的示例中强调了try/finally清理模式——client.end()应放在finally块中执行确保请求异常时连接也能归还避免占用 Workers 严格的连接配额import { Client } from pg; // pg^8.17.2 export default { async fetch(req: Request, env: Env): PromiseResponse { const client new Client({connectionString: env.HYPERDRIVE.connectionString}); try { await client.connect(); const result await client.query(SELECT * FROM users WHERE id $1, [123]); return Response.json(result.rows); } finally { await client.end(); } }, };完整配置指南CLI 参数、wrangler.jsonc 与管理命令configuration.md 是落地实操的主文档完整继承了以下全部内容。创建配置的 CLI 变体PostgreSQL# Basic npx wrangler hyperdrive create my-db \ --connection-stringpostgres://user:passhost:5432/db # Custom cache npx wrangler hyperdrive create my-db \ --connection-stringpostgres://... \ --max-age120 --swr30 # No cache npx wrangler hyperdrive create my-db \ --connection-stringpostgres://... \ --caching-disabledtrueMySQLnpx wrangler hyperdrive create my-db \ --connection-stringmysql://user:passhost:3306/dbwrangler.jsonc 完整写法{ compatibility_date: 2025-01-01, // Use latest for new projects compatibility_flags: [nodejs_compat], hyperdrive: [ { binding: HYPERDRIVE, id: HYPERDRIVE_ID, localConnectionString: postgres://user:passlocalhost:5432/dev } ] }三个要点compatibility_date新项目建议用最新版本localConnectionString用于本地开发详见下文“本地开发”一节运行npx wrangler types可从 wrangler.jsonc 自动生成worker-configuration.d.ts为env.HYPERDRIVE提供 TypeScript 类型。多配置Multiple configs同一 Worker 可以绑定多个 Hyperdrive 配置用不同binding名区分典型用法是“缓存读 无缓存写”分离{ hyperdrive: [ {binding: HYPERDRIVE_CACHED, id: ID1}, {binding: HYPERDRIVE_NO_CACHE, id: ID2} ] }生命周期管理命令npx wrangler hyperdrive list npx wrangler hyperdrive get ID npx wrangler hyperdrive update ID --max-age180 npx wrangler hyperdrive delete IDcreate/update 的全部 CLI 参数OptionDefaultNotes--caching-disabledfalseDisable caching--max-age60Cache TTL (max 3600s)--swr15Stale-while-revalidate--origin-connection-limit20/100Free/paid--access-client-id-Tunnel auth--access-client-secret-Tunnel auth--sslmoderequirePostgreSQL only几个值得注意的默认值缓存默认开启、TTL 60 秒、SWRstale-while-revalidate允许在缓存过期后短暂返回旧值的同时后台刷新默认 15 秒--max-age上限 3600 秒免费档到源库的连接数上限约 20付费档约 100。绑定接口与三大驱动写法Binding 接口形态api.md 定义了 Worker 收到的绑定结构——PostgreSQL 只暴露一个connectionString而 MySQL 则拆解为各字段interface Hyperdrive { connectionString: string; // PostgreSQL // MySQL properties: host: string; port: number; user: string; password: string; database: string; } interface Env { HYPERDRIVE: Hyperdrive; }驱动选择DriverUse WhenNotespg推荐General use, TypeScript, ecosystem compatibilityStable, widely used, works with most ORMspostgres.jsAdvanced features, template literals, streamingLighter than pg,prepare: trueis defaultmysql2MySQL/MariaDB/PlanetScaleMySQL only, less mature support关键前提Workers 每次调用最多只有6 个并发连接free 与 paid 均如此见 gotchas.md 的 Limits 表因此驱动侧池大小必须留有余量。postgres.js 写法模板字符串风格import postgres from postgres; // postgres^3.4.8 const sql postgres(env.HYPERDRIVE.connectionString, { max: 5, // Limit per Worker (Workers max: 6) prepare: true, // Enabled by default, required for caching fetch_types: false, // Reduce latency if not using arrays }); const users await sqlSELECT * FROM users WHERE active ${true} LIMIT 10;api.md 特别强调prepare: true默认开启且是 Hyperdrive 缓存生效的前提显式设为false会同时禁用 prepared statements 与查询缓存。mysql2 写法import { createConnection } from mysql2/promise; // mysql2^3.16.2 const conn await createConnection({ host: env.HYPERDRIVE.host, user: env.HYPERDRIVE.user, password: env.HYPERDRIVE.password, database: env.HYPERDRIVE.database, port: env.HYPERDRIVE.port, disableEval: true, // ⚠️ REQUIRED for Workers }); const [results] await conn.query(SELECT * FROM users WHERE active ? LIMIT ?, [true, 10]); ctx.waitUntil(conn.end());两个要点disableEval: true在 Workers 环境是必需的Worker 禁止运行时eval连接收尾要交给ctx.waitUntil(conn.end())让收尾逻辑在响应返回后异步完成。api.md 同时提醒 MySQL 支持成熟度低于 PostgreSQL可预期更少的优化与更多边缘情况。ORM 集成Drizzle / KyselyDrizzleimport { drizzle } from drizzle-orm/postgres-js; // drizzle-orm^0.45.1 import postgres from postgres; const client postgres(env.HYPERDRIVE.connectionString, {max: 5, prepare: true}); const db drizzle(client); const users await db.select().from(users).where(eq(users.active, true)).limit(10);Kyselyimport { Kysely, PostgresDialect } from kysely; // kysely^0.27 import postgres from postgres; const db new Kysely({ dialect: new PostgresDialect({ postgres: postgres(env.HYPERDRIVE.connectionString, {max: 5, prepare: true}), }), }); const users await db.selectFrom(users).selectAll().where(active, , true).execute();两个 ORM 的示例都基于postgres驱动并保留prepare: true保证 ORM 生成的查询仍走 prepared statements、可被 Hyperdrive 缓存。查询缓存规则哪些查询会被缓存缓存规则是 Hyperdrive 使用中最容易踩坑的部分。api.md 给出的判定边界可缓存CacheableSELECT * FROM posts WHERE published true; SELECT COUNT(*) FROM users;不可缓存NOT cacheable-- Writes INSERT/UPDATE/DELETE -- Volatile functions SELECT NOW(); SELECT random(); SELECT LASTVAL(); -- PostgreSQL SELECT UUID(); -- MySQL即变更型语句与含易变函数volatile functions的语句一律不缓存。默认参数为max_age60s、swr15smax_age上限 3600 秒可用--caching-disabledtrue整体关闭。由此衍生出一个实用模式——双配置分离读写热点读路径走缓存配置时间敏感/写路径走无缓存配置// Reads: cached const sqlCached postgres(env.HYPERDRIVE_CACHED.connectionString); const posts await sqlCachedSELECT * FROM posts ORDER BY views DESC LIMIT 10; // Writes/time-sensitive: no cache const sqlNoCache postgres(env.HYPERDRIVE_NO_CACHE.connectionString); const orders await sqlNoCacheSELECT * FROM orders WHERE created_at NOW() - INTERVAL 5 MINUTE;patterns.md 进一步给出了“写缓存友好查询”的技巧// ✅ Cacheable (deterministic) await sqlSELECT * FROM products WHERE category electronics LIMIT 10; // ❌ Not cacheable (volatile NOW()) await sqlSELECT * FROM logs WHERE created_at NOW(); // ✅ Cacheable (parameterized timestamp) const ts Date.now(); await sqlSELECT * FROM logs WHERE created_at ${ts};用参数化时间戳替代NOW()即可让本不该缓存的“时间窗口查询”变得可缓存。典型架构模式来自 patterns.mdpatterns.md 覆盖了五类生产场景均继承自原文档高流量读密集型const sql postgres(env.HYPERDRIVE.connectionString, {max: 5, prepare: true}); // Cacheable: popular content const posts await sqlSELECT * FROM posts WHERE published true ORDER BY views DESC LIMIT 20; // Cacheable: user profiles const [user] await sqlSELECT id, username, bio FROM users WHERE id ${userId};热门内容与用户画像天然命中 60s 缓存流量尖峰由连接池吸收。读写混合双绑定interface Env { HYPERDRIVE_CACHED: Hyperdrive; // max_age120 HYPERDRIVE_REALTIME: Hyperdrive; // caching disabled } // Reads: cached if (req.method GET) { const sql postgres(env.HYPERDRIVE_CACHED.connectionString, {prepare: true}); const products await sqlSELECT * FROM products WHERE category ${cat}; } // Writes: no cache (immediate consistency) if (req.method POST) { const sql postgres(env.HYPERDRIVE_REALTIME.connectionString, {prepare: true}); await sqlINSERT INTO orders ${sql(data)}; }分析型看板const client new Client({connectionString: env.HYPERDRIVE.connectionString}); await client.connect(); // Aggregate queries cached (use fixed timestamps for caching) const thirtyDaysAgo new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString(); const dailyStats await client.query( SELECT DATE(created_at) as date, COUNT(*) as orders, SUM(amount) as revenue FROM orders WHERE created_at $1 GROUP BY DATE(created_at) ORDER BY date DESC , [thirtyDaysAgo]);聚合查询开销高、结果可容忍分钟级延迟是最典型的缓存受益者原文档提示同样要用固定时间戳替代NOW()。多租户const tenantId req.headers.get(X-Tenant-ID); const sql postgres(env.HYPERDRIVE.connectionString, {prepare: true}); // Tenant-scoped queries cached separately const docs await sql SELECT * FROM documents WHERE tenant_id ${tenantId} AND deleted_at IS NULL ORDER BY updated_at DESC LIMIT 50 ;不同租户的参数值天然产生不同缓存键实现按租户隔离的缓存同时共享连接池。连接池化行为事务模式下的 SET 陷阱patterns.md 指出 Hyperdrive 池工作在事务模式连接按事务借出归还时执行RESET。这直接决定了SET语句的正确写法// ✅ Within transaction await client.query(BEGIN); await client.query(SET work_mem 256MB); await client.query(SELECT * FROM large_table); // Uses SET await client.query(COMMIT); // RESET after // ✅ Single statement await client.query(SET work_mem 256MB; SELECT * FROM large_table); // ❌ Across queries (may get different connection) await client.query(SET work_mem 256MB); await client.query(SELECT * FROM large_table); // SET not applied以及最佳实践避免长事务独占连接BEGIN后挂起数秒处理外部逻辑会拖垮池保持事务短小或在事务内用SET LOCAL替代SET// ✅ Short transactions await client.query(BEGIN); await client.query(UPDATE users SET status $1 WHERE id $2, [status, id]); await client.query(COMMIT); // ✅ SET LOCAL within transaction await client.query(BEGIN); await client.query(SET LOCAL work_mem 256MB); await client.query(SELECT * FROM large_table); await client.query(COMMIT);多查询 Smart Placement当单请求内有多条查询时建议在 wrangler.jsonc 同时开启 Smart Placement// wrangler.jsonc { placement: {mode: smart}, hyperdrive: [{binding: HYPERDRIVE, id: ID}] }const sql postgres(env.HYPERDRIVE.connectionString, {prepare: true}); // Multiple queries benefit from Smart Placement const [user] await sqlSELECT * FROM users WHERE id ${userId}; const orders await sqlSELECT * FROM orders WHERE user_id ${userId} ORDER BY created_at DESC LIMIT 10; const stats await sqlSELECT COUNT(*) as total, SUM(amount) as spent FROM orders WHERE user_id ${userId}; return Response.json({user, orders, stats});原理是不开 Smart Placement 时 Worker 在离用户最近的边缘执行每条查询都要跨洲往返开启后平台把 Worker 调度到靠近数据库的位置N 条查询的往返延迟同时下降。autoskills 中 smart-placement 参考文档 给出了启用前提需带fetch处理器的 Worker、后端地理集中、请求时延主要由后端主导且分析窗口约 15 分钟。私有数据库接入Hyperdrive Tunnel Accessconfiguration.md 提供了把数据库放在私有网络VPC/内网时的完整链路Worker → Hyperdrive → Access → Tunnel → Private Network → DBSetup 五步# 1. Create tunnel cloudflared tunnel create my-db-tunnel # 2. Configure hostname in Zero Trust dashboard # Domain: db-tunnel.example.com # Service: TCP - localhost:5432 # 3. Create service token (Zero Trust Service Auth) # Save Client ID/Secret # 4. Create Access app (db-tunnel.example.com) # Policy: Service Auth token from step 3 # 5. Create Hyperdrive npx wrangler hyperdrive create my-private-db \ --hostdb-tunnel.example.com \ --userdbuser --passworddbpass --databaseprod \ --access-client-idID --access-client-secretSECRET注意两点使用 Tunnel 时用--host/--user/--password/--database分字段传参而非完整 connection string不要指定--port端口在 tunnel 服务设置中配置。本地开发configuration.md 推荐两种本地验证方式方式一本地连接RECOMMENDED——让wrangler dev直连本地或远程数据库# Env var (takes precedence) export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVEpostgres://user:passlocalhost:5432/dev npx wrangler dev # wrangler.jsonc {hyperdrive: [{binding: HYPERDRIVE, localConnectionString: postgres://...}]}远程库本地开发时注意 SSL 参数差异PostgreSQL 用?sslmoderequireMySQL 用?sslModeREQUIRED大小写敏感# PostgreSQL export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVEpostgres://user:passremote:5432/db?sslmoderequire # MySQL export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVEmysql://user:passremote:3306/db?sslModeREQUIRED方式二远程执行npx wrangler dev --remote # Uses deployed config, affects production环境变量命名规则是CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_BINDING其中BINDING必须与 wrangler.jsonc 中的 binding 名完全一致。平台限制与常见故障排查gotchas.md 汇总了硬限制表LimitFreePaidNotesMax configs1025Hyperdrive configurations per accountWorker connections66Max concurrent connections per Worker invocationUsername/DB name63 bytes63 bytesMaximum lengthConnection timeout15s15sTime to establish connectionIdle timeout10 min10 minConnection idle timeoutMax origin connections~20~100Connections to origin databaseQuery duration max60s60sQueries 60s terminatedCached response max50 MB50 MBResponses 50MB returned but not cached对应的高频故障与官方诊断路径均出自 gotchas.md现象原因解决方案Too many open connections / Connection limit exceededWorkers 单次调用 6 连接硬上限驱动配置设max: 5复用连接用client.end()或ctx.waitUntil(conn.end())正确清理Failed to acquire a connection (Pool exhausted)池耗尽常因长事务缩短事务、避免 60s 查询、外部调用期间不持有连接或升级付费档connection_refused防火墙/端口/服务异常确认防火墙放行 Cloudflare IP、端口监听、凭据正确Query timeout (deadline exceeded)超过 60s 查询上限加索引、加 LIMIT、拆小查询或改异步处理password authentication failed配置凭据错误核对 Hyperdrive 配置中的用户名密码SSL/TLS connection errorSSL 配置不匹配加sslmoderequirePostgres或sslModeREQUIREDMySQL自签证书需上传 CAQueries not being cached变更语句/易变函数/缓存被关闭确认是纯 SELECT、避开NOW()/RANDOM()、postgres.js设preparetrue用wrangler dev --remote验证Slow multi-query Workers despite HyperdriveWorker 仍在边缘执行开启 Smart Placementplacement: {mode: smart}Local database connection failedlocalConnectionString错误或数据库未启动核对字符串、确认数据库运行、环境变量名与 binding 一致Environment variable not working变量格式错误或未导出严格使用CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_BINDING格式并重启 wrangler dev文档地图如何继续深入Hyperdrive 参考目录采用 README 四个专题文件的组织方式README 中给出了三条阅读路径New to HyperdriveImplementingTroubleshooting1. README1. configuration.md1. gotchas.md2. configuration.md2. api.md2. patterns.md3. api.md3. patterns.md3. api.md各文件定位configuration.md — 创建/管理 CLI、wrangler.jsonc 配置、Smart Placement 集成、Tunnel 私有库接入、本地开发api.md — Binding 接口、三种驱动写法、缓存判定规则、ORM 集成patterns.md — 五大使用模式、事务模式下的 SET 语句、连接与查询性能调优gotchas.md — 十类常见错误、平台限制表。README 末尾还指向三个相邻参考smart-placement多查询 Worker 的数据库侧延迟优化本文已展开其配置与前提、d1edge 原生 serverless SQLite无既有数据库时的替代选择。此外autoskills 的 Cloudflare 技能主文档 明确提醒references 是检索起点而非权威来源涉及具体数值限制、API 签名或配置项时应以最新官方文档为准——本文所有默认值与限制均以仓库内 hyperdrive 参考文档 当前版本为准确认。赞分享【免费下载链接】autoskillsOne command. Your entire AI skill stack. Installed.项目地址https://gitcode.com/gh_mirrors/au/autoskills点击查看免费下载相关推荐react-desktop 版本演进全解析从 0.2.0 Beta 到 0.3.10 的 macOS/Windows 组件库发展史react desktop 版本演进全解析从 0.2.0 Beta 到 0.3.10 的 macOS/Windows 组件库发展史 react desktopnormalize.css 8.x 完整指南CSS Reset 的现代替代方案从安装到源码级规范化原理normalize.css 8.x 完整指南CSS Reset 的现代替代方案从安装到源码级规范化原理 normalize.css 是一个现代 CSS RCloudflare Workers Bindings 完全指南从 env 对象到平台资源的实战手册autoskills cloudflare-deploy 技能库Cloudflare Workers Bindings 完全指南从 env 对象到平台资源的实战手册autoskills cloudflare deploy上一篇如何让AI Agent替你打CTFctf-skills——AI解题Agent Skills工具箱完整入门指南下一篇PaddleSeg 自定义数据集准备与配置实战目录结构、文件列表生成与 Dataset 配置详解创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考