Merge pull request #80 from omazin/upgrading-guide-3.0

Add upgrade guide for 3.0. Update readme.

Author: aaron-lane

CHANGELOG.md

@@ -7,6 +7,8 @@ project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+## [3.0.0] - 2019-12-13
+
 ### Removed
 
 - Removed variable `peering_completed`. [#78]
@@ -47,7 +49,8 @@ project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [1.0.0] - 2019-02-14
 
-[Unreleased]: https://github.com/terraform-google-modules/terraform-google-sql-db/compare/v2.0.0...HEAD
+[Unreleased]: https://github.com/terraform-google-modules/terraform-google-sql-db/compare/v3.0.0...HEAD
+[3.0.0]: https://github.com/terraform-google-modules/terraform-google-sql-db/compare/v2.0.0...v3.0.0
 [2.0.0]: https://github.com/terraform-google-modules/terraform-google-sql-db/compare/v1.2.0...v2.0.0
 [1.2.0]: https://github.com/terraform-google-modules/terraform-google-sql-db/compare/1.1.2...v1.2.0
 [1.1.2]: https://github.com/terraform-google-modules/terraform-google-sql-db/compare/1.1.1...1.1.2

README.md

@@ -16,6 +16,13 @@ and need a Terraform 0.11.x-compatible version of this module, the last
 released version intended for Terraform 0.11.x is
 [v1.2.0](https://registry.terraform.io/modules/GoogleCloudPlatform/sql-db/google/1.2.0).
 
+## Upgrading
+
+The current version is 3.X. The following guides are available to assist with upgrades:
+
+- [1.X -> 2.0](./docs/upgrading_to_sql_db_2.0.0.md)
+- [2.X -> 3.0](./docs/upgrading_to_sql_db_3.0.0.md)
+
 ## Root module
 
 The root module has been deprecated. Please switch to using one of the submodules.

docs/upgrading_to_sql_db_3.0.0.md

@@ -0,0 +1,69 @@
+# Upgrading to SQL DB 3.0.0
+
+The 3.0.0 release of SQL DB is a backward incompatible release. The `peering_completed` string variable along with hardcoded "tf_dependency" label in `user_labels` variable used to ensure that resources are created in a proper order when using private IPs and service network peering were dropped from `postgresql` and `safer_mysql` submodules. Instead the `module_depends_on` variable was added to the `postgresql`, `safer_mysql` and `mysql` submodules, which is a list of modules/resources a submodule depends on.
+
+## Migration Instructions
+
+Prior to the 3.0.0 release, you needed to set the optional `peering_completed` input with a string id of a resource that should have been created before the target sql module (e.g. safer_mysql).
+
+```hcl
+// We define a connection with the VPC of the Cloud SQL instance.
+module "private-service-access" {
+  source      = "GoogleCloudPlatform/sql-db/google//modules/private_service_access"
+  project_id  = var.project_id
+  vpc_network = google_compute_network.default.name
+}
+
+module "safer-mysql-db" {
+  source           = "GoogleCloudPlatform/sql-db/google//modules/safer_mysql"
+  version          = "2.0.0"
+
+  name             = "example-safer-mysql-${random_id.name.hex}"
+  database_version = var.mysql_version
+  project_id       = var.project_id
+  region           = var.region
+  zone             = "c"
+
+  ...
+
+  assign_public_ip = true
+  vpc_network      = google_compute_network.default.self_link
+
+  // Used to enforce ordering in the creation of resources.
+  peering_completed = module.private-service-access.complete
+}
+
+```
+
+With the 3.0.0 release, the `module_depends_on` variable is presented which contains a list of modules/resources that should be created before the target sql module.
+
+```diff
+// We define a connection with the VPC of the Cloud SQL instance.
+module "private-service-access" {
+  source      = "GoogleCloudPlatform/sql-db/google//modules/private_service_access"
+  project_id  = var.project_id
+  vpc_network = google_compute_network.default.name
+}
+
+module "safer-mysql-db" {
+  source           = "GoogleCloudPlatform/sql-db/google//modules/safer_mysql"
+- version          = "2.0.0"
++ version          = "3.0.0"
+
+  name             = "example-safer-mysql-${random_id.name.hex}"
+  database_version = var.mysql_version
+  project_id       = var.project_id
+  region           = var.region
+  zone             = "c"
+
+  ...
+
+  assign_public_ip = true
+  vpc_network      = google_compute_network.default.self_link
+
+  // Used to enforce ordering in the creation of resources.
+- peering_completed = module.private-service-access.complete
++ module_depends_on = [module.private-service-access.complete]
+}
+
+```