How to rename a table in PostgreSQL

Why would you rename a table?

Teams rename tables to match new business terms, phase out legacy names, or merge schemas. Doing so keeps data, indexes, constraints, and privileges intact, avoiding the cost of creating a new table and re-migrating data.

What is the exact syntax to rename a table?

Use ALTER TABLE [IF EXISTS] current_name RENAME TO new_name;. Add IF EXISTS to suppress errors if the table is missing. Only the owning role or a superuser can run this command.

How do I rename the “Orders” table to “CustomerOrders”?

ALTER TABLE Orders RENAME TO CustomerOrders;

The command runs instantly because PostgreSQL updates only the system catalog.

Can I rename multiple tables in one transaction?

Yes. Wrap several ALTER TABLE ... RENAME statements in a BEGIN; … COMMIT; block to keep the schema consistent if any step fails.

Does renaming affect foreign keys or views?

PostgreSQL automatically updates foreign keys, sequences, and constraint names that reference the old table. Views and functions using the old name are not updated; refresh them manually.

Best practices for safe renames?

• Rename during low-traffic windows.
• Use short, descriptive names (customer_orders vs custord).
• Search your codebase for hard-coded table names and update them.
• Keep a migration file so teammates can replay the change.

Common mistakes and how to avoid them

Using RENAME on a busy table without a lock plan

Although instant, the command still takes an ACCESS EXCLUSIVE lock. Schedule it during maintenance windows.

Forgetting to update dependent views

Views break after the rename. Recreate or refresh them immediately.

Quick checklist before running the command

1) Confirm no conflicting migrations. 2) Search and replace old table name in code, tests, and dashboards. 3) Add the change to version control. 4) Run in a transaction when possible.