Skip to content

Commit 76244bd

Browse files
Dev25Dev25
authored
chore: Add v4 upgrade doc (#121)
1 parent 86c533a commit 76244bd

File tree

4 files changed

+597
-2
lines changed

4 files changed

+597
-2
lines changed

‎docs/upgrading_to_sql_db_4.0.0.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# Upgrading to SQL DB 4.0.0
2+
3+
The v4.0.0 release of SQL DB is a backward incompatible release. The MySQL/PostgreSQL read replica state has been migrated to using `for_each` and the replica configuration is now a list of individual replica configuration rather then all replicas sharing the same settings.
4+
5+
In addition the deprecated `failover_*` variables used to manage the legacy MySQL failover instance for HA have been completely removed in favour of the new HA solution that was introduced in v3.2.0
6+
7+
## Migration Instructions
8+
#### MySQL Failover Instance
9+
10+
This migration causes downtime, please read the CloudSQL docs first: [Updating an instance from legacy to current high availability](https://cloud.google.com/sql/docs/mysql/configure-ha#update-from-legacy)
11+
12+
1. Delete the failover instance via this module
13+
2. Set `availability_type = "REGIONAL"` - This will cause downtime as the master instance is restarted
14+
15+
16+
#### Additional Users and Databases
17+
`additional_databases` and `additional_users` has moved to using `for_each` which requires a state migration. In addition `project` and `instance` object fields have been removed since they are inferred automatically.
18+
19+
```diff
20+
additional_databases = [
21+
{
22+
- project = var.project_id
23+
- instance = null
24+
name = "db1"
25+
charset = "utf8mb4"
26+
collation = "utf8mb4_general_ci"
27+
28+
additional_users = [
29+
{
30+
- project = var.project_id
31+
- instance = null
32+
name = "user1"
33+
password = "abcdefg"
34+
host = "localhost"
35+
}
36+
]
37+
38+
```
39+
40+
#### Read Replicas
41+
The new `read_replicas` variable is used to manage all replica configuration. In order to migrate existing replicas you will need to perform a state migration.
42+
43+
- You must have `read_replica_size` objects inside `read_replicas`
44+
- You must use the full `zone` id which includes the region e.g. `europe-west1-c` instead of `c`
45+
46+
```diff
47+
module "test" {
48+
source = "GoogleCloudPlatform/sql-db/google//modules/mysql"
49+
- version = "~> 3.2"
50+
+ version = "~> 4.0"
51+
52+
// Read replica configurations
53+
- read_replica_name_suffix = "-test"
54+
- read_replica_size = 1
55+
- read_replica_tier = "db-n1-standard-1"
56+
- read_replica_zones = "c"
57+
- read_replica_activation_policy = "ALWAYS"
58+
- read_replica_crash_safe_replication = true
59+
- read_replica_disk_size = 15
60+
- read_replica_disk_autoresize = true
61+
- read_replica_disk_type = "PD_HDD"
62+
- read_replica_replication_type = "SYNCHRONOUS"
63+
- read_replica_maintenance_window_day = 1
64+
- read_replica_maintenance_window_hour = 22
65+
- read_replica_maintenance_window_update_track = "stable"
66+
-
67+
- read_replica_user_labels = {
68+
- bar = "baz"
69+
- }
70+
-
71+
- read_replica_database_flags = [
72+
+ read_replica_name_suffix = "-test"
73+
+ read_replicas = [
74+
{
75+
- name = "long_query_time"
76+
- value = "1"
77+
+ name = "0"
78+
+ tier = "db-n1-standard-1"
79+
+ zone = "europe-west1-c"
80+
+ ip_configuration = {
81+
+ ipv4_enabled = true
82+
+ require_ssl = true
83+
+ private_network = var.host_vpc_link
84+
+ authorized_networks = []
85+
+ }
86+
+ database_flags = [{ name = "long_query_time", value = "1" }]
87+
+ disk_autoresize = true
88+
+ disk_size = 15
89+
+ disk_type = "PD_HDD"
90+
+ user_labels = { bar = "baz" }
91+
+ },
92+
+ {
93+
+ name = "1"
94+
+ tier = "db-n1-standard-1"
95+
+ zone = "europe-west1-c"
96+
+ ip_configuration = {
97+
+ ipv4_enabled = true
98+
+ require_ssl = true
99+
+ private_network = var.host_vpc_link
100+
+ authorized_networks = []
101+
+ }
102+
+ database_flags = [{ name = "long_query_time", value = "1" }]
103+
+ disk_autoresize = true
104+
+ disk_size = 15
105+
+ disk_type = "PD_HDD"
106+
+ user_labels = { bar = "baz" }
107+
},
108+
]
109+
110+
- read_replica_configuration = {
111+
- dump_file_path = null
112+
- connect_retry_interval = null
113+
- ca_certificate = null
114+
- client_certificate = null
115+
- client_key = null
116+
- failover_target = false
117+
- master_heartbeat_period = null
118+
- password = null
119+
- ssl_cipher = null
120+
- username = null
121+
- verify_server_certificate = null
122+
- }
123+
-
124+
- read_replica_ip_configuration = {
125+
- ipv4_enabled = true
126+
- require_ssl = true
127+
- private_network = var.host_vpc_link
128+
- authorized_networks = []
129+
- }
130+
-
131+
}
132+
```
133+
134+
### State Migration Script
135+
136+
1. Download the script:
137+
138+
```sh
139+
curl -O https://raw.githubusercontent.com/terraform-google-modules/terraform-google-sql-db/master/helpers/migrate4.py
140+
chmod +x migrate4.py
141+
```
142+
143+
2. Back up your Terraform state:
144+
145+
```sh
146+
terraform state pull >> state.bak
147+
```
148+
149+
2. Run the script to output the migration commands:
150+
151+
```sh
152+
$ ./migrate4.py --dryrun
153+
---- Migrating the following modules:
154+
-- module.test
155+
---- Commands to run:
156+
terraform state mv 'module.test.google_sql_database_instance.replicas[0]' 'module.test.google_sql_database_instance.replicas["test-migration-replica-test0"]'
157+
terraform state mv 'module.test.google_sql_user.additional_users[0]' 'module.test.google_sql_user.additional_users["user1"]'
158+
terraform state mv 'module.test.google_sql_database.additional_databases[0]' 'module.test.google_sql_database.additional_databases["db1"]'
159+
160+
```
161+
162+
3. Execute the migration script:
163+
164+
```sh
165+
$ ./migrate4.py
166+
---- Migrating the following modules:
167+
-- module.test
168+
---- Commands to run:
169+
Move "module.test.google_sql_database_instance.replicas[0]" to "module.test.google_sql_database_instance.replicas[\"test-migration-replica-test0\"]"
170+
Successfully moved 1 object(s).
171+
Move "module.test.google_sql_user.additional_users[0]" to "module.test.google_sql_user.additional_users[\"user1\"]"
172+
Successfully moved 1 object(s).
173+
Move "module.test.google_sql_database.additional_databases[0]" to "module.test.google_sql_database.additional_databases[\"db1\"]"
174+
Successfully moved 1 object(s).
175+
176+
```
177+
178+
4. Run `terraform plan` to confirm no changes are expected.

0 commit comments

Comments
 (0)