Description

During GitLab version upgrades, database migrations may fail with a PG::LockNotAvailable: ERROR: canceling statement due to lock timeout error. This typically occurs when the database is handling multiple concurrent processes that prevent the migration from acquiring necessary locks on database objects.

 

Impacted offerings:

  • GitLab Self-Managed

Impacted versions:

  • GitLab Self-Managed instances

Solution

  1. Enable Maintenance Mode to prevent new processes from interfering with the migration: https://docs.gitlab.com/administration/maintenance_mode/#enable-maintenance-mode
  2. Wait for existing processes to complete gracefully - Maintenance Mode allows current database operations to finish without starting new ones.
  3. Run the database migration once the database is free from competing processes: gitlab-rake db:migrate
  4. Disable Maintenance Mode after the migration completes successfully: https://docs.gitlab.com/administration/maintenance_mode/#disable-maintenance-mode

Cause

The error occurs when: 

  • Multiple database processes are running simultaneously during migration
  • Database locks cannot be acquired due to competing operations
  • Long-running queries or background jobs are blocking the migration process
  • Missing database configuration parameters (like statements_timeout) may exacerbate the issue

Additional Information

  • Ensure all required database parameters are properly configured before starting migrations, especially statement_timeout: https://docs.gitlab.com/install/requirements/#postgresql-tuning
  • Monitor database activity during upgrades to identify potential conflicts
  • Consider scheduling upgrades during low-activity periods to minimize lock contention
  • Maintenance Mode gracefully handles existing connections while preventing new ones

Related Links

 

 

On this page...