feat: support sql version in metadata files

CONTRIBUTING_NEW_EXTENSION.md

@@ -76,6 +76,21 @@ remains constant, the versioning reflects the underlying Debian release:
 > upstream repositories and trigger update Pull Requests once your extension is
 > merged.
 
+#### Package Version vs. SQL Version
+
+Your `metadata.hcl` file requires two version fields:
+
+- **`package`**: The full Debian package version (e.g., `0.8.2-1.pgdg13+1`).
+  This includes packaging metadata and is used to install the correct package.
+
+- **`sql`**: The PostgreSQL extension version as it appears in the catalog
+  (e.g., `0.8.2`). This is the version of the extension that will be verified
+  as part of the automatic testing of the resulting containers. It should
+  match what is defined by the `default_version` field in the control file.
+
+The **SQL version** is optional and only needed if your extension uses
+`CREATE EXTENSION` (when `create_extension = true` in metadata).
+
 #### Inspecting the Package Content
 
 If you want to get a list of the files contained in the package, you need to

README.md

@@ -138,11 +138,12 @@ other tools to identify the base PostgreSQL version and OS distribution.
 
 ### CloudNativePG-Specific Labels
 
-| Label | Description | Example |
-| :--- | :--- | :--- |
-| `io.cloudnativepg.image.base.name` | Base PostgreSQL container image | `ghcr.io/cloudnative-pg/postgresql:18-minimal-bookworm` |
-| `io.cloudnativepg.image.base.pgmajor` | PostgreSQL major version | `18` |
-| `io.cloudnativepg.image.base.os` | Operating system distribution | `bookworm` |
+| Label | Description                      | Example |
+| :--- |:---------------------------------| :--- |
+| `io.cloudnativepg.image.base.name` | Base PostgreSQL container image  | `ghcr.io/cloudnative-pg/postgresql:18-minimal-bookworm` |
+| `io.cloudnativepg.image.base.pgmajor` | PostgreSQL major version         | `18` |
+| `io.cloudnativepg.image.base.os` | Operating system distribution    | `bookworm` |
+| `io.cloudnativepg.image.sql.version` | PostgreSQL extension SQL version | `0.8.2` |
 
 ### Standard OCI Labels
 

dagger/maintenance/image.go

@@ -147,16 +147,16 @@ func getExtensionImageWithTimestamp(metadata *extensionMetadata, distribution st
 // extractExtensionVersion returns the extension version for a given distribution and pgMajor,
 // extracted from the extension's metadata.
 func extractExtensionVersion(versions versionMap, distribution string, pgMajor int) (string, error) {
-	packageVersion := versions[distribution][strconv.Itoa(pgMajor)]
-	if packageVersion == "" {
+	extVersion, ok := versions[distribution][strconv.Itoa(pgMajor)]
+	if !ok {
 		return "", fmt.Errorf("no package version found for distribution %q and version %d",
 			distribution, pgMajor)
 	}
 
 	re := regexp.MustCompile(`^(\d+(?:\.\d+)+)`)
-	matches := re.FindStringSubmatch(packageVersion)
+	matches := re.FindStringSubmatch(extVersion.Package)
 	if len(matches) < 2 {
-		return "", fmt.Errorf("cannot extract extension version from %q", packageVersion)
+		return "", fmt.Errorf("cannot extract extension version from %q", extVersion.Package)
 	}
 
 	return matches[1], nil

dagger/maintenance/main.go

@@ -179,10 +179,10 @@ func (m *Maintenance) GenerateTestingValues(
 			targetExtensionImage)
 	}
 
-	version := annotations["org.opencontainers.image.version"]
-	if version == "" {
+	version := annotations["io.cloudnativepg.image.sql.version"]
+	if version == "" && metadata.CreateExtension {
 		return nil, fmt.Errorf(
-			"extension image %s doesn't have an 'org.opencontainers.image.version' annotation",
+			"extension image %s doesn't have an 'io.cloudnativepg.image.sql.version' annotation or its value is empty",
 			targetExtensionImage)
 	}
 

dagger/maintenance/parse.go

@@ -18,7 +18,11 @@ type buildMatrix struct {
 	MajorVersions []string
 }
 
-type versionMap map[string]map[string]string
+type extensionVersion struct {
+	Package string `hcl:"package" cty:"package"`
+}
+
+type versionMap map[string]map[string]extensionVersion
 
 type extensionMetadata struct {
 	Name                   string     `hcl:"name" cty:"name"`

docker-bake.hcl

@@ -79,6 +79,7 @@ target "default" {
     "index,manifest:io.cloudnativepg.image.base.name=${getBaseImage(distro, pgVersion)}",
     "index,manifest:io.cloudnativepg.image.base.pgmajor=${pgVersion}",
     "index,manifest:io.cloudnativepg.image.base.os=${distro}",
+    "index,manifest:io.cloudnativepg.image.sql.version=${getExtensionSqlVersion(distro, pgVersion)}",
   ]
   labels = {
     "org.opencontainers.image.created" = "${now}",
@@ -96,6 +97,7 @@ target "default" {
     "io.cloudnativepg.image.base.name" = "${getBaseImage(distro, pgVersion)}",
     "io.cloudnativepg.image.base.pgmajor" = "${pgVersion}",
     "io.cloudnativepg.image.base.os" = "${distro}",
+    "io.cloudnativepg.image.sql.version" = "${getExtensionSqlVersion(distro, pgVersion)}",
   }
 }
 
@@ -106,7 +108,12 @@ function getImageName {
 
 function getExtensionPackage {
   params = [ distro, pgVersion ]
-  result = metadata.versions[distro][pgVersion]
+  result = metadata.versions[distro][pgVersion]["package"]
+}
+
+function getExtensionSqlVersion {
+  params = [ distro, pgVersion ]
+  result = lookup(metadata.versions[distro][pgVersion], "sql", "")
 }
 
 // Parse the packageVersion to extract the MM.mm.pp extension version.

pg-crash/metadata.hcl

@@ -16,12 +16,16 @@ metadata = {
 
   versions = {
     bookworm = {
-      // renovate: suite=bookworm-pgdg depName=postgresql-18-pg-crash
-      "18" = "0.3-2.pgdg12+1"
+      "18" = {
+        // renovate: suite=bookworm-pgdg depName=postgresql-18-pg-crash
+        package = "0.3-2.pgdg12+1"
+      }
     }
     trixie = {
-      // renovate: suite=trixie-pgdg depName=postgresql-18-pg-crash
-      "18" = "0.3-2.pgdg13+1"
+      "18" = {
+        // renovate: suite=trixie-pgdg depName=postgresql-18-pg-crash
+        package = "0.3-2.pgdg13+1"
+      }
     }
   }
 }

pgaudit/metadata.hcl

@@ -14,12 +14,20 @@ metadata = {
 
   versions = {
     bookworm = {
-      // renovate: suite=bookworm-pgdg depName=postgresql-18-pgaudit
-      "18" = "18.0-2.pgdg12+1"
+      "18" = {
+        // renovate: suite=bookworm-pgdg depName=postgresql-18-pgaudit
+        package = "18.0-2.pgdg12+1"
+        // renovate: suite=bookworm-pgdg depName=postgresql-18-pgaudit extractVersion=^(?<version>\d+\.\d+).*$
+        sql     = "18.0"
+      }
     }
     trixie = {
-      // renovate: suite=trixie-pgdg depName=postgresql-18-pgaudit
-      "18" = "18.0-2.pgdg13+1"
+      "18" = {
+        // renovate: suite=trixie-pgdg depName=postgresql-18-pgaudit
+        package = "18.0-2.pgdg13+1"
+        // renovate: suite=trixie-pgdg depName=postgresql-18-pgaudit extractVersion=^(?<version>\d+\.\d+).*$
+        sql     = "18.0"
+      }
     }
   }
 }

pgvector/metadata.hcl

@@ -14,12 +14,20 @@ metadata = {
 
   versions = {
     bookworm = {
-      // renovate: suite=bookworm-pgdg depName=postgresql-18-pgvector
-      "18" = "0.8.2-1.pgdg12+1"
+      "18" = {
+        // renovate: suite=bookworm-pgdg depName=postgresql-18-pgvector
+        package = "0.8.2-1.pgdg12+1"
+        // renovate: suite=bookworm-pgdg depName=postgresql-18-pgvector extractVersion=^(?<version>\d+\.\d+\.\d+).*$
+        sql     = "0.8.2"
+      }
     }
     trixie = {
-      // renovate: suite=trixie-pgdg depName=postgresql-18-pgvector
-      "18" = "0.8.2-1.pgdg13+1"
+      "18" = {
+        // renovate: suite=trixie-pgdg depName=postgresql-18-pgvector
+        package = "0.8.2-1.pgdg13+1"
+        // renovate: suite=trixie-pgdg depName=postgresql-18-pgvector extractVersion=^(?<version>\d+\.\d+\.\d+).*$
+        sql     = "0.8.2"
+      }
     }
   }
 }

postgis/metadata.hcl

@@ -15,12 +15,20 @@ metadata = {
 
   versions = {
     bookworm = {
-      // renovate: suite=bookworm-pgdg depName=postgresql-18-postgis-3
-      "18" = "3.6.2+dfsg-1.pgdg12+1"
+      "18" = {
+        // renovate: suite=bookworm-pgdg depName=postgresql-18-postgis-3
+        package = "3.6.2+dfsg-1.pgdg12+1"
+        // renovate: suite=bookworm-pgdg depName=postgresql-18-postgis-3 extractVersion=^(?<version>\d+\.\d+\.\d+).*$
+        sql     = "3.6.2"
+      }
     }
     trixie = {
-      // renovate: suite=trixie-pgdg depName=postgresql-18-postgis-3
-      "18" = "3.6.2+dfsg-1.pgdg13+1"
+      "18" = {
+        // renovate: suite=trixie-pgdg depName=postgresql-18-postgis-3
+        package = "3.6.2+dfsg-1.pgdg13+1"
+        // renovate: suite=trixie-pgdg depName=postgresql-18-postgis-3 extractVersion=^(?<version>\d+\.\d+\.\d+).*$
+        sql     = "3.6.2"
+      }
     }
   }
 }

renovate.json

@@ -17,7 +17,7 @@
         "**/*.hcl"
       ],
       "matchStrings": [
-        "\\/\\/\\s*renovate:\\s*?(suite=(?<suite>.*?))?\\s*depName=(?<depName>.*?)?\\s*\"[A-Za-z0-9_-]+\"\\s*=\\s*\"(?<currentValue>.*)\""
+        "\\/\\/\\s*renovate:\\s*?(suite=(?<suite>.*?))?\\s*depName=(?<depName>.*?)?(?: extractVersion=(?<extractVersion>[^\\s]+?))?\\s*(sql|package)\\s*=\\s*\"(?<currentValue>.*)\""
       ],
       "registryUrlTemplate": "https://download.postgresql.org/pub/repos/apt?suite={{#if suite}}{{suite}}{{else}}stable{{/if}}&components=main&binaryArch=amd64",
       "datasourceTemplate": "deb"

templates/metadata.hcl.tmpl

@@ -79,8 +79,15 @@ metadata = {
     {{- range $distro := .Distros}}
     {{ $distro }} = {
         {{- range $version := $.Versions}}
-        // renovate: suite={{ $distro }}-pgdg depName={{ replaceAll $.Package "%version%" $version }}
-        "{{ $version }}" = "<package-version-here>"
+        "{{ $version }}" = {
+          // renovate: suite={{ $distro }}-pgdg depName={{ replaceAll $.Package "%version%" $version }}
+          package = "<package-version-here>"
+          // TODO: Remove this comment after adding the sql version if extension uses CREATE EXTENSION
+          // TODO: Adjust the extractVersion regex pattern based on your extension's versioning scheme
+          // Examples: \d+\.\d+ for major.minor (e.g., "18.0"), \d+\.\d+\.\d+ for major.minor.patch (e.g., "0.8.2")
+          // renovate: suite={{ $distro }}-pgdg depName={{ replaceAll $.Package "%version%" $version }} extractVersion=^(?<version>\d+\.\d+\.\d+).*$
+          sql = "<sql-version-here>"
+        }
         {{- end}}
     }
     {{- end}}