Bitbucket Data Center shared home and database synchronization limits

What goes wrong when the shared home isn’t in sync with the database snapshot?

When the shared‑home directory contains files that were generated by a newer Bitbucket release while the database has been rolled back to an older schema, the following behaviors can occur:

• Plugin failures – Plugins installed after the upgrade may reference tables or columns that no longer exist in the rolled‑back schema, causing 500‑errors or “missing table” exceptions.
• Configuration drift – System‑wide settings (e.g., repo permissions, feature flags) stored in the shared‑home may reference database objects that are absent, leading to inconsistent or broken functionality.
• Data corruption risk – Writes that rely on schema changes (new columns, indexes) may silently drop data or produce malformed rows if the database rejects them.
• Startup hang or abort – The Bitbucket process may wait for a database transaction that can never succeed, or it may terminate with a clear error message about a version mismatch.

Is there a built‑in mismatch detector?

Bitbucket Data Center includes a lightweight version check that runs during the bootstrap phase:

• The shared_home/bitbucket_version file (created during each upgrade) contains the release number that produced the shared‑home contents.
• The database holds a schema_version table (in PostgreSQL or MySQL) that records the current schema revision.
• On startup, the JVM reads both values and compares them. If they differ, Bitbucket logs a fatal error and refuses to start.

Because the check is performed before the web tier is initialized, it prevents the application from running in an inconsistent state.

How to verify the version alignment in your cluster

1. Check the shared‑home file. On any node, run:

   cat /shared/home/bitbucket_version
   

2. Query the database. Connect to the primary database and run:

   SELECT version FROM schema_version;
   

3. Compare the two outputs. They should be identical (e.g., 7.18.0).
4. If they differ, restore the shared‑home from the same snapshot that the database was rolled back to, or roll the database forward to the newer schema.
5. After alignment, restart the Bitbucket nodes and verify that the startup.log shows a successful version match.

Missing diagnostic detail

To tailor the guidance further, could you confirm whether your cluster uses PostgreSQL or MySQL? The exact table name (schema_version vs schema_version_info) and the SQL dialect can affect the query syntax.