SQLAdmin Documentation

To integrate SQLAdmin into a FastAPI application, initialize the Admin class with your FastAPI app instance and your SQLAlchemy engine. Define a class inheriting from ModelView, specifying the model to manage, and then register it using admin.add_view(). By default, the admin interface is available at the /admin path.

from fastapi import FastAPI
from sqladmin import Admin, ModelView

# Assuming 'engine' and 'User' model are already defined
app = FastAPI()
admin = Admin(app, engine)

class UserAdmin(ModelView, model=User):
    column_list = [User.id, User.name]

admin.add_view(UserAdmin)

To integrate SQLAdmin into a Starlette application, initialize the Admin class with your Starlette app instance and your SQLAlchemy engine. Define a class inheriting from ModelView, specifying the model to manage, and then register it using admin.add_view(). The admin interface is available at /admin.

from sqladmin import Admin, ModelView
from starlette.applications import Starlette

# Assuming 'engine' and 'User' model are already defined
app = Starlette()
admin = Admin(app, engine)

class UserAdmin(ModelView, model=User):
    column_list = [User.id, User.name]

admin.add_view(UserAdmin)

You can control which fields appear in the Admin console's creation and editing forms by using form_create_rules and form_edit_rules. This is useful for hiding sensitive fields (like passwords) during edits while allowing them during initial creation.

• form_create_rules: A list of field names to include in the 'Create' form.
• form_edit_rules: A list of field names to include in the 'Edit' form.

class UserAdmin(ModelView, model=User):
    # Only show name and password when creating
    form_create_rules = ["name", "hashed_password"]
    
    # Only show name when editing (hides password)
    form_edit_rules = ["name"]

To access the Starlette/FastAPI request object during database operations (create, update, or delete), you can override the following methods in your ModelView class:

• insert_model(request, data): Triggered when creating a new record.
• update_model(request, pk, data): Triggered when updating an existing record (where pk is the primary key).
• delete_model(request, pk): Triggered when deleting a record.

This is useful for accessing request.user to perform audit logging or to automatically assign ownership of a record to the currently authenticated user.

class PostAdmin(ModelView, model=Post):
    async def insert_model(self, request, data):
        data["author_id"] = request.user.id
        return await super().insert_model(request, data)

New languages must be added to the package source. The workflow uses Babel and the provided Makefile targets. Run these commands from the repository root:

1. Extract strings: Refresh the .pot template and sync existing catalogs: make i18n-extract
2. Initialize locale: Create a new catalog (e.g., for French): make i18n-init LOCALE=fr
3. Translate: Edit the generated .po file at sqladmin/translations/fr/LC_MESSAGES/admin.po. Important: Remove the #, fuzzy line from the header after reviewing translations to ensure compilation.
4. Compile: Convert .po files into binary .mo files: make i18n-compile

Finally, add the new locale code to SUPPORTED_LOCALES in sqladmin/i18n.py and commit both the .po and .mo files.

make i18n-extract
make i18n-init LOCALE=fr
# ... translate file ...
make i18n-compile

Pass configuration options to an editor field using the form_args dictionary in your ModelView, following the standard WTForms field argument pattern.

from sqladmin.editors import CKEditor5Field

class PostAdmin(ModelView, model=Post):
    form_overrides = {"content": CKEditor5Field}
    form_args = {"content": {"min_height": 300}}

To add custom pages like dashboards or custom forms to the SQLAdmin interface, inherit from BaseView. You can define the view's display name using name, an icon using icon (FontAwesome syntax), and define endpoints using the @expose decorator.

By default, SQLAdmin looks for templates in a templates directory. If you use a custom directory, configure it when initializing the Admin object using templates_dir.

from sqladmin import BaseView, expose

class ReportView(BaseView):
    name = "Report Page"
    icon = "fa-solid fa-chart-line"

    @expose("/report", methods=["GET"])
    async def report_page(self, request):
        return await self.templates.TemplateResponse(request, "report.html")

admin.add_view(ReportView)

To use SQLAdmin in a FastAPI application, initialize the Admin class with your FastAPI app instance and your SQLAlchemy engine. Then, create a class that inherits from ModelView, specifying the SQLAlchemy model it manages, and add it to the admin instance using add_view().

from fastapi import FastAPI
from sqladmin import Admin, ModelView

app = FastAPI()
admin = Admin(app, engine)

class UserAdmin(ModelView, model=User):
    column_list = [User.id, User.name]

admin.add_view(UserAdmin)

To support multiple databases (partitioning) in sqladmin, do not pass an engine to the Admin constructor. Instead, configure a SQLAlchemy sessionmaker with specific binds for different models and pass that factory to the session_maker argument of Admin.

This allows you to route different models (e.g., User to engine1 and Account to engine2) to different database engines within the same admin interface.

When editing a model with many related records (e.g., a One-To-Many or Many-To-Many relationship), SQLAdmin defaults to loading all related objects into an HTML select element. For large tables, this causes significant performance issues.

To prevent loading all records at once, use form_ajax_refs to enable AJAX-based searching and loading for specific relationship fields. This allows users to search for related objects via an asynchronous call.

class ParentAdmin(ModelView, model=Parent):
    form_ajax_refs = {
        "children": {
            "fields": ("id",),
            "order_by": "id",
        }
    }