SQLAdmin

0.24.0 · active · verified Mon Apr 13

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.

Warnings

gotcha 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.
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.
breaking 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).
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.
breaking 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.
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.
gotcha 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.
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.

Install

pip install sqladmin Basic Installation
pip install "sqladmin[full]" Full Installation (with optional dependencies like email, pydantic, sqlalchemy-file)

Imports

Admin
```
from sqladmin import Admin
```
ModelView
```
from sqladmin import ModelView
```
AuthenticationBackend
```
from sqladmin.authentication import AuthenticationBackend
```
AuthenticationBackend is in a submodule, not directly under sqladmin.

Quickstart

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.

import os
from fastapi import FastAPI
from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.orm import declarative_base, sessionmaker

from sqladmin import Admin, ModelView

# 1. Database Setup
DATABASE_URL = os.environ.get("DATABASE_URL", "sqlite:///./example.db")
engine = create_engine(DATABASE_URL, connect_args={"check_same_thread": False})

Base = declarative_base()

class User(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True)
    name = Column(String, default="Anonymous")
    email = Column(String, unique=True, nullable=False)

Base.metadata.create_all(engine)

# 2. FastAPI App Setup
app = FastAPI(title="My SQLAdmin App")

# 3. SQLAdmin Setup
admin = Admin(app, engine, title="My Admin Panel")

# 4. Define ModelView
class UserAdmin(ModelView, model=User):
    column_list = [User.id, User.name, User.email]
    column_searchable_list = [User.name, User.email]
    column_sortable_list = [User.id, User.name, User.email]
    column_default_sort = ('id', True)

# 5. Add ModelView to Admin
admin.add_view(UserAdmin)

@app.get("/")
async def read_root():
    return {"message": "Welcome! Visit /admin for the admin panel."}

# To run this:
# pip install fastapi uvicorn sqladmin sqlalchemy
# uvicorn your_module_name:app --reload
# Then navigate to http://127.0.0.1:8000/admin in your browser.

view raw JSON →