feat: implement RDB engine upgrade using MajorUpgradeWorkflow to minimize downtime and preserve endpoints

Author: jremy42

docs/resources/rdb_instance.md

@@ -25,6 +25,37 @@ resource "scaleway_rdb_instance" "main" {
 }
 ```
 
+### Example Engine Upgrade
+
+```terraform
+resource "scaleway_rdb_instance" "main" {
+  name           = "test-rdb-upgrade"
+  node_type      = "DB-DEV-S"
+  engine         = "PostgreSQL-14"  # Start with older version
+  is_ha_cluster  = false
+  disable_backup = true
+  user_name      = "my_user"
+  password       = "thiZ_is_v&ry_s3cret"
+}
+
+# Upgrade to newer version by changing the engine value
+# Available versions can be found in the upgradable_versions attribute
+resource "scaleway_rdb_instance" "upgraded" {
+  name           = "test-rdb-upgrade"
+  node_type      = "DB-DEV-S"
+  engine         = "PostgreSQL-15"  # Upgrade to newer version
+  is_ha_cluster  = false
+  disable_backup = true
+  user_name      = "my_user"
+  password       = "thiZ_is_v&ry_s3cret"
+}
+
+# Check available upgrade versions
+output "upgradable_versions" {
+  value = scaleway_rdb_instance.main.upgradable_versions
+}
+```
+
 ### Example Block Storage Low Latency
 
 ```terraform
@@ -143,7 +174,7 @@ interruption.
 
 - `engine` - (Required) Database Instance's engine version (e.g. `PostgreSQL-11`).
 
-~> **Important** Updates to `engine` will recreate the Database Instance.
+~> **Important** Updates to `engine` will perform a blue/green upgrade using a snapshot and endpoint migration. This ensures minimal downtime but any writes between the snapshot and the switch will be lost. Available upgrade versions can be found in the `upgradable_versions` computed attribute.
 
 - `volume_type` - (Optional, default to `lssd`) Type of volume where data are stored (`lssd`, `sbs_5k` or `sbs_15k`).
 
@@ -244,6 +275,11 @@ are of the form `{region}/{id}`, e.g. `fr-par/11111111-1111-1111-1111-1111111111
     - `id` - The ID of the IPv4 address resource.
     - `address` - The private IPv4 address.
 - `certificate` - Certificate of the Database Instance.
+- `upgradable_versions` - List of available engine versions for upgrade.
+    - `id` - Version ID for upgrade requests.
+    - `name` - Engine name.
+    - `version` - Version string.
+    - `minor_version` - Minor version string.
 - `organization_id` - The organization ID the Database Instance is associated with.
 
 ## Limitations

internal/services/rdb/instance.go

@@ -59,8 +59,7 @@ func ResourceInstance() *schema.Resource {
 				Type:             schema.TypeString,
 				Optional:         true,
 				Computed:         true,
-				ForceNew:         true,
-				Description:      "Database's engine version id",
+				Description:      "Database's engine version id. Changing this value triggers a blue/green upgrade using MajorUpgradeWorkflow with automatic endpoint migration",
 				DiffSuppressFunc: dsf.IgnoreCase,
 				ConflictsWith: []string{
 					"snapshot_id",
@@ -327,6 +326,35 @@ func ResourceInstance() *schema.Resource {
 				Optional:    true,
 				Description: "Enable or disable encryption at rest for the database instance",
 			},
+			"upgradable_versions": {
+				Type:        schema.TypeList,
+				Computed:    true,
+				Description: "List of available engine versions for upgrade",
+				Elem: &schema.Resource{
+					Schema: map[string]*schema.Schema{
+						"id": {
+							Type:        schema.TypeString,
+							Computed:    true,
+							Description: "Version ID for upgrade requests",
+						},
+						"name": {
+							Type:        schema.TypeString,
+							Computed:    true,
+							Description: "Engine name",
+						},
+						"version": {
+							Type:        schema.TypeString,
+							Computed:    true,
+							Description: "Version string",
+						},
+						"minor_version": {
+							Type:        schema.TypeString,
+							Computed:    true,
+							Description: "Minor version string",
+						},
+					},
+				},
+			},
 			"private_ip": {
 				Type:        schema.TypeList,
 				Computed:    true,
@@ -671,6 +699,17 @@ func ResourceRdbInstanceRead(ctx context.Context, d *schema.ResourceData, m any)
 		_ = d.Set("encryption_at_rest", res.Encryption.Enabled)
 	}
 
+	upgradableVersions := make([]map[string]interface{}, len(res.UpgradableVersion))
+	for i, version := range res.UpgradableVersion {
+		upgradableVersions[i] = map[string]interface{}{
+			"id":            version.ID,
+			"name":          version.Name,
+			"version":       version.Version,
+			"minor_version": version.MinorVersion,
+		}
+	}
+	_ = d.Set("upgradable_versions", upgradableVersions)
+
 	// set user and password
 	if user, ok := d.GetOk("user_name"); ok {
 		_ = d.Set("user_name", user.(string))
@@ -911,18 +950,54 @@ func ResourceRdbInstanceUpdate(ctx context.Context, d *schema.ResourceData, m an
 			})
 	}
 
+	if d.HasChange("engine") {
+		oldEngine, newEngine := d.GetChange("engine")
+		newEngineStr := newEngine.(string)
+
+		targetVersionID := ""
+		var availableVersions []string
+		for _, version := range rdbInstance.UpgradableVersion {
+			availableVersions = append(availableVersions, version.Name)
+			if version.ID == newEngineStr || version.Version == newEngineStr || version.Name == newEngineStr {
+				targetVersionID = version.ID
+				break
+			}
+		}
+
+		if targetVersionID == "" {
+			return diag.FromErr(fmt.Errorf("engine version %s is not available for upgrade from %s. Available versions: %v",
+				newEngineStr, oldEngine.(string), availableVersions))
+		}
+
+		upgradeInstanceRequests = append(upgradeInstanceRequests,
+			rdb.UpgradeInstanceRequest{
+				Region:     region,
+				InstanceID: ID,
+				MajorUpgradeWorkflow: &rdb.UpgradeInstanceRequestMajorUpgradeWorkflow{
+					UpgradableVersionID: targetVersionID,
+					WithEndpoints:       true,
+				},
+			})
+	}
+
 	// Carry out the upgrades
 	for i := range upgradeInstanceRequests {
 		_, err = waitForRDBInstance(ctx, rdbAPI, region, ID, d.Timeout(schema.TimeoutUpdate))
 		if err != nil && !httperrors.Is404(err) {
 			return diag.FromErr(err)
 		}
 
-		_, err = rdbAPI.UpgradeInstance(&upgradeInstanceRequests[i], scw.WithContext(ctx))
+		upgradedInstance, err := rdbAPI.UpgradeInstance(&upgradeInstanceRequests[i], scw.WithContext(ctx))
 		if err != nil {
 			return diag.FromErr(err)
 		}
 
+		if upgradeInstanceRequests[i].MajorUpgradeWorkflow != nil && upgradedInstance.ID != ID {
+			tflog.Info(ctx, fmt.Sprintf("Engine upgrade created new instance, updating ID from %s to %s", ID, upgradedInstance.ID))
+			ID = upgradedInstance.ID
+			d.SetId(regional.NewIDString(region, ID))
+		}
+
 		_, err = waitForRDBInstance(ctx, rdbAPI, region, ID, d.Timeout(schema.TimeoutUpdate))
 		if err != nil && !httperrors.Is404(err) {
 			return diag.FromErr(err)

internal/services/rdb/instance_test.go

@@ -1542,6 +1542,71 @@ func TestAccInstance_EndpointErrorHandling(t *testing.T) {
 	})
 }
 
+func TestAccInstance_EngineUpgrade(t *testing.T) {
+	tt := acctest.NewTestTools(t)
+	defer tt.Cleanup()
+
+	// Get two different PostgreSQL versions for upgrade testing
+	oldVersion, newVersion := rdbchecks.GetEngineVersionsForUpgrade(tt, postgreSQLEngineName)
+	if oldVersion == newVersion {
+		t.Skip("Need at least 2 different PostgreSQL versions for upgrade testing")
+	}
+
+	resource.ParallelTest(t, resource.TestCase{
+		PreCheck:                 func() { acctest.PreCheck(t) },
+		ProtoV6ProviderFactories: tt.ProviderFactories,
+		CheckDestroy:             rdbchecks.IsInstanceDestroyed(tt),
+		Steps: []resource.TestStep{
+			// Step 1: Create instance with older engine version
+			{
+				Config: fmt.Sprintf(`
+					resource "scaleway_rdb_instance" "main" {
+						name           = "test-rdb-engine-upgrade"
+						node_type      = "db-dev-s"
+						engine         = %q
+						is_ha_cluster  = false
+						disable_backup = true
+						user_name      = "test_user"
+						password       = "thiZ_is_v&ry_s3cret"
+						tags           = ["terraform-test", "engine-upgrade"]
+						volume_type    = "sbs_5k"
+						volume_size_in_gb = 10
+					}
+				`, oldVersion),
+				Check: resource.ComposeTestCheckFunc(
+					isInstancePresent(tt, "scaleway_rdb_instance.main"),
+					resource.TestCheckResourceAttr("scaleway_rdb_instance.main", "engine", oldVersion),
+					resource.TestCheckResourceAttrSet("scaleway_rdb_instance.main", "upgradable_versions.#"),
+				),
+			},
+			// Step 2: Upgrade to newer engine version
+			{
+				Config: fmt.Sprintf(`
+					resource "scaleway_rdb_instance" "main" {
+						name           = "test-rdb-engine-upgrade"
+						node_type      = "db-dev-s"
+						engine         = %q
+						is_ha_cluster  = false
+						disable_backup = true
+						user_name      = "test_user"
+						password       = "thiZ_is_v&ry_s3cret"
+						tags           = ["terraform-test", "engine-upgrade"]
+						volume_type    = "sbs_5k"
+						volume_size_in_gb = 10
+					}
+				`, newVersion),
+				Check: resource.ComposeTestCheckFunc(
+					isInstancePresent(tt, "scaleway_rdb_instance.main"),
+					resource.TestCheckResourceAttr("scaleway_rdb_instance.main", "engine", newVersion),
+					resource.TestCheckResourceAttr("scaleway_rdb_instance.main", "name", "test-rdb-engine-upgrade"),
+					// Verify endpoints are preserved
+					resource.TestCheckResourceAttrSet("scaleway_rdb_instance.main", "load_balancer.0.ip"),
+				),
+			},
+		},
+	})
+}
+
 func isInstancePresent(tt *acctest.TestTools, n string) resource.TestCheckFunc {
 	return func(s *terraform.State) error {
 		rs, ok := s.RootModule().Resources[n]

internal/services/rdb/testdata/instance-engine-upgrade.cassette.yaml

@@ -73,3 +73,30 @@ func GetLatestEngineVersion(tt *acctest.TestTools, engineName string) string {
 
 	return latestEngineVersion
 }
+
+func GetEngineVersionsForUpgrade(tt *acctest.TestTools, engineName string) (string, string) {
+	api := rdbSDK.NewAPI(tt.Meta.ScwClient())
+
+	engines, err := api.ListDatabaseEngines(&rdbSDK.ListDatabaseEnginesRequest{})
+	if err != nil {
+		tt.T.Fatalf("Could not get engine versions: %s", err)
+	}
+
+	for _, engine := range engines.Engines {
+		if engine.Name == engineName {
+			var availableVersions []string
+			for _, version := range engine.Versions {
+				if !version.Disabled {
+					availableVersions = append(availableVersions, version.Name)
+				}
+			}
+
+			if len(availableVersions) >= 2 {
+				return availableVersions[1], availableVersions[0]
+			}
+		}
+	}
+
+	tt.T.Fatalf("Could not find two different versions for engine %s", engineName)
+	return "", ""
+}