Overview
In Brainspace 7.4, the Postgres image used by the brains-db service has been updated from the Bitnami Postgres image (Postgres 16.6) to the Chainguard Postgres image (Postgres 16.12, at the date of release).
Upgrading to 7.4 includes changes to how Postgres is initialized and where configuration files are stored. To ensure a smooth upgrade and avoid database or sorting issues, follow the steps below.
1. Back up the Brainspace postgres database (Strongly recommended)
Before upgrading to 7.4, we strongly recommend taking a backup of the Brainspace database from the existing Bitnami Postgres container. This is a precaution in case any unexpected database issues are encountered during the image transition.
From inside the brains-db container, run:
pg_dump --file brainspace-db.sql -U brainspace brainspace
Note
In large environments, this command can take some time to complete.
Then copy the backup file out of the container to the Docker host (the container will be destroyed during the upgrade):
docker cp <brains-db container ID>:<path to SQL dump file> ./
Store this backup in a safe location according to your organization’s backup practices.
2. Reapply any custom postgresql.conf settings after upgrade
If you previously customized postgresql.conf in the Bitnami Postgres container (for example, changing max_locks_per_transaction or other tuning parameters), you must manually reapply those changes after the upgrade to the Chainguard Postgres image.
In 7.4, postgresql.conf resides in a different location inside the container:
/var/lib/postgresql/data/postgresql.conf
The recommended approach:
After the upgrade completes, on the Docker host where
brains-dbruns, edit the configuration file stored in the Postgres data volume:/var/lib/docker/volumes/brainspace_vol-pgsql/_data/data/postgresql.confReapply any custom settings you previously had in the Bitnami
postgresql.conf(for example,max_locks_per_transaction).Restart the
brains-dbservice to apply the changes:docker service update --force brainspace_brains-db
3. Addressing collation version mismatch warnings (Optional but recommended)
After upgrading to the Chainguard Postgres image, you may see log entries similar to:
WARNING: Database “brainspace” has a collation version mismatch.
DETAIL: The database was created using collation version 2.36, but the operating system provides version 2.43.
HINT: Rebuild all objects in this database that use the default collation and run
ALTER DATABASE brainspace REFRESH COLLATION VERSIONorbuild PostgreSQLwith the right library version.
These warnings indicate that the operating system’s collation library version has changed between the original Bitnami environment and the new Chainguard environment. In practice, this can potentially affect how some indexed text is sorted.
To eliminate the warnings and avoid any subtle sorting inconsistencies in Brainspace:
Open a
psqlsession inside thebrains-dbcontainer. Run:
REINDEX DATABASE brainspace; ALTER DATABASE brainspace REFRESH COLLATION VERSION;
Note
The REINDEX operation can take more than a few seconds in environments with a large amount of data, because it must rebuild all relevant indexes in the Brainspace database.
Brainspace relies primarily on Lucene for most UI sorting (e.g., sorting by CMML score), so any sorting issues related to this collation mismatch are expected to be limited. However, running the commands above ensures consistency and removes the warnings from the logs.