aiosql报错主因是路径/命名/驱动配置不当：SQL文件须统一放queries/目录下，块名全局唯一；PostgreSQL需指定driver_name="psycopg"；异步方法必须await调用。
SQL 文件路径怎么组织才不会报 aiosql.exceptions.SQLLoadException
aiosql 从文件加载 SQL 时，默认只认 .sql 后缀，且对目录结构敏感。路径写错、文件没被发现、或 SQL 块名重复，都会直接抛这个异常。
- 确保所有 SQL 文件放在一个明确的根目录下（比如
queries/），不要嵌套过深，避免用相对路径如../queries/—— aiosql 不解析上级路径 - 每个
.sql文件里，SQL 块必须以-- name: block_name开头，后面紧跟换行和 SQL 语句；block_name在整个加载范围内必须唯一，否则会静默覆盖或报错 - 如果用了子目录（如
queries/users/get_user.sql），加载时得传完整路径：aiosql.from_path("queries/users", "sqlite3")，不能只传"queries"然后指望它递归扫描
如何让 aiosql.from_path() 正确识别 PostgreSQL 的 $1 占位符
aiosql 默认按 SQLite 风格解析参数（?），PostgreSQL 用 $1、$2 时，必须显式指定驱动类型，否则会把 $1 当字面量处理，导致语法错误或空结果。
- 调用
aiosql.from_path()时，第二个参数必须是字符串"psycopg"（不是"postgresql"或"pg"）；用asyncpg驱动则填"asyncpg" - SQL 文件中写
WHERE id = $1是 OK 的，但不能混用风格，比如WHERE id = ? AND name = $1—— aiosql 只按驱动类型统一解析一种占位符 - 如果用的是
psycopg2（非异步），别用aiosql，它专为异步驱动设计；同步场景该用sqlalchemy或原生psycopg2
为什么 query.run() 报 TypeError: 'coroutine' object is not iterable
这是最常见的误用：把异步查询当同步函数调了。aiosql 返回的 query 对象方法全是 async def，必须 await，不能直接 .run() 就完事。
- 确认你用的是支持异步的驱动（
psycopg/asyncpg/aiomysql），并用aiosql.from_path(..., driver_name="...")显式声明 - 调用时必须加
await：await queries.users.get_by_id(conn, user_id=123)；漏掉await就会返回 coroutine 对象，后续 if/for 里直接用就崩 - 别在普通函数里调异步 query —— 比如 FastAPI 的依赖函数里写了
def get_queries()而不是async def，即使里面 await 了，外层没 async 上下文也白搭
SQL 文件里怎么安全写多语句（比如带 WITH 或多个 SELECT）
aiosql 本身不禁止多语句，但它只取第一个语句的结果集。如果你的 SQL 文件里写了两个 SELECT，第二个会被忽略；而 WITH 是允许的，只要它属于同一个逻辑查询块。
立即学习“Python免费学习笔记（深入）”；
-
WITH子句完全 OK：WITH active_users AS (...) SELECT * FROM active_users;是标准单语句，aiosql 正常解析 - 分号结尾不是必须的，但加了也没问题；千万别写成
SELECT ...; SELECT ...;—— 第二个SELECT会被丢弃，且无警告 - 如果真需要多个独立查询，拆成不同
-- name:块，比如-- name: get_active_users和-- name: count_active_users，各自维护更清晰
事情说清了就结束。最常卡住的地方其实是驱动名拼错、忘了 await、还有 SQL 块名重复——这三个点查日志时往往不报具体哪行，得人工翻文件核对。
