Starlette Admin

Common errors

• ModuleNotFoundError: No module named 'sqlalchemy'

  cause Attempting to use `SQLAlchemyModelView` without installing the `sqla` extra dependency.
  fix Install `starlette-admin` with the SQLAlchemy extra: `pip install "starlette-admin[sqla]`"

• TypeError: Admin.__init__() missing 1 required positional argument: 'engine'

  cause The `Admin` class constructor requires a database engine/client instance when using ORM-specific ModelViews, or you are trying to instantiate `Admin` without any arguments for CustomViews.
  fix Pass your database engine (e.g., SQLAlchemy `engine`, Beanie `database`, etc.) to the `Admin` constructor: `admin = Admin(engine=my_engine)`

• TypeError: 'User' object is not callable

  cause This error often occurs when setting up SQLAlchemy and forgetting to call `Base.metadata.create_all(bind=engine)` to create the database tables before Starlette Admin tries to access them.
  fix Ensure `Base.metadata.create_all(bind=engine)` is executed to create your database schema when your application starts.

• AttributeError: 'Session' object has no attribute 'add_all'

  cause This specific error is less about starlette-admin and more about direct SQLAlchemy usage, but a common pitfall is mixing `session.add()` for single objects with `session.add_all()` for lists of objects. Ensure your bulk insertions match the correct SQLAlchemy session method.
  fix Use `session.add(obj)` for single objects and `session.add_all([obj1, obj2])` for iterables of objects.

Warnings

• gotcha When using ORM-specific ModelViews (e.g., `SQLAlchemyModelView`, `BeanieModelView`), ensure you install the correct extra dependencies (e.g., `starlette-admin[sqla]`, `starlette-admin[beanie]`) to avoid `ModuleNotFoundError`.
  Fix: Install with `pip install "starlette-admin[<orm_name>]"` (e.g., `starlette-admin[sqla]`)
• breaking Version 0.15.0 upgraded Odmantic support to v1.0+. If you were using Odmantic with an older version of `starlette-admin` (pre-0.15.0) and Odmantic v0.x, you might face breaking changes due to Odmantic's API changes.
  Fix: Review Odmantic v1.0 migration guides and update your Odmantic models and database interactions accordingly. Then, upgrade `starlette-admin`.
• gotcha Authentication and authorization are not included by default. You must implement your own security layer (e.g., using `starlette.middleware.authentication.AuthMiddleware` or FastAPI's dependency injection) to protect your admin panel.
  Fix: Implement custom authentication/authorization using Starlette/FastAPI's security features and integrate it with Starlette Admin via custom routes or middleware.
• deprecated Older versions (pre-0.15.0) might trigger deprecation warnings related to `TemplateResponse` and `Jinja2Templates` usage from Starlette. These have been addressed in 0.15.0.
  Fix: Upgrade to `starlette-admin` version 0.15.0 or newer to resolve these warnings. No code changes are typically required on your end unless you've customized templates.

Install

• pip install starlette-admin Core Installation
• pip install "starlette-admin[sqla]" With SQLAlchemy support
• pip install "starlette-admin[beanie]" With Beanie (MongoDB) support
• pip install "starlette-admin[full]" With all ORM and extra features

Imports

• Admin
  wrong:

  from starlette_admin import Admin

  correct:

  from starlette_admin.app import Admin

  The Admin class is located in the `app` submodule.
• ModelView
  wrong:

  from starlette_admin.views import ModelView

  correct:

  from starlette_admin.contrib.sqla import ModelView

  ORM-specific ModelViews are located in `contrib.*` submodules (e.g., `sqla`, `beanie`). The base `ModelView` in `views` is abstract.
• BaseModelView

  from starlette_admin.views import BaseModelView

Quickstart

This quickstart demonstrates how to integrate Starlette Admin with a FastAPI application using SQLAlchemy. It sets up a basic `User` model, initializes the admin interface with a `ModelView` for `User`, and mounts it to the FastAPI app. Ensure you install `starlette-admin[sqla]` and `uvicorn` to run this example.

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

from starlette_admin.app import Admin
from starlette_admin.contrib.sqla import ModelView

# 1. Setup Database (SQLAlchemy Example)
DATABASE_URL = "sqlite:///./test.db"
engine = create_engine(DATABASE_URL, connect_args={"check_same_thread": False})
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
Base = declarative_base()

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

# Create tables
Base.metadata.create_all(bind=engine)

# 2. Setup FastAPI App
app = FastAPI()

# 3. Setup Starlette Admin
admin = Admin(engine, title="My Admin Dashboard")

# Add ModelViews
admin.add_view(ModelView(User))

# Mount Admin to FastAPI
admin.mount_to(app)

# Optional: Add a root route
@app.get("/", include_in_schema=False)
async def read_root():
    return {"message": "Welcome to FastAPI with Starlette Admin!"}

if __name__ == "__main__":
    # Populate some data if needed (run once)
    with SessionLocal() as db:
        if not db.query(User).first():
            db.add(User(name="Alice", email="alice@example.com"))
            db.add(User(name="Bob", email="bob@example.com"))
            db.commit()
    uvicorn.run(app, host="0.0.0.0", port=8000)