Upgrading from FlaskBB 2.x

FlaskBB 3.0 upgrades a 2.x installation in place. flaskbb db upgrade migrates the database, including the settings, the groups and the data of the official plugins, and a config file generated by FlaskBB 2.x keeps working.

Before you start

The migrations can’t be reverted. Back up

  • the database, e.g. with pg_dump or a copy of the SQLite file, and

  • your flaskbb.cfg.

To go back to 2.x, restore both and reinstall your old FlaskBB version.

FlaskBB 3.0 needs Python 3.12 or newer, which usually means a new virtual environment. Stop FlaskBB and its Celery worker before you migrate.

Plugins written for FlaskBB 2.x only work with 3.0 if they have a release that supports it. Update them, or remove them from the environment before you start FlaskBB 3.0. The settings of a removed plugin stay in the database.

Install FlaskBB 3.0

For an installation from a Git checkout, as described in Production & Deployment, check out the new release and sync the environment with the extras you need:

$ git fetch --tags
$ git checkout v3.0.0
$ uv sync --no-dev --extra postgres

The extras are postgres for PostgreSQL, mysql for MySQL, gunicorn for gunicorn and plugins for the official plugins that aren’t installed by default. A checkout also has to compile the translations again, the files FlaskBB 2.x compiled are outdated:

$ uv run flaskbb translations compile

To install FlaskBB from PyPI instead, create a new virtual environment and install it with the same extras, e.g.:

$ pip install "FlaskBB[postgres]"

The portal and conversations plugins are always installed with FlaskBB.

Configuration

FlaskBB 3.0 still loads a config file generated by FlaskBB 2.x and translates these settings to their new form:

  • CELERY_BROKER_URL and CELERY_RESULT_BACKEND are now broker_url and result_backend in CELERY_CONFIG:

    CELERY_CONFIG = {
        "broker_url": "redis://localhost:6379",
        "result_backend": "redis://localhost:6379",
    }
    
  • CACHE_TYPE = "simple" and CACHE_TYPE = "redis" are now "SimpleCache" and "RedisCache".

  • RATELIMIT_STORAGE_URL was renamed to RATELIMIT_STORAGE_URI.

The translation is deprecated and will be removed in FlaskBB 4.0, FlaskBB warns about each of these settings until you update it. Other changes:

  • WHOOSHEE_DIR, WHOOSHEE_MIN_STRING_LEN and WHOOSHEE_WRITER_TIMEOUT are no longer used, see Search.

  • TRUSTED_HOSTS is new and defaults to SERVER_NAME.

  • AVATAR_UPLOAD_PATH and ATTACHMENT_UPLOAD_PATH are new, see Uploads.

  • The reCAPTCHA keys are managed in the admin panel again. Keys saved in a 2.0 or 2.1 admin panel are picked up by the migration, and RECAPTCHA_PUBLIC_KEY and RECAPTCHA_PRIVATE_KEY from a 2.2 config are still used as long as the admin panel fields are empty.

To start with a new config instead, run flaskbb makeconfig and copy at least SQLALCHEMY_DATABASE_URI, SECRET_KEY, WTF_CSRF_SECRET_KEY and your mail and Redis settings from the old one. New secret keys log out every user and invalidate the password reset and activation links sent before the upgrade.

postgresql:// database URIs keep working with the psycopg driver of the postgres extra. The mysql extra installs PyMySQL, which needs a mysql+pymysql:// URI.

Migrate the database

Run the migrations with your config:

$ uv run flaskbb --config flaskbb.cfg db upgrade

This migrates FlaskBB and every enabled plugin. Among other things, it

  • moves the settings and the plugin settings into the new settings table, keeps their values and adds the settings that are new in 3.0,

  • turns the permission flags of every group, including your own groups, into roles and permissions,

  • migrates the private messages of the conversations plugin and

  • creates the full text search indexes and fills them with the existing topics and posts.

The command creates the app before it migrates, so it may log that a plugin “stays disabled until its migrations are applied”. db upgrade applies them, you can ignore that warning here.

After the upgrade

Start FlaskBB and its Celery worker again (flaskbb celery worker) and log in as an administrator. On the first start, FlaskBB adds the new settings of the enabled plugins.

Plugins

Plugins that were enabled in 2.x stay enabled. Plugins that you installed with 3.0, e.g. through the plugins extra, are disabled until you enable and install them in the admin panel or with:

$ uv run flaskbb plugins list
$ uv run flaskbb plugins enable like
$ uv run flaskbb plugins install like

See Plugins for more.

Uploads

Users can upload avatars and attach files to posts now, and avatar links set in 2.x keep working. Uploads are stored in flaskbb/static/uploads unless AVATAR_UPLOAD_PATH and ATTACHMENT_UPLOAD_PATH point somewhere else. FlaskBB has to be able to write there, and the directory belongs in your backups. If you installed FlaskBB with pip, point both settings outside of the virtual environment, or the uploads are lost when FlaskBB is reinstalled.

Commands

flaskbb upgrade was removed. flaskbb db upgrade and the plugin commands keep the settings up to date now.

Moving to Docker

The container images migrate an existing database before every start, see Docker Deployment. To move a 2.x PostgreSQL database into the release stack, create its dump with pg_dump --no-owner, copy SECRET_KEY and WTF_CSRF_SECRET_KEY from your old config to SECRET_KEY and CSRF_SECRET_KEY in docker/.env, and restore the dump before FlaskBB starts:

$ docker compose -f docker/docker-compose.yaml up -d postgres
$ docker compose -f docker/docker-compose.yaml exec -T postgres sh -c \
    'psql -U "$POSTGRES_USER" "$POSTGRES_DB"' < flaskbb.sql
$ docker compose -f docker/docker-compose.yaml up -d