aiosql

What it is and what it does

aiosql lets you organize SQL queries in separate .sql files and load them into Python as callable methods, rather than embedding SQL as strings in your code. This approach keeps your SQL reusable—you can run the same queries in psql or other database tools without modification—while maintaining clean separation between SQL and Python logic.

The package works with both synchronous PEP 249 drivers (sqlite3, psycopg2, PyMySQL, etc.) and asyncio-based drivers (aiosqlite, asyncpg, asyncmy, etc.). You write parametric SQL with named parameters, load the file via aiosql.from_path(), and call queries by name, passing a connection object and any required parameters. It's a lightweight alternative to ORMs when you want to write and maintain SQL directly.

Use it for:

• Organize complex SQL queries in version-controlled .sql files for a Python application using SQLite or PostgreSQL
• Run the same parameterized SQL queries from both Python code and command-line tools like psql without duplication
• Build async applications that execute multiple SQL queries concurrently using aiosqlite or asyncpg
• Maintain SQL code separately from Python when you prefer hand-written queries over ORM-generated SQL
• Support multiple database backends (SQLite, PostgreSQL, MySQL, DuckDB) with a single query file and driver parameter

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Load SQL queries from files and call them as Python methods, supporting both sync and async database drivers across SQLite, PostgreSQL, MySQL, MariaDB, DuckDB, and MS SQL Server.

Yes. aiosql is actively maintained, has no runtime dependencies, requires only Python >=3.10, and carries no known vulnerabilities. It's worth installing if you want to keep SQL in files and call it from Python without an ORM, and you're comfortable writing SQL directly. Skip it if you need an ORM or prefer SQL-like syntax in Python.

Install

aiosql on PyPI

pip install aiosql

uv add aiosql

poetry add aiosql

Installing aiosql

Before you install

Low friction install with no runtime dependencies. Active maintenance with last commit 2026-07-10 and 1409 repository stars. Requires Python >=3.10.

License in practice

BSD-2-Clause permissive license allows commercial and private use with minimal restrictions.

Quickstart

pip install aiosql

import aiosql
import sqlite3

queries = aiosql.from_path("greetings.sql", "sqlite3")
with sqlite3.connect("greetings.db") as conn:
    user = queries.get_user_by_username(conn, username="willvaughn")

Requires Python >=3.10 and a compatible database driver (sqlite3, psycopg, asyncpg, etc.) installed separately.

Verify before relying

• Whether all listed database drivers work equally well or if some have known limitations beyond what the description states
• Performance characteristics when loading and executing many queries from a single SQL file

Package facts

Evidence: aiosql-15.0-py3-none-any.whl

Tags

More Python Modules packages