terraform-google-sql for PostgreSQL

Note: CloudSQL provides disk autoresize feature which can cause a Terraform configuration drift due to the value in disk_size variable, and hence any updates to this variable is ignored in the Terraform lifecycle.

Usage

Functional examples are included in the examples directory. If you want to create an instance with failover replica and manage lifecycle of primary and secondary instance lifecycle using this module follow example in postgresql-with-cross-region-failover

Basic usage of this module is as follows:

Create simple Postgresql instance with read replica

module "pg" {
  source  = "terraform-google-modules/sql-db/google//modules/postgresql"
  version = "~> 26.2"

  name                 = var.pg_ha_name
  random_instance_name = true
  project_id           = var.project_id
  database_version     = "POSTGRES_9_6"
  region               = "us-central1"

  // Master configurations
  tier                            = "db-custom-1-3840"
  zone                            = "us-central1-c"
  availability_type               = "REGIONAL"
  maintenance_window_day          = 7
  maintenance_window_hour         = 12
  maintenance_window_update_track = "stable"

  deletion_protection = false

  database_flags = [{ name = "autovacuum", value = "off" }]

  user_labels = {
    foo = "bar"
  }

  ip_configuration = {
    ipv4_enabled       = true
    ssl_mode           = "ENCRYPTED_ONLY" // can also be ALLOW_UNENCRYPTED_AND_ENCRYPTED
    private_network    = null
    allocated_ip_range = null
    authorized_networks = [
      {
        name  = "${var.project_id}-cidr"
        value = var.pg_ha_external_ip_range
      },
    ]
  }

  backup_configuration = {
    enabled                        = true
    start_time                     = "20:55"
    location                       = null
    point_in_time_recovery_enabled = false
    transaction_log_retention_days = null
    retained_backups               = 365
    retention_unit                 = "COUNT"
  }

  // Read replica configurations
  read_replica_name_suffix = "-test-ha"
  read_replicas = [
    {
      name                  = "0"
      zone                  = "us-central1-a"
      availability_type     = "REGIONAL"
      tier                  = "db-custom-1-3840"
      ip_configuration      = local.read_replica_ip_configuration
      database_flags        = [{ name = "autovacuum", value = "off" }]
      disk_autoresize       = null
      disk_autoresize_limit = null
      disk_size             = null
      disk_type             = "PD_HDD"
      user_labels           = { bar = "baz" }
      encryption_key_name   = null
    },
  ]

  db_name      = var.pg_ha_name
  db_charset   = "UTF8"
  db_collation = "en_US.UTF8"

  additional_databases = [
    {
      name      = "${var.pg_ha_name}-additional"
      charset   = "UTF8"
      collation = "en_US.UTF8"
    },
  ]

  user_name     = "tftest"
  user_password = "foobar"

  additional_users = [
    {
      name            = "tftest2"
      password        = "abcdefg"
      host            = "localhost"
      random_password = false
    },
    {
      name            = "tftest3"
      password        = "abcdefg"
      host            = "localhost"
      random_password = false
    },
  ]
}

Inputs

Name	Description	Type	Default	Required
activation_policy	The activation policy for the Cloud SQL instance.Can be either `ALWAYS`, `NEVER` or `ON_DEMAND`.	`string`	`"ALWAYS"`	no
additional_databases	A list of databases to be created in your cluster	list(object({ name = string charset = string collation = string }))	`[]`	no
additional_users	A list of users to be created in your cluster. A random password would be set for the user if the `random_password` variable is set.	list(object({ name = string password = string random_password = bool }))	`[]`	no
availability_type	The availability type for the Cloud SQL instance.This is only used to set up high availability for the PostgreSQL instance. Can be either `ZONAL` or `REGIONAL`.	`string`	`"ZONAL"`	no
backup_configuration	The backup_configuration settings subblock for the database settings	object({ enabled = optional(bool, false) start_time = optional(string) location = optional(string) point_in_time_recovery_enabled = optional(bool, false) transaction_log_retention_days = optional(string) retained_backups = optional(number) retention_unit = optional(string) })	`{}`	no
connector_enforcement	Enforce that clients use the connector library	`bool`	`false`	no
create_kms_key_handle	KeyHandles cannot be deleted from Google Cloud Platform. Destroying a Terraform-managed KeyHandle will remove it from state but will not delete the resource from the project. Set this to false if key handle already exists	`bool`	`true`	no
create_timeout	The optional timout that is applied to limit long database creates.	`string`	`"30m"`	no
data_cache_enabled	Whether data cache is enabled for the instance. Defaults to false. Feature is only available for ENTERPRISE_PLUS tier and supported database_versions	`bool`	`false`	no
database_deletion_policy	The deletion policy for the database. Setting ABANDON allows the resource to be abandoned rather than deleted. This is useful for Postgres, where databases cannot be deleted from the API if there are users other than cloudsqlsuperuser with access. Possible values are: "ABANDON".	`string`	`null`	no
database_flags	The database flags for the Cloud SQL instance. See more details	list(object({ name = string value = string }))	`[]`	no
database_integration_roles	The roles required by default database instance service account for integration with GCP services	`list(string)`	`[]`	no
database_version	The database version to use. Can be 9_6, 14, 15, 16, 17.	`string`	n/a	yes
db_charset	The charset for the default database	`string`	`""`	no
db_collation	The collation for the default database. Example: 'en_US.UTF8'	`string`	`""`	no
db_name	The name of the default database to create. This should be unique per Cloud SQL instance.	`string`	`"default"`	no
delete_timeout	The optional timout that is applied to limit long database deletes.	`string`	`"30m"`	no
deletion_protection	Used to block Terraform from deleting a SQL Instance.	`bool`	`true`	no
deletion_protection_enabled	Enables protection of an Cloud SQL instance from accidental deletion across all surfaces (API, gcloud, Cloud Console and Terraform).	`bool`	`false`	no
deny_maintenance_period	The Deny Maintenance Period fields to prevent automatic maintenance from occurring during a 90-day time period. List accepts only one value. See more details	list(object({ end_date = string start_date = string time = string }))	`[]`	no
disk_autoresize	Configuration to increase storage size.	`bool`	`true`	no
disk_autoresize_limit	The maximum size to which storage can be auto increased.	`number`	`0`	no
disk_size	The disk size (in GB) for the Cloud SQL instance.	`number`	`10`	no
disk_type	The disk type for the Cloud SQL instance.	`string`	`"PD_SSD"`	no
edition	The edition of the Cloud SQL instance, can be ENTERPRISE or ENTERPRISE_PLUS.	`string`	`null`	no
enable_dataplex_integration	Enable database Dataplex integration	`bool`	`false`	no
enable_default_db	Enable or disable the creation of the default database	`bool`	`true`	no
enable_default_user	Enable or disable the creation of the default user	`bool`	`true`	no
enable_google_ml_integration	Enable database ML integration	`bool`	`false`	no
enable_random_password_special	Enable special characters in generated random passwords.	`bool`	`false`	no
encryption_key_name	The full path to the encryption key used for the CMEK disk encryption	`string`	`null`	no
failover_dr_replica_name	If the instance is a primary instance, then this field identifies the disaster recovery (DR) replica. The standard format of this field is "your-project:your-instance". You can also set this field to "your-instance", but cloud SQL backend will convert it to the aforementioned standard format.	`string`	`null`	no
follow_gae_application	A Google App Engine application whose zone to remain in. Must be in the same region as this instance.	`string`	`null`	no
iam_users	A list of IAM users to be created in your CloudSQL instance. iam.users.type can be CLOUD_IAM_USER, CLOUD_IAM_SERVICE_ACCOUNT, CLOUD_IAM_GROUP and is required for type CLOUD_IAM_GROUP (IAM groups)	list(object({ id = string, email = string, type = optional(string) }))	`[]`	no
insights_config	The insights_config settings for the database.	object({ query_plans_per_minute = optional(number, 5) query_string_length = optional(number, 1024) record_application_tags = optional(bool, false) record_client_address = optional(bool, false) })	`null`	no
instance_type	The type of the instance. The supported values are SQL_INSTANCE_TYPE_UNSPECIFIED, CLOUD_SQL_INSTANCE, ON_PREMISES_INSTANCE and READ_REPLICA_INSTANCE. Set to READ_REPLICA_INSTANCE if master_instance_name value is provided	`string`	`"CLOUD_SQL_INSTANCE"`	no
ip_configuration	The ip configuration for the Cloud SQL instances.	object({ authorized_networks = optional(list(map(string)), []) ipv4_enabled = optional(bool, true) private_network = optional(string) ssl_mode = optional(string) allocated_ip_range = optional(string) enable_private_path_for_google_cloud_services = optional(bool, false) psc_enabled = optional(bool, false) psc_allowed_consumer_projects = optional(list(string), []) server_ca_mode = optional(string) server_ca_pool = optional(string) custom_subject_alternative_names = optional(list(string), []) })	`{}`	no
kms_key_handle_name	key handle name. If not provided module will use instance name as key handle name	`string`	`null`	no
maintenance_version	The current software version on the instance. This attribute can not be set during creation. Refer to available_maintenance_versions attribute to see what maintenance_version are available for upgrade. When this attribute gets updated, it will cause an instance restart. Setting a maintenance_version value that is older than the current one on the instance will be ignored	`string`	`null`	no
maintenance_window_day	The day of week (1-7) for the Cloud SQL instance maintenance.	`number`	`1`	no
maintenance_window_hour	The hour of day (0-23) maintenance window for the Cloud SQL instance maintenance.	`number`	`23`	no
maintenance_window_update_track	The update track of maintenance window for the Cloud SQL instance maintenance.Can be either `canary` or `stable`.	`string`	`"canary"`	no
master_instance_name	Name of the master instance if this is a failover replica. Required for creating failover replica instance. Not needed for master instance. When removed, next terraform apply will promote this failover failover replica instance as master instance	`string`	`null`	no
module_depends_on	List of modules or resources this module depends on.	`list(any)`	`[]`	no
name	The name of the Cloud SQL instance	`string`	n/a	yes
password_validation_policy_config	The password validation policy settings for the database instance.	object({ min_length = optional(number) complexity = optional(string) reuse_interval = optional(number) disallow_username_substring = optional(bool) password_change_interval = optional(string) })	`null`	no
pricing_plan	The pricing plan for the Cloud SQL instance.	`string`	`"PER_USE"`	no
project_id	The project ID to manage the Cloud SQL resources	`string`	n/a	yes
random_instance_name	Sets random suffix at the end of the Cloud SQL resource name	`bool`	`false`	no
read_replica_deletion_protection	Used to block Terraform from deleting replica SQL Instances.	`bool`	`false`	no
read_replica_deletion_protection_enabled	Enables protection of replica instance from accidental deletion across all surfaces (API, gcloud, Cloud Console and Terraform).	`bool`	`false`	no
read_replica_name_suffix	The optional suffix to add to the read instance name	`string`	`""`	no
read_replicas	List of read replicas to create. Encryption key is required for replica in different region. For replica in same region as master set encryption_key_name = null	list(object({ name = string name_override = optional(string) tier = optional(string) edition = optional(string) availability_type = optional(string) zone = optional(string) disk_type = optional(string) disk_autoresize = optional(bool) disk_autoresize_limit = optional(number) disk_size = optional(string) user_labels = map(string) database_flags = optional(list(object({ name = string value = string })), []) insights_config = optional(object({ query_plans_per_minute = optional(number, 5) query_string_length = optional(number, 1024) record_application_tags = optional(bool, false) record_client_address = optional(bool, false) }), null) ip_configuration = object({ authorized_networks = optional(list(map(string)), []) ipv4_enabled = optional(bool) private_network = optional(string) ssl_mode = optional(string) allocated_ip_range = optional(string) enable_private_path_for_google_cloud_services = optional(bool, false) psc_enabled = optional(bool, false) psc_allowed_consumer_projects = optional(list(string), []) }) encryption_key_name = optional(string) data_cache_enabled = optional(bool) }))	`[]`	no
region	The region of the Cloud SQL resources	`string`	`"us-central1"`	no
retain_backups_on_delete	When this parameter is set to true, Cloud SQL retains backups of the instance even after the instance is deleted. The ON_DEMAND backup will be retained until customer deletes the backup or the project. The AUTOMATED backup will be retained based on the backups retention setting.	`bool`	`false`	no
root_password	Initial root password during creation	`string`	`null`	no
secondary_zone	The preferred zone for the replica instance, it should be something like: `us-central1-a`, `us-east1-c`.	`string`	`null`	no
tier	The tier for the Cloud SQL instance, for ADC its default value will be db-perf-optimized-N-8 which is tier value for edition ENTERPRISE_PLUS, if user wants to change the edition, he should chose compatible tier.	`string`	`"db-f1-micro"`	no
update_timeout	The optional timout that is applied to limit long database updates.	`string`	`"30m"`	no
use_autokey	Enable the use of autokeys from Google Cloud KMS for CMEK. This requires autokey already configured in the project	`bool`	`false`	no
user_deletion_policy	The deletion policy for the user. Setting ABANDON allows the resource to be abandoned rather than deleted. This is useful for Postgres, where users cannot be deleted from the API if they have been granted SQL roles. Possible values are: "ABANDON".	`string`	`null`	no
user_labels	The key/value labels for the Cloud SQL instances.	`map(string)`	`{}`	no
user_name	The name of the default user	`string`	`"default"`	no
user_password	The password for the default user. If not set, a random one will be generated and available in the generated_user_password output variable.	`string`	`""`	no
zone	The zone for the Cloud SQL instance, it should be something like: `us-central1-a`, `us-east1-c`.	`string`	`null`	no

Outputs

Name	Description
additional_user_passwords_map	Map of auto generated passwords for the additional users
additional_users	List of maps of additional users and passwords
apphub_service_uri	Service URI in CAIS style to be used by Apphub.
dns_name	DNS name of the instance endpoint
env_vars	Exported environment variables
generated_user_password	The auto generated default user password if not input password was provided
iam_users	The list of the IAM users with access to the CloudSQL instance
instance_connection_name	The connection name of the master instance to be used in connection strings
instance_first_ip_address	The first IPv4 address of the addresses assigned.
instance_ip_address	The IPv4 address assigned for the master instance
instance_name	The instance name for the master instance
instance_psc_attachment	The psc_service_attachment_link created for the master instance
instance_self_link	The URI of the master instance
instance_server_ca_cert	The CA certificate information used to connect to the SQL instance via SSL
instance_service_account_email_address	The service account email address assigned to the master instance
instances	A list of all `google_sql_database_instance` resources we've created
primary	The `google_sql_database_instance` resource representing the primary instance
private_ip_address	The first private (PRIVATE) IPv4 address assigned for the master instance
public_ip_address	The first public (PRIMARY) IPv4 address assigned for the master instance
read_replica_instance_names	The instance names for the read replica instances
replicas	A list of `google_sql_database_instance` resources representing the replicas
replicas_instance_connection_names	The connection names of the replica instances to be used in connection strings
replicas_instance_first_ip_addresses	The first IPv4 addresses of the addresses assigned for the replica instances
replicas_instance_psc_attachments	The psc_service_attachment_links created for the replica instances
replicas_instance_self_links	The URIs of the replica instances
replicas_instance_server_ca_certs	The CA certificates information used to connect to the replica instances via SSL
replicas_instance_service_account_email_addresses	The service account email addresses assigned to the replica instances

Requirements

Installation Dependencies

Terraform >= 1.3.0
terraform-provider-google plugin v5.25+
Terraform Provider Beta for GCP plugin v5.25+