Registry / database / aiosql

aiosql

JSON →
library15.0pypypi✓ verified 84d ago

aiosql allows you to write SQL queries in separate .sql files and call them directly from Python as async or sync functions. It supports multiple database drivers (sqlite3, aiosqlite, psycopg2, asyncpg, etc.) and provides a clean separation of SQL and Python. Current version 15.0, requires Python ≥3.10. Release cadence is irregular but actively maintained.

database
pip install aiosql
github ↗package ↗homepage ↗docs ↗
INSTALL
IMPORT
SIG · AIOSQL
A
aiosql
databasepythonv15.0
Install
1.6s avg
Import
143ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v15.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.148s · 18MB
glibc
py 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.138s · 19MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

aiosql
✓ import aiosql
✗ from aiosql import aiosql
aiosql is a module, not a class. Import the module directly.
from_query
✓ from aiosql import from_path
✗ from aiosql import from_query
The function to load queries from a file is `from_path`. `from_query` does not exist in recent versions.

Load SQL queries from a directory and call them as Python functions.

import aiosql import sqlite3 conn = sqlite3.connect(":memory:") conn.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)") conn.execute("INSERT INTO users VALUES (1, 'Alice')") conn.commit() # Write a SQL file: queries/users.sql # -- name: get_user # SELECT * FROM users WHERE id = ? queries = aiosql.from_path("queries", "sqlite3") user = queries.get_user(conn, user_id=1) print(user)
Debug
Known issues
breakingIn version 11.0, the `from_path` and `from_str` signatures changed: the driver name changed from a string like 'sqlite' to the actual driver module or string (e.g., 'sqlite3'). Old code using `aiosql.from_path('queries', 'sqlite')` will break.
fix
Change to `aiosql.from_path('queries', 'sqlite3')` or pass the module object: `aiosql.from_path('queries', aiosql.adapters.sqlite)`.
affects: >=11.0
gotchaQuery names must be unique across all .sql files loaded; duplicates cause silent overwrite of the earlier one.
fix
Ensure each SQL file has unique `-- name:` tags. Use a single directory or namespace with subdirectories.
affects: all
deprecatedThe `from_sql` function was removed in version 10.0. Use `from_path` or `from_str` instead.
fix
Replace `aiosql.from_sql(...)` with `aiosql.from_str(...)` or `aiosql.from_path(...)`.
affects: >=10.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'aiosql'
aiosql is not installed.
fix
pip install aiosql
aiosql.exceptions.AioSQLQueryNotFoundError: No query named 'get_user'
The query name in the SQL file does not match the Python call, or the file was not loaded properly.
fix
Check that the SQL file contains `-- name: get_user` (case-sensitive, exact match) and that the file is in the directory passed to `from_path`.
TypeError: from_path() got an unexpected keyword argument 'driver'
Using old keyword argument name; `driver` was renamed to `driver_name` or changed to positional.
fix
Use `aiosql.from_path('queries', 'sqlite3')` or `aiosql.from_path('queries', driver_name='sqlite3')`.
Upgrade
Version history
15.0latest on PyPI · released Jan 4, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
41 hits · last 30 days
node
34
OpenAI (training)
2
Resources
githubhttps://github.com/nackjicholson/aiosql ↗
packagehttps://pypi.org/project/aiosql/ ↗
homepagehttps://nackjicholson.github.io/aiosql/ ↗
docshttps://nackjicholson.github.io/aiosql/ ↗