Flask-AppBuilder

Warnings

• breaking Flask-AppBuilder 5.0.0 completely removed support for MongoDB/MongoEngine and OpenID 2.0 authentication. Applications relying on these backends will require significant migration to SQLAlchemy-based databases and alternative authentication methods (e.g., OAuth2, LDAP, SAML). [1, 11, 16, 17]
  Fix: Migrate MongoDB data to a supported SQL database (PostgreSQL, MySQL, SQLite, etc.). Update models to use SQLAlchemy syntax. Switch from OpenID 2.0 to OAuth 2.0, LDAP, SAML, or database authentication. Remove `flask-mongoengine`, `mongoengine`, `pymongo`, `flask-openid` dependencies. [1]
• breaking Version 5.0.0 introduced breaking changes for SQLAlchemy 2.x and Flask-SQLAlchemy 3.x compatibility. This affects query syntax, session handling, relationship loading, and potentially the `SQLA` import path or how the SQLAlchemy object is passed to `AppBuilder`. [1, 11, 13, 24, 25]
  Fix: Review and update SQLAlchemy query patterns to align with 2.x best practices. Ensure Flask-SQLAlchemy is configured correctly. For `AppBuilder` initialization, pass `db.session` directly rather than the `db` object itself. If encountering `SQLA` import errors, consider `from flask_appbuilder.utils.legacy import get_sqla_class()` or use Flask-SQLAlchemy's `db` object directly for models and session. [1, 13]
• breaking Flask-AppBuilder 4.0.0 introduced major version bumps for several core Flask dependencies including Flask (1.x to 2.x), Flask-JWT-Extended (3.x to 4.x), Jinja2 (2.x to 3.x), Werkzeug (1.x to 2.x), pyJWT (1.x to 2.x), and Click (7.x to 8.x). These changes often come with their own breaking changes. [14]
  Fix: Review migration guides for each updated dependency (Flask, Jinja2, Werkzeug, etc.) and adapt application code accordingly. Ensure all dependencies are updated and compatible with Flask-AppBuilder v4.0.0+. [14]
• gotcha Database migrations with Alembic (managed by Flask-Migrate via `flask fab`) require careful handling, especially on initial setup or when schema changes are introduced. Simply running `flask db migrate` might not detect changes if the setup isn't exact. [23]
  Fix: Always back up your database before migrations. For the very first migration, if you encounter `No changes in schema detected`, you might need to drop all `ab_` tables and the `alembic_version` table, then run `flask db upgrade` to create all tables and initialize Alembic correctly. Use `flask fab upgrade-db` after a Flask-AppBuilder upgrade. [2, 23]
• gotcha The `SECRET_KEY` configuration is crucial for Flask's session security. Using a weak or default key in production makes the application vulnerable to session hijacking and other attacks. [12, 21]
  Fix: Always set `app.config['SECRET_KEY']` to a long, random, and secret string. It's best practice to load this from an environment variable (e.g., `os.environ.get('FLASK_SECRET_KEY')`) rather than hardcoding it. [12, 21]
• gotcha The configuration structure for OAuth providers changed significantly in version 4.0.0, specifically impacting the keys used for client credentials (e.g., `consumer_key` and `consumer_secret` were replaced by `client_id` and `client_secret`). [14]
  Fix: Update `OAUTH_PROVIDERS` configuration in `config.py` to use the new `client_id` and `client_secret` keys within the `remote_app` dictionary. Also ensure `authlib` is correctly installed and used. [14]

Install

• pip install Flask-AppBuilder Install latest version

Imports

• AppBuilder

  from flask_appbuilder import AppBuilder

• SQLA

  from flask_appbuilder import SQLA

  While older versions or specific examples might show a submodule import, the recommended minimal quickstart for current versions directly imports `SQLA` from `flask_appbuilder` for its SQLAlchemy database object. [2, 13]
• ModelView

  from flask_appbuilder import ModelView

• SQLAInterface

  from flask_appbuilder.models.sqla.interface import SQLAInterface

Quickstart

This quickstart sets up a minimal Flask-AppBuilder application with a simple SQLAlchemy model and a corresponding ModelView for CRUD operations. It initializes Flask, Flask-SQLAlchemy, and Flask-AppBuilder, then registers a basic view. You'll need to set a `FLASK_SECRET_KEY` environment variable or replace the placeholder. After running, use `flask fab create-admin` to set up an administrative user. [2, 8, 10, 12, 21]

import os
from flask import Flask
from flask_appbuilder import SQLA, AppBuilder, ModelView
from flask_appbuilder.models.sqla.interface import SQLAInterface

# Your App class
class MyUser(SQLA.Model):
    id = SQLA.Column(SQLA.Integer, primary_key=True)
    name = SQLA.Column(SQLA.String(50), unique=True, nullable=False)

    def __repr__(self):
        return self.name

# Instantiate Flask app
app = Flask(__name__)
app.config['SECRET_KEY'] = os.environ.get('FLASK_SECRET_KEY', 'a-very-secret-key-that-you-should-change')
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///' + os.path.join(os.path.dirname(__file__), 'app.db')
app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False

# Instantiate SQLAlchemy and AppBuilder
db = SQLA(app)
appbuilder = AppBuilder(app, db.session)

# Create a ModelView for MyUser
class MyUserView(ModelView):
    datamodel = SQLAInterface(MyUser)
    list_columns = ['name']

# Add the view to AppBuilder
appbuilder.add_view(MyUserView, 'List My Users', icon='fa-users', category='My App')

# To run the app:
# $ export FLASK_APP=your_app_file_name.py
# $ flask fab create-admin (follow prompts to create an admin user)
# $ flask run
# Access at http://127.0.0.1:5000