Renaming table in BigQuery using terraform

[skj]

Hi everyone,

I am working on a project where we utilize Terraform to manage all BigQuery infrastructure, including datasets, tables, and other resources. I have a scenario where I need to rename a BigQuery table. I understand that this is possible using a DDL command as documented here:
Renaming Table 

However, since Terraform does not natively support renaming tables, I am looking for guidance on:

• How to handle this within Terraform
• What are the best practices for managing such changes without breaking the Terraform state
• Whether it's better to clone/create a new table and deprecate the old one
• How to manage the terraform state or import correctly in such cases

I would appreciate any advice or recommended patterns from those who have faced similar situations.

Thanks!

[dawnberdan]

Hi @skj,

Welcome to Google Cloud Community!

Terraform currently manages BigQuery tables by their unique identifiers, which include the project_id, dataset_id, and table_id. While it doesn’t support directly renaming BigQuery tables, changing the table_id in your google_bigquery_table resource prompts Terraform to recreate the table. This behavior helps ensure resource consistency and clarity, so it’s important to handle such changes carefully to protect your data.

Here's how to approach this, including best practices and considerations:

1. Manually Rename or Clone the Table: Use BigQuery DDL or Clone it.
2. Update Terraform State Since Terraform still thinks the table is named old_table, you’ll need to manually update the state, This tells Terraform that the resource now corresponds to the renamed table.
3. Update Your Terraform Code Change the table_id in your .tf file to match the new table name.
4. Run a Plan to Confirm Run terraform plan to ensure no changes are pending. If everything looks good, you’re set.

For the best practices:

• Avoid renaming tables frequently in Terraform-managed infra unless absolutely necessary.
• Use deletion_protection = true to prevent accidental data loss during schema or name changes.
• Document manual steps in your repo (e.g., in a README.md or MIGRATION.md) so future maintainers understand the context.
• Use terraform import if the table was renamed outside of Terraform and you want to bring it under management again.

Here are some helpful references:

• Stack Overflow: How to manage schema changes to a BigQuery table via Terraform: This thread covers Terraform’s limits with BigQuery schema changes and suggests using bq commands and manual Terraform state management.
• Manage Tables: This official guide shows how to rename tables with DDL and covers limitations and best practices.
• Github Terraform: You may check this Feature request to add BigQuery column renaming in Terraform, noting current limits and community demand.

Was this helpful? If so, please accept this answer as “Solution”. If you need additional assistance, reply here within 2 business days and I’ll be happy to help