{"id":23219,"library":"aiosql","title":"aiosql – Simple SQL in Python","description":"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.","status":"active","version":"15.0","language":"python","source_language":"en","source_url":"https://github.com/nackjicholson/aiosql","tags":["sql","async","database","query-loader"],"install":[{"cmd":"pip install aiosql","lang":"bash","label":"PyPI"}],"dependencies":[],"imports":[{"note":"aiosql is a module, not a class. Import the module directly.","wrong":"from aiosql import aiosql","symbol":"aiosql","correct":"import aiosql"},{"note":"The function to load queries from a file is `from_path`. `from_query` does not exist in recent versions.","wrong":"from aiosql import from_query","symbol":"from_query","correct":"from aiosql import from_path"}],"quickstart":{"code":"import aiosql\nimport sqlite3\n\nconn = sqlite3.connect(\":memory:\")\nconn.execute(\"CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)\")\nconn.execute(\"INSERT INTO users VALUES (1, 'Alice')\")\nconn.commit()\n\n# Write a SQL file: queries/users.sql\n# -- name: get_user\n# SELECT * FROM users WHERE id = ?\n\nqueries = aiosql.from_path(\"queries\", \"sqlite3\")\nuser = queries.get_user(conn, user_id=1)\nprint(user)","lang":"python","description":"Load SQL queries from a directory and call them as Python functions."},"warnings":[{"fix":"Change to `aiosql.from_path('queries', 'sqlite3')` or pass the module object: `aiosql.from_path('queries', aiosql.adapters.sqlite)`.","message":"In 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.","severity":"breaking","affected_versions":">=11.0"},{"fix":"Ensure each SQL file has unique `-- name:` tags. Use a single directory or namespace with subdirectories.","message":"Query names must be unique across all .sql files loaded; duplicates cause silent overwrite of the earlier one.","severity":"gotcha","affected_versions":"all"},{"fix":"Replace `aiosql.from_sql(...)` with `aiosql.from_str(...)` or `aiosql.from_path(...)`.","message":"The `from_sql` function was removed in version 10.0. Use `from_path` or `from_str` instead.","severity":"deprecated","affected_versions":">=10.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"pip install aiosql","cause":"aiosql is not installed.","error":"ModuleNotFoundError: No module named 'aiosql'"},{"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`.","cause":"The query name in the SQL file does not match the Python call, or the file was not loaded properly.","error":"aiosql.exceptions.AioSQLQueryNotFoundError: No query named 'get_user'"},{"fix":"Use `aiosql.from_path('queries', 'sqlite3')` or `aiosql.from_path('queries', driver_name='sqlite3')`.","cause":"Using old keyword argument name; `driver` was renamed to `driver_name` or changed to positional.","error":"TypeError: from_path() got an unexpected keyword argument 'driver'","affected_versions":">=11.0"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}