{"id":3447,"library":"databases","title":"Asynchronous Database Toolkit","description":"The `databases` library provides asynchronous database support for Python, designed to work with `asyncio` and `await`. It supports PostgreSQL, MySQL, and SQLite, and integrates well with SQLAlchemy Core expression language. The current version is 0.9.0, and it has an active development cadence with regular updates.","status":"active","version":"0.9.0","language":"python","source_language":"en","source_url":"https://github.com/encode/databases","tags":["async","database","sql","sqlalchemy","asyncio","orm"],"install":[{"cmd":"pip install databases","lang":"bash","label":"Base installation"},{"cmd":"pip install databases[postgresql]","lang":"bash","label":"With PostgreSQL driver (asyncpg)"},{"cmd":"pip install databases[mysql]","lang":"bash","label":"With MySQL driver (aiomysql)"},{"cmd":"pip install databases[sqlite]","lang":"bash","label":"With SQLite driver (aiosqlite)"}],"dependencies":[{"reason":"Used for SQL expression language support, though raw SQL is also possible.","package":"sqlalchemy","optional":false},{"reason":"PostgreSQL database driver.","package":"asyncpg","optional":true},{"reason":"MySQL database driver. Alternatively, asyncmy can be used.","package":"aiomysql","optional":true},{"reason":"SQLite database driver.","package":"aiosqlite","optional":true}],"imports":[{"symbol":"Database","correct":"from databases import Database"},{"note":"Represents a single row from a database query result.","symbol":"Record","correct":"from databases import Record"}],"quickstart":{"code":"import asyncio\nimport os\nfrom databases import Database\n\nasync def main():\n    # Use an in-memory SQLite database for a simple example.\n    # For a real application, use a proper URL like DATABASE_URL = 'postgresql://user:pass@host/db'\n    database = Database(os.environ.get('DATABASE_URL', 'sqlite:///./test.db'))\n\n    try:\n        await database.connect()\n        print(\"Database connected.\")\n\n        # Create a table\n        query = \"\"\"\n            CREATE TABLE IF NOT EXISTS users (\n                id INTEGER PRIMARY KEY,\n                name VARCHAR(100)\n            );\n        \"\"\"\n        await database.execute(query=query)\n        print(\"Table 'users' created or already exists.\")\n\n        # Insert data\n        query = \"INSERT INTO users(name) VALUES (:name)\"\n        await database.execute(query=query, values={\"name\": \"Alice\"})\n        print(\"Inserted 'Alice'.\")\n\n        # Select data\n        query = \"SELECT id, name FROM users\"\n        rows = await database.fetch_all(query=query)\n        for row in rows:\n            print(f\"User: {row['id']}, {row['name']}\")\n\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n    finally:\n        await database.disconnect()\n        print(\"Database disconnected.\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n","lang":"python","description":"This quickstart demonstrates connecting to a database, executing a DDL statement to create a table, inserting a record, and fetching all records. It uses an in-memory SQLite database by default but can be configured with an environment variable for other databases. Remember to install the appropriate database driver (e.g., `pip install databases[sqlite]`)."},"warnings":[{"fix":"Ensure your project runs on Python 3.8 or higher. If using SQLAlchemy, consider upgrading to SQLAlchemy 2.x. If you must use older SQLAlchemy 1.x, consult `databases` documentation for specific version compatibility.","message":"Version 0.9.0 dropped support for Python 3.7 and earlier versions. Additionally, it now officially supports SQLAlchemy 2.x, which might introduce compatibility issues if you are still using older SQLAlchemy 1.x versions.","severity":"breaking","affected_versions":">=0.9.0"},{"fix":"Carefully review concurrent database operations in your application. Ensure that connections and transactions are explicitly managed or passed between tasks where shared behavior is intended, rather than relying on implicit inheritance.","message":"In version 0.8.0, connection and transaction isolation was significantly improved. Database connections are now task-local and not inherited by child tasks. The `@db.transaction` decorator uses the calling task's connection, and new tasks use new connections unless explicitly provided.","severity":"breaking","affected_versions":">=0.8.0"},{"fix":"Always install `databases` with the appropriate extras, e.g., `pip install databases[postgresql]`, or install the driver manually.","message":"You must install the specific database driver package for your chosen database alongside `databases`. For example, `pip install databases asyncpg` for PostgreSQL, `pip install databases aiomysql` for MySQL, or `pip install databases aiosqlite` for SQLite. Installing just `databases` is not sufficient for database connectivity.","severity":"gotcha","affected_versions":"all"},{"fix":"Always check the specific release notes for `databases` regarding SQLAlchemy compatibility. For `>=0.9.0`, it's highly recommended to use SQLAlchemy 2.x. If sticking with SQLAlchemy 1.x, careful version pinning of both `databases` and `SQLAlchemy` is required.","message":"Compatibility with SQLAlchemy 1.4.x has been a recurring issue across several `databases` versions, with specific pins and fixes (e.g., `0.6.2` pinned `<=1.4.41`, `0.7.0` supported `>=1.4.42,<1.5`). While `0.9.0` adds SQLAlchemy 2.x support, transitioning from older SQLAlchemy 1.x with `databases` can be complex.","severity":"gotcha","affected_versions":"0.6.0 - 0.9.0"}],"env_vars":null,"search_vec":"'0.9.0':38 'activ':43 'async':49 'asynchron':1,8 'asyncio':17,53 'await':19 'cadenc':45 'core':31 'current':35 'databas':2,5,9,50 'design':13 'develop':44 'express':32 'integr':27 'languag':33 'librari':6 'mysql':23 'orm':54 'postgresql':22 'provid':7 'python':12 'regular':47 'sql':51 'sqlalchemi':30,52 'sqlite':25 'support':10,21 'toolkit':3 'updat':48 'version':36 'well':28 'work':15","created_at":"2026-04-11T17:29:30.582184+00:00","updated_at":"2026-04-16T05:11:02.031935+00:00","problems":[{"fix":"Install the library using pip: `pip install databases`. If a specific database backend is used, ensure its corresponding async driver is also installed, e.g., `pip install databases[postgresql]` (which installs `asyncpg`) or `pip install databases[mysql]` (which installs `aiomysql`) or `pip install databases[sqlite]` (which installs `aiosqlite`).","cause":"The `databases` library is not installed in the Python environment, or is not available in the active environment.","error":"ModuleNotFoundError: No module named 'databases'"},{"fix":"Ensure `await database.connect()` is called and awaited before any database interactions. For robust connection management, use an `async with` block: `async with database: await database.fetch_one(...)`.","cause":"A database operation (e.g., `execute`, `fetch_one`) was attempted on a `databases.Database` instance before an active connection was established using `await database.connect()`.","error":"RuntimeError: Database must be connected before use."},{"fix":"Verify that the database server is running, the connection URL (host, port, database name, user, password) is absolutely correct, and network configurations (like firewalls) permit the connection.","cause":"The underlying PostgreSQL database server is not running, is not accessible at the specified host/port, or network/firewall rules are blocking the connection. Similar errors can occur with other database types (e.g., `OperationalError` for MySQL or SQLite).","error":"asyncpg.exceptions.CannotConnectNowError: connection refused"},{"fix":"Install the required driver. For PostgreSQL, use `pip install asyncpg`. For MySQL, `pip install aiomysql`. For SQLite, `pip install aiosqlite`. Using `pip install databases[backend_name]` is the recommended way to ensure correct driver installation.","cause":"The `databases` library was initialized with a database URL specifying a backend driver (e.g., `postgresql+asyncpg`) but the corresponding asynchronous driver (`asyncpg` in this example) is not installed in the Python environment.","error":"ValueError: No driver for postgresql+asyncpg available."}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.9.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/encode/databases","docs":null,"changelog":null,"pypi":"https://pypi.org/project/databases/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","web-framework","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-28","install_tag":null}}