---
id: aiosql
version: "15.0"
license: BSD-2-Clause
license_treatment: permissive
maintenance: active
---

# aiosql — Simple SQL in Python

License: permissive · Maintenance: active · Downloads: 162.6K/mo

## 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 above — 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

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

- License: BSD-2-Clause (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 162.6K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

SQL queries from files, external SQL file loader, yesql python, SQL file management, database query organization, sync async SQL driver, parametric SQL execution, sql-file-loader, async-database

[View on SkillFed](https://skillfed.io/packages/aiosql) · [View on PyPI](https://pypi.org/project/aiosql/)