Qoder数据库连接需依次完成驱动安装、配置参数设置、应用初始化挂载、路由安全调用及健康度验证。先装PyMySQL/psycopg2-binary/redis，再在config/database.py中正确定义MYSQL_CONFIG和PG_CONFIG，接着在app.py中实例化并挂载至app.state，路由中通过Depends注入Database实例执行查询与事务，最后通过/health/db端点或qodercli db ping命令验证连接池状态。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您正在尝试将Qoder框架与数据库建立连接，但遇到连接失败、配置不生效或初始化报错等问题，则可能是由于驱动缺失、配置参数错误、初始化顺序不当或环境变量未就绪所致。以下是完成Qoder数据库连接的详细操作流程：
一、安装对应数据库驱动
Qoder需通过Python客户端驱动与数据库通信，不同数据库类型依赖不同驱动。未安装正确驱动将导致Database类实例化失败，并抛出ImportError或ModuleNotFoundError。
1、若使用MySQL：执行命令 pip install PyMySQL
2、若使用PostgreSQL：执行命令 pip install psycopg2-binary
3、若使用Redis作为缓存层：执行命令 pip install redis
4、验证全部驱动加载成功：运行 python -c "import pymysql; import psycopg2; import redis; print('✅ All drivers loaded')"
二、配置database.py连接参数
Qoder采用集中式配置管理，所有数据库连接参数必须统一定义在config/database.py中。该文件需显式导出命名字典（如MYSQL_CONFIG），字段值须与实际数据库服务完全一致；host写错为localhost而非127.0.0.1、port填写3307而非3306均会导致连接超时。
1、在config/database.py中定义MySQL配置块：MYSQL_CONFIG = {"host": "127.0.0.1", "port": 3306, "user": "qoder_app", "password": "secure_pass", "database": "prod_db", "charset": "utf8mb4"}
2、在同一文件中定义PostgreSQL配置块：PG_CONFIG = {"host": "db.internal", "port": 5432, "user": "qoder_ro", "password": "ro_only_2026", "database": "analytics", "sslmode": "require"}
3、保存后确认文件无语法错误，且无中文引号、多余逗号或未闭合括号。
三、在app.py中初始化并挂载数据库实例
Qoder要求在应用启动早期完成数据库对象创建，并将其绑定至FastAPI或Qoder应用上下文（app.state）。若初始化代码置于路由注册之后，或未正确赋值给app.state属性，后续业务逻辑调用db.query()时将触发AttributeError。
1、在app.py顶部导入模块：from qoder.db import Database
代码编辑 CLI 工具集合：Cursor CLI（agent）和 Qoder CLI（qodercli），用于代码修改、重构、Code Review 及自动化代码任务。
2、实例化MySQL连接：mysql_db = Database("mysql", **MYSQL_CONFIG)
3、实例化PostgreSQL连接：pg_db = Database("postgresql", **PG_CONFIG)
4、挂载至应用上下文：app.state.mysql = mysql_db 与 app.state.pg = pg_db
四、在路由中安全调用数据库查询
Qoder推荐“缓存穿透防护+主从分离感知”的调用模式。直接在路由函数内硬编码db.query()虽可运行，但无法利用内置连接池复用、事务上下文及自动重试机制，易引发连接耗尽或脏读。
1、在路由函数签名中声明依赖：async def get_users(db: Database = Depends(lambda: app.state.mysql)):
2、执行参数化查询：result = await db.fetch_all("SELECT * FROM users WHERE status = :status", {"status": "active"})
3、对敏感操作启用事务：async with db.transaction(): await db.execute("UPDATE accounts SET balance = balance - :amt WHERE id = :uid", {...})
五、验证连接状态与连接池健康度
仅凭应用启动无报错不能代表数据库真正连通。Qoder提供内置健康检查端点与诊断命令，用于实时探测连接池活跃数、平均响应延迟及最近失败原因，避免线上静默断连。
1、启动应用后访问 /health/db 端点，返回JSON中"status"为"ok"且"pool_size"大于0
2、执行CLI诊断命令：qodercli db ping --target mysql
3、查看日志中是否出现 "Connection acquired from pool" 或 "Pool max size reached" 提示
