playbooks

home / skills / jik92 / sqladmin-skills / sqladmin

sqladmin skill

/sqladmin

This skill helps you build and tailor SQLAdmin interfaces for SQLAlchemy models in FastAPI or Starlette apps, including authentication, views, and async

npx playbooks add skill jik92/sqladmin-skills --skill sqladmin

Review the files below or copy the command above to add this skill to your agents.

Files (9)
SKILL.md
3.1 KB
---
name: sqladmin
description: Build and maintain SQLAdmin admin interfaces for SQLAlchemy models in FastAPI or Starlette apps. Use when you need to add an admin UI, configure ModelView behavior (lists, forms, filters, exports), add authentication/authorization or role-based permissions, customize templates, add custom views/actions, integrate file/image uploads, or set up async SQLAlchemy engines/sessions.
---

# SQLAdmin

## Overview
Use this skill to implement SQLAdmin in FastAPI/Starlette apps, wire SQLAlchemy engines/sessions (sync or async), and tailor the admin UI via ModelView configuration, authentication, templates, and extensions.

## Trigger examples
- “Add an admin dashboard for my SQLAlchemy models in FastAPI.”
- “Lock down the admin so only users with role=admin can access certain models.”
- “Make SQLAdmin work with an async engine and async sessionmaker.”
- “Customize list columns and add a custom action button.”
- “Override SQLAdmin templates for a custom layout.”

## Quick start
1) Create the SQLAlchemy engine (sync or async) and your models.
2) Initialize `Admin(app, engine)` (or pass a `session_maker`).
3) Define a `ModelView` for each model and `add_view` it.
4) Visit `/admin` (or your custom base URL).

See `references/quickstart.md` for a minimal setup pattern.

## Core tasks

### Configure ModelView behavior
- Lists, details, sorting, searching, filtering, pagination, and export options.
- Form scaffolding, overrides, and relationship field behaviors.
- Permissions and metadata (labels, icons, categories).

Use `references/configurations.md` for all ModelView options and examples.

### Add authentication and access control
- Add `AuthenticationBackend` to the `Admin` instance.
- Implement per-view visibility and access checks via `is_visible` / `is_accessible`.

Use `references/authentication.md` for the required methods and patterns.

### Role-based permissions
- Implement role checks in `is_accessible` and `is_visible`.
- Apply per-model restrictions and per-action guards.

Use `references/permissions.md` for role and policy patterns.

### Async SQLAlchemy integration
- Use `create_async_engine` and async `sessionmaker`.
- Ensure ModelView hooks handle async sessions correctly.

Use `references/async.md` for async engine/session patterns.

### Customize templates and add custom views
- Override built-in templates or point views to custom templates.
- Add custom pages with `BaseView` and `@expose`.

Use `references/templates-and-views.md` for template and custom view patterns.

### File and image fields
- Use `fastapi-storages` integrations for `FileType` / `ImageType` columns.

Use `references/files.md` for the storage-backed field setup.

### Admin initialization options
- Customize base URL, title, logo, favicon, middlewares, and template directory.

Use `references/admin-init.md` for the `Admin` constructor options.

## References
- `references/quickstart.md`
- `references/configurations.md`
- `references/authentication.md`
- `references/permissions.md`
- `references/async.md`
- `references/templates-and-views.md`
- `references/files.md`
- `references/admin-init.md`

Overview

This skill builds and maintains SQLAdmin admin interfaces for SQLAlchemy models in FastAPI or Starlette apps. It wires sync or async SQLAlchemy engines/sessions, configures ModelView behavior, and adds authentication, role-based permissions, custom templates, and file/image upload integrations. Use it to quickly expose a polished admin UI and to extend admin features with custom views and actions.

How this skill works

I initialize an Admin instance with your FastAPI/Starlette app and a SQLAlchemy engine or sessionmaker (sync or async). For each model I create a ModelView that configures lists, forms, filters, exports, and relationship fields, then add those views to the Admin instance. Authentication backends, per-view access checks, template overrides, custom BaseView pages, and storage-backed file/image columns are wired through documented hooks and options.

When to use it

  • You need an admin dashboard to manage SQLAlchemy models in a FastAPI/Starlette project.
  • You want role-based access and per-model or per-action permissions in the admin UI.
  • You must run an async SQLAlchemy engine/session (asyncio) with admin views.
  • You want to customize list columns, forms, filters, exports, or add custom actions.
  • You need file/image upload support integrated into admin forms and listings.

Best practices

  • Use explicit ModelView configurations for lists, search, filters, and pagination to avoid leaking sensitive fields.
  • Implement AuthenticationBackend with is_accessible/is_visible checks for role enforcement and per-view guards.
  • Prefer async sessionmakers and ensure ModelView hooks use async patterns when running an async engine.
  • Override only the templates you need and keep a fallback to defaults to reduce maintenance.
  • Use storage integrations (e.g., fastapi-storages) for robust file and image handling and avoid storing files directly in the DB.

Example use cases

  • Add a single /admin dashboard that exposes Product, User, and Order models with role-based access so only admins can edit users.
  • Make SQLAdmin work with an async SQLAlchemy engine and async sessionmaker in an asyncio FastAPI app.
  • Customize a ModelView to show specific columns, add filters and a CSV export for reporting.
  • Create a custom BaseView page with analytics and add a ModelView action button to trigger batch operations.
  • Integrate image upload fields for a Product model using storage-backed ImageType columns.

FAQ

Can SQLAdmin work with async SQLAlchemy sessions?

Yes. Initialize with create_async_engine and an async sessionmaker and ensure ModelView hooks use async-compatible code.

How do I restrict access to only admin users?

Implement an AuthenticationBackend and apply role checks inside is_accessible and is_visible on your ModelView classes or centrally on the Admin instance.