gitlab-org--gitlab-foss/doc/development/database/swapping_tables.md

stage	group	info
Data Stores	Database	To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments

Swapping Tables

Sometimes you need to replace one table with another. For example, when migrating data in a very large table it's often better to create a copy of the table and insert & migrate the data into this new table in the background.

Let's say you want to swap the table events with events_for_migration. In this case you need to follow 3 steps:

1. Rename events to events_temporary
2. Rename events_for_migration to events
3. Rename events_temporary to events_for_migration

Rails allows you to do this using the rename_table method:

rename_table :events, :events_temporary
rename_table :events_for_migration, :events
rename_table :events_temporary, :events_for_migration

This does not require any downtime as long as the 3 rename_table calls are executed in the same database transaction. Rails by default uses database transactions for migrations, but if it doesn't you need to start one manually:

Event.transaction do
  rename_table :events, :events_temporary
  rename_table :events_for_migration, :events
  rename_table :events_temporary, :events_for_migration
end

Once swapped you have to reset the primary key of the new table. For PostgreSQL you can use the reset_pk_sequence! method like so:

reset_pk_sequence!('events')

Failure to reset the primary keys results in newly created rows starting with an ID value of 1. Depending on the existing data this can then lead to duplicate key constraints from popping up, preventing users from creating new data.