{"id":21326,"library":"fastapi-sqlalchemy","title":"fastapi-sqlalchemy","description":"Provides a simple middleware and dependency to integrate SQLAlchemy sessions into FastAPI applications. Current version 0.2.1, last updated in 2021. Low release cadence; considered stable but minimal maintenance.","status":"maintenance","version":"0.2.1","language":"python","source_language":"en","source_url":"https://github.com/mfreeborn/fastapi-sqlalchemy","tags":["fastapi","sqlalchemy","database","middleware","orm","integration"],"install":[{"cmd":"pip install fastapi-sqlalchemy","lang":"bash","label":"install"}],"dependencies":[{"reason":"Required to run FastAPI app","package":"fastapi","optional":false},{"reason":"Core ORM library","package":"sqlalchemy","optional":false},{"reason":"Shared dependency with FastAPI","package":"pydantic","optional":false}],"imports":[{"note":"DBSessionMiddleware is exposed at package level","wrong":"from fastapi_sqlalchemy.middleware import DBSessionMiddleware","symbol":"DBSessionMiddleware","correct":"from fastapi_sqlalchemy import DBSessionMiddleware"},{"note":"The db object is a session proxy, import directly from package","wrong":"from fastapi_sqlalchemy.db import db","symbol":"db","correct":"from fastapi_sqlalchemy import db"}],"quickstart":{"code":"import os\nfrom fastapi import FastAPI\nfrom fastapi_sqlalchemy import DBSessionMiddleware, db\nfrom sqlalchemy import create_engine\n\napp = FastAPI()\nDATABASE_URL = os.environ.get('DATABASE_URL', 'sqlite:///test.db')\napp.add_middleware(DBSessionMiddleware, db_url=DATABASE_URL)\n\n@app.get('/')\ndef root():\n    # db.session is the current SQLAlchemy session\n    result = db.session.execute('SELECT 1').scalar()\n    return {'result': result}","lang":"python","description":"Initialize middleware, then use `db.session` for queries."},"warnings":[{"fix":"Always access `db` inside a FastAPI route or dependency.","message":"The `db` object is a thread-local proxy and must be accessed within the request lifecycle. Using it outside of a request context (e.g., at module level) will raise an error.","severity":"gotcha","affected_versions":"all"},{"fix":"Consider switching to FastAPI's built-in SQLAlchemy support with `Session` dependency injection or use sqlalchemy.ext.asyncio for async.","message":"The library is not actively maintained (last release 2021) and does not support newer SQLAlchemy 2.0 style. It uses the deprecated `Session` pattern.","severity":"deprecated","affected_versions":">=0.2.0"},{"fix":"Manually configure engine with `pool_pre_ping=True` using `engine_args` parameter in middleware.","message":"The middleware does not handle database disconnections or connection pooling gracefully by default. Long-running applications may experience stale connections.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Ensure `app.add_middleware(DBSessionMiddleware, db_url=...)` is called before any route that uses `db`.","cause":"Accessing `db.session` before the middleware has been added or outside a request context.","error":"RuntimeError: No database session found. Have you added the DBSessionMiddleware?"},{"fix":"Use `from fastapi_sqlalchemy import DBSessionMiddleware` (no submodule).","cause":"Importing from the wrong module path or outdated pip package.","error":"AttributeError: module 'fastapi_sqlalchemy' has no attribute 'DBSessionMiddleware'"},{"fix":"Use `Base.metadata.create_all(bind=engine)` before starting the app, using the same engine URL.","cause":"Tables not created because the middleware does not auto-create tables.","error":"sqlalchemy.exc.OperationalError: (sqlite3.OperationalError) no such table: ..."}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}