{"id":5500,"library":"sqladmin","title":"SQLAdmin","description":"SQLAdmin is a flexible and actively developed admin interface for SQLAlchemy models, designed for use with FastAPI and Starlette. It provides a UI for managing database models, leveraging WTForms for form building and Tabler for the UI. The library maintains a regular release cadence, with updates typically occurring every few weeks to a month.","status":"active","version":"0.24.0","language":"en","source_language":"en","source_url":"https://github.com/aminalaee/sqladmin","tags":["admin panel","fastapi","starlette","sqlalchemy","orm","web ui"],"install":[{"cmd":"pip install sqladmin","lang":"bash","label":"Basic Installation"},{"cmd":"pip install \"sqladmin[full]\"","lang":"bash","label":"Full Installation (with optional dependencies like email, pydantic, sqlalchemy-file)"}],"dependencies":[{"reason":"Common ASGI framework integration for building web applications.","package":"fastapi"},{"reason":"Core ASGI framework integration, FastAPI builds on Starlette.","package":"starlette"},{"reason":"Primary ORM for database interaction.","package":"sqlalchemy"},{"reason":"Used for generating forms within the admin interface.","package":"wtforms"},{"reason":"Support for SQLModel ORM models.","package":"sqlmodel","optional":true}],"imports":[{"symbol":"Admin","correct":"from sqladmin import Admin"},{"symbol":"ModelView","correct":"from sqladmin import ModelView"},{"note":"AuthenticationBackend is in a submodule, not directly under sqladmin.","wrong":"from sqladmin import AuthenticationBackend","symbol":"AuthenticationBackend","correct":"from sqladmin.authentication import AuthenticationBackend"}],"quickstart":{"code":"import os\nfrom fastapi import FastAPI\nfrom sqlalchemy import create_engine, Column, Integer, String\nfrom sqlalchemy.orm import declarative_base, sessionmaker\n\nfrom sqladmin import Admin, ModelView\n\n# 1. Database Setup\nDATABASE_URL = os.environ.get(\"DATABASE_URL\", \"sqlite:///./example.db\")\nengine = create_engine(DATABASE_URL, connect_args={\"check_same_thread\": False})\n\nBase = declarative_base()\n\nclass User(Base):\n    __tablename__ = \"users\"\n    id = Column(Integer, primary_key=True)\n    name = Column(String, default=\"Anonymous\")\n    email = Column(String, unique=True, nullable=False)\n\nBase.metadata.create_all(engine)\n\n# 2. FastAPI App Setup\napp = FastAPI(title=\"My SQLAdmin App\")\n\n# 3. SQLAdmin Setup\nadmin = Admin(app, engine, title=\"My Admin Panel\")\n\n# 4. Define ModelView\nclass UserAdmin(ModelView, model=User):\n    column_list = [User.id, User.name, User.email]\n    column_searchable_list = [User.name, User.email]\n    column_sortable_list = [User.id, User.name, User.email]\n    column_default_sort = ('id', True)\n\n# 5. Add ModelView to Admin\nadmin.add_view(UserAdmin)\n\n@app.get(\"/\")\nasync def read_root():\n    return {\"message\": \"Welcome! Visit /admin for the admin panel.\"}\n\n# To run this:\n# pip install fastapi uvicorn sqladmin sqlalchemy\n# uvicorn your_module_name:app --reload\n# Then navigate to http://127.0.0.1:8000/admin in your browser.","lang":"python","description":"This quickstart demonstrates how to integrate SQLAdmin into a FastAPI application, defining a simple SQLAlchemy model and exposing it through the admin panel. It sets up an in-memory SQLite database and registers a `UserAdmin` view."},"warnings":[{"fix":"Implement a custom `AuthenticationBackend` by inheriting `sqladmin.authentication.AuthenticationBackend` and configure your ASGI app with an appropriate authentication middleware (e.g., Starlette's `AuthenticationMiddleware`). Refer to the official documentation for examples.","message":"SQLAdmin does not include authentication by default. For production environments, you must implement a custom `AuthenticationBackend` and integrate it with your ASGI application's middleware. Failing to do so will leave your admin panel publicly accessible.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review your custom `AuthenticationBackend` implementation and update the `authenticate` method signature and logic to align with the changes introduced in the respective versions. Consult the `CHANGELOG.md` or official documentation for the exact signature updates.","message":"The `AuthenticationBackend.authenticate` method signature has undergone breaking changes in versions 0.10.0 and 0.12.0. Custom authentication backends developed for older versions may require updates to match the new method signature (e.g., to support OAuth or updated `Request` object access).","severity":"breaking","affected_versions":"0.10.0, 0.12.0"},{"fix":"Ensure your custom template files are placed within a `templates/sqladmin/` directory in your project's root or a configured template search path. If you previously referred to `some_template.html`, you might now need to refer to `sqladmin/some_template.html` if overriding.","message":"The internal structure for template files changed around version 0.17.0, moving default templates from the `templates/` directory to `templates/sqladmin/`. If you have custom templates that override SQLAdmin's default ones, their paths may need adjustment.","severity":"breaking","affected_versions":">=0.17.0"},{"fix":"To prevent `DetachedInstanceError`, explicitly eager-load relationships using `selectinload` or include the related columns in `ModelView.column_list` or `ModelView.column_details_list` so that SQLAdmin fetches them within the active session. Ensure your `get_session` method manages the session lifecycle correctly.","message":"When working with SQLAlchemy relationships, lazy-loaded relationships can cause `DetachedInstanceError` if accessed after the SQLAlchemy session has been closed. This is a common pitfall in ORM usage, especially in web contexts where sessions are typically short-lived.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}