One line stops a migration from taking down production. Almost nobody adds it.

ALTER TABLE statements that add a column to a table without specifying a lock timeout can cause database migrations to stop, even if the migration itself is harmless. This happens because the ALTER TABLE statement requests a lock called ACCESS EXCLUSIVE, which conflicts with all other locks including the read-only ACCESS SHARE lock used by simple SELECT queries. If another transaction already holds any lock on the table, the ALTER TABLE statement must wait, as it cannot proceed until that lock is freed.

PostgreSQL grants locks in order, so once the ALTER TABLE statement is queued, every subsequent request that conflicts with ACCESS EXCLUSIVE will be queued behind it, regardless of whether it is a read or write operation. This means that even a seemingly harmless migration that adds a nullable column to a table can lock the entire table for a significant amount of time, potentially causing downtime for the entire application.

A simple way to prevent this issue is to add a line setting the lock_timeout parameter to a value such as 2 seconds when running the ALTER TABLE statement. This tells PostgreSQL to give up the lock after the specified time if it cannot be obtained. By using this guard, the migration can be retried until it successfully acquires the lock, ensuring that the table change is completed without locking the entire database. This small addition can prevent unexpected outages and ensure smooth migration processes.