Resolving Schema Config Reversions in Specify 7.12.0 (Self-Hosted Users)

Announcements & News
,
1

Hi Specificians, :specify7:

As mentioned in our recent announcement, the Specify 7.12.0 update included changes that may have inadvertently modified the schema config records within your database. During startup, some schema records may have reverted to the default configuration, affecting your custom captions, descriptions, and assigned pick lists, web links, or formats.

This issue has been completely resolved in the Specify 7.12.0.5 update. However, if your self-hosted instance was updated to any version between 7.12.0 and 7.12.0.4, you will need to manually restore the affected tables from a pre-update backup.

[!warning] Important Note: Have you added a new discipline?
If you have added a new discipline to your database since updating to 7.12.0, please do not follow the instructions below as you will be left without necessary schema records. Reach out to our support team at support@specifysoftware.org, and we will remediate the issue for you directly to prevent any schema misconfiguration!

For all other self-hosted users, please follow the steps below to securely restore your schema configuration.

Remediation Steps

  1. Locate a pre-update backup

    Find the most recent database backup taken before your update to the 7.12.0 - 7.12.0.4 range. You will need to restore this backup to a temporary database (or have it accessible on your database server) so we can extract the specific schema tables.

  2. Extract the schema configuration tables
    We need to extract the data from the three tables responsible for schema configurations: splocalecontainer, splocalecontaineritem, and splocaleitemstr. You can do this by running a mysqldump command against your pre-update backup database.

    mysqldump -u [username] -p [pre_update_database_name] splocalecontainer splocalecontaineritem splocaleitemstr > schema_tables_backup.sql

  3. Backup your current database
    Before making any changes to your live database, it is critical to create a full backup of your current 7.12.0 - 7.12.0.4 database. This ensures you have a recovery point if anything goes wrong.

    mysqldump -u [username] -p [current_database_name] > full_current_backup.sql

  4. Restore the schema tables to the current database
    Now, apply the SQL dump containing the three splocale* tables to your current, live database. This will overwrite the reverted schema configuration with your previous, correct settings.

    mysql -u [username] -p [current_database_name] < schema_tables_backup.sql

  5. Restart Specify 7 and check logs
    To ensure everything initializes smoothly, restart your Specify 7 Docker container. This will run a function to recreate the new schema config tables and values for the new fields present in the 7.12 release, which were not included in the previous splocale* tables.

    It is highly recommended to watch the logs during startup to confirm the application starts without any schema-related errors.

    docker-compose restart specify7
docker-compose logs -f specify7

  6. Verify the Schema Config
    Log into your Specify 7 instance as an administrator. Navigate to the Schema Config tool in the User Tools menu and verify that your custom captions, descriptions, pick lists, and formats are appearing exactly as expected.

[!success] Solved.
If your logs are clear and your schema configuration looks correct in the UI, your schema configuration is fully restored!

If you run into any issues or have questions about running these commands, please feel free to reply to this thread or reach out to the help desk. We are here to help.

Best,
The Specify Collections Consortium Team

Important Update: Schema Configuration Reversions in Specify 7.12.0