Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

feat: support AWS RDS IAM auth for metadata database (#20189)

p0ny1c33ef45e84e
diff --git a/backend/store/db_connection.go b/backend/store/db_connection.go
index 144ca0eaa3..d96aaddf9b 100644
--- a/backend/store/db_connection.go
+++ b/backend/store/db_connection.go
@@ -185,13 +185,46 @@ func isFilePath(s string) bool {
return false
}
- if strings.Contains(s, "host=/tmp") {
+ if isKeywordValuePGURL(s) {
return false
}
return true
}
+func isKeywordValuePGURL(s string) bool {
+ for _, field := range strings.Fields(s) {
+ eqIdx := strings.IndexRune(field, '=')
+ if eqIdx < 0 {
+ continue
+ }
+
+ switch field[:eqIdx] {
+ case "host",
+ "hostaddr",
+ "port",
+ "dbname",
+ "database",
+ "user",
+ "password",
+ "passfile",
+ "connect_timeout",
+ "sslmode",
+ "sslrootcert",
+ "sslcert",
+ "sslkey",
+ "service",
+ "servicefile",
+ "target_session_attrs",
+ "application_name",
+ metadataDBAWSRDSIAMParam,
+ metadataDBAWSRegionParam:
+ return true
+ }
+ }
+ return false
+}
+
func readURLFromFile(path string) (string, error) {
content, err := os.ReadFile(path)
if err != nil {
@@ -206,8 +239,20 @@ func createConnectionWithTracer(ctx context.Context, pgURL string) (*sql.DB, err
return nil, errors.Wrap(err, "failed to parse database URL")
}
+ authConfig, err := metadataDBAuthConfigFromPGXConfig(pgxConfig)
+ if err != nil {
+ return nil, err
+ }
+
pgxConfig.Tracer = &metadataDBTracer{}
- db := stdlib.OpenDB(*pgxConfig)
+ var tokenProvider metadataDBTokenProvider
+ if authConfig != nil && authConfig.enabled {
+ tokenProvider, err = newAWSMetadataDBTokenProvider(ctx, authConfig.region)
+ if err != nil {
+ return nil, err
+ }
+ }
+ db := stdlib.OpenDB(*pgxConfig, metadataDBOpenOptions(authConfig, tokenProvider)...)
// Validate connection
if err := db.PingContext(ctx); err != nil {
diff --git a/backend/store/db_connection_test.go b/backend/store/db_connection_test.go
new file mode 100644
index 0000000000..387068a983
--- /dev/null
+++ b/backend/store/db_connection_test.go
@@ -0,0 +1,62 @@
+package store
+
+import (
+ "testing"
+
+ "github.com/stretchr/testify/require"
+)
+
+func TestIsFilePath(t *testing.T) {
+ tests := []struct {
+ name string
+ in string
+ want bool
+ }{
+ {
+ name: "postgres URL",
+ in: "postgres://[email protected]:5432/bytebase",
+ want: false,
+ },
+ {
+ name: "postgresql URL",
+ in: "postgresql://[email protected]:5432/bytebase",
+ want: false,
+ },
+ {
+ name: "keyword value DSN",
+ in: "host=example.com port=5432 user=bb dbname=bytebase",
+ want: false,
+ },
+ {
+ name: "keyword value IAM DSN",
+ in: "host=example.com port=5432 user=bb dbname=bytebase bytebase_aws_rds_iam=true bytebase_aws_region=us-east-1 sslmode=verify-full",
+ want: false,
+ },
+ {
+ name: "keyword value DSN with runtime parameter first",
+ in: "application_name=bytebase host=example.com port=5432 user=bb dbname=bytebase",
+ want: false,
+ },
+ {
+ name: "unix socket keyword value DSN",
+ in: "host=/tmp port=5432 user=bb dbname=bytebase",
+ want: false,
+ },
+ {
+ name: "file path",
+ in: "/var/run/bytebase/pg-url",
+ want: true,
+ },
+ {
+ name: "file path with equals",
+ in: "/var/run/bytebase/pg-url=prod",
+ want: true,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ require.Equal(t, tt.want, isFilePath(tt.in))
+ })
+ }
+}
diff --git a/backend/store/metadata_db_auth.go b/backend/store/metadata_db_auth.go
new file mode 100644
index 0000000000..767c42f715
--- /dev/null
+++ b/backend/store/metadata_db_auth.go
@@ -0,0 +1,113 @@
+package store
+
+import (
+ "context"
+ "net"
+ "strconv"
+
+ "github.com/aws/aws-sdk-go-v2/aws"
+ "github.com/aws/aws-sdk-go-v2/config"
+ "github.com/aws/aws-sdk-go-v2/feature/rds/auth"
+ "github.com/jackc/pgx/v5"
+ "github.com/jackc/pgx/v5/stdlib"
+ "github.com/pkg/errors"
+)
+
+const (
+ metadataDBAWSRDSIAMParam = "bytebase_aws_rds_iam"
+ metadataDBAWSRegionParam = "bytebase_aws_region"
+)
+
+type metadataDBAuthConfig struct {
+ enabled bool
+ region string
+ endpoint string
+ user string
+}
+
+type metadataDBTokenProvider interface {
+ BuildAuthToken(ctx context.Context, endpoint, region, user string) (string, error)
+}
+
+type awsMetadataDBTokenProvider struct {
+ credentials aws.CredentialsProvider
+}
+
+func newAWSMetadataDBTokenProvider(ctx context.Context, region string) (*awsMetadataDBTokenProvider, error) {
+ cfg, err := config.LoadDefaultConfig(ctx, config.WithRegion(region))
+ if err != nil {
+ return nil, errors.Wrap(err, "failed to load AWS config")
+ }
+
+ return &awsMetadataDBTokenProvider{
+ credentials: cfg.Credentials,
+ }, nil
+}
+
+func (p *awsMetadataDBTokenProvider) BuildAuthToken(ctx context.Context, endpoint, region, user string) (string, error) {
+ token, err := auth.BuildAuthToken(ctx, endpoint, region, user, p.credentials)
+ if err != nil {
+ return "", errors.Wrap(err, "failed to create authentication token")
+ }
+ return token, nil
+}
+
+func metadataDBAuthConfigFromPGXConfig(pgxConfig *pgx.ConnConfig) (*metadataDBAuthConfig, error) {
+ iamEnabled := pgxConfig.RuntimeParams[metadataDBAWSRDSIAMParam] == "true"
+ region := pgxConfig.RuntimeParams[metadataDBAWSRegionParam]
+ delete(pgxConfig.RuntimeParams, metadataDBAWSRDSIAMParam)
+ delete(pgxConfig.RuntimeParams, metadataDBAWSRegionParam)
+
+ if !iamEnabled {
+ return nil, nil
+ }
+
+ if region == "" {
+ return nil, errors.Errorf("%s is required when metadata database AWS RDS IAM auth is enabled", metadataDBAWSRegionParam)
+ }
+
+ if pgxConfig.User == "" {
+ return nil, errors.New("database user is required when metadata database AWS RDS IAM auth is enabled")
+ }
+
+ if pgxConfig.Host == "" {
+ return nil, errors.New("database host is required when metadata database AWS RDS IAM auth is enabled")
+ }
+
+ if pgxConfig.Port == 0 {
+ return nil, errors.New("database port is required when metadata database AWS RDS IAM auth is enabled")
+ }
+
+ if len(pgxConfig.Fallbacks) > 0 {
+ return nil, errors.New("metadata database AWS RDS IAM auth does not support fallback hosts or TLS fallback")
+ }
+
+ if pgxConfig.TLSConfig == nil || pgxConfig.TLSConfig.InsecureSkipVerify || pgxConfig.TLSConfig.ServerName == "" {
+ return nil, errors.New("verified TLS is required when metadata database AWS RDS IAM auth is enabled")
+ }
+
+ return &metadataDBAuthConfig{
+ enabled: true,
+ region: region,
+ endpoint: net.JoinHostPort(pgxConfig.Host, strconv.FormatUint(uint64(pgxConfig.Port), 10)),
+ user: pgxConfig.User,
+ }, nil
+}
+
+func newMetadataDBBeforeConnect(authConfig *metadataDBAuthConfig, tokenProvider metadataDBTokenProvider) func(context.Context, *pgx.ConnConfig) error {
+ return func(ctx context.Context, connConfig *pgx.ConnConfig) error {
+ token, err := tokenProvider.BuildAuthToken(ctx, authConfig.endpoint, authConfig.region, authConfig.user)
+ if err != nil {
+ return errors.Wrapf(err, "failed to build metadata database AWS RDS IAM auth token for endpoint %q, region %q, user %q", authConfig.endpoint, authConfig.region, authConfig.user)
+ }
+ connConfig.Password = token
+ return nil
+ }
+}
+
+func metadataDBOpenOptions(authConfig *metadataDBAuthConfig, tokenProvider metadataDBTokenProvider) []stdlib.OptionOpenDB {
+ if authConfig == nil || !authConfig.enabled {
+ return nil
+ }
+ return []stdlib.OptionOpenDB{stdlib.OptionBeforeConnect(newMetadataDBBeforeConnect(authConfig, tokenProvider))}
+}
diff --git a/backend/store/metadata_db_auth_test.go b/backend/store/metadata_db_auth_test.go
new file mode 100644
index 0000000000..4189042564
--- /dev/null
+++ b/backend/store/metadata_db_auth_test.go
@@ -0,0 +1,225 @@
+package store
+
+import (
+ "context"
+ "errors"
+ "testing"
+
+ "github.com/jackc/pgx/v5"
+ "github.com/stretchr/testify/require"
+)
+
+type fakeMetadataDBTokenProvider struct {
+ token string
+ err error
+ calls []fakeMetadataDBTokenProviderCall
+}
+
+type fakeMetadataDBTokenProviderCall struct {
+ endpoint string
+ region string
+ user string
+}
+
+func (p *fakeMetadataDBTokenProvider) BuildAuthToken(_ context.Context, endpoint, region, user string) (string, error) {
+ p.calls = append(p.calls, fakeMetadataDBTokenProviderCall{
+ endpoint: endpoint,
+ region: region,
+ user: user,
+ })
+ return p.token, p.err
+}
+
+func TestMetadataDBAuthConfigFromPGXConfigDisabled(t *testing.T) {
+ pgxConfig := mustParseMetadataDBPGXConfig(t, "postgres://bb:[email protected]:5432/bytebase?sslmode=verify-full")
+
+ authConfig, err := metadataDBAuthConfigFromPGXConfig(pgxConfig)
+
+ require.NoError(t, err)
+ require.Nil(t, authConfig)
+}
+
+func TestMetadataDBAuthConfigFromPGXConfigEnabledURL(t *testing.T) {
+ pgxConfig := mustParseMetadataDBPGXConfig(t, "postgres://[email protected]:5432/bytebase?sslmode=verify-full&bytebase_aws_rds_iam=true&bytebase_aws_region=us-east-1")
+
+ authConfig, err := metadataDBAuthConfigFromPGXConfig(pgxConfig)
+
+ require.NoError(t, err)
+ require.NotNil(t, authConfig)
+ require.True(t, authConfig.enabled)
+ require.Equal(t, "us-east-1", authConfig.region)
+ require.Equal(t, "example.us-east-1.rds.amazonaws.com:5432", authConfig.endpoint)
+ require.Equal(t, "bb_meta", authConfig.user)
+ require.NotContains(t, pgxConfig.RuntimeParams, metadataDBAWSRDSIAMParam)
+ require.NotContains(t, pgxConfig.RuntimeParams, metadataDBAWSRegionParam)
+}
+
+func TestMetadataDBAuthConfigFromPGXConfigEnabledKeywordValue(t *testing.T) {
+ pgxConfig := mustParseMetadataDBPGXConfig(t, "host=example.us-east-1.rds.amazonaws.com port=5432 user=bb_meta dbname=bytebase sslmode=verify-full bytebase_aws_rds_iam=true bytebase_aws_region=us-east-1")
+
+ authConfig, err := metadataDBAuthConfigFromPGXConfig(pgxConfig)
+
+ require.NoError(t, err)
+ require.NotNil(t, authConfig)
+ require.True(t, authConfig.enabled)
+ require.Equal(t, "us-east-1", authConfig.region)
+ require.Equal(t, "example.us-east-1.rds.amazonaws.com:5432", authConfig.endpoint)
+ require.Equal(t, "bb_meta", authConfig.user)
+ require.NotContains(t, pgxConfig.RuntimeParams, metadataDBAWSRDSIAMParam)
+ require.NotContains(t, pgxConfig.RuntimeParams, metadataDBAWSRegionParam)
+}
+
+func TestMetadataDBAuthConfigFromPGXConfigStripsDisabledBytebaseAWSParams(t *testing.T) {
+ pgxConfig := mustParseMetadataDBPGXConfig(t, "postgres://bb:[email protected]:5432/bytebase?bytebase_aws_rds_iam=false&bytebase_aws_region=us-east-1&sslmode=verify-full")
+
+ authConfig, err := metadataDBAuthConfigFromPGXConfig(pgxConfig)
+
+ require.NoError(t, err)
+ require.Nil(t, authConfig)
+ require.NotContains(t, pgxConfig.RuntimeParams, metadataDBAWSRDSIAMParam)
+ require.NotContains(t, pgxConfig.RuntimeParams, metadataDBAWSRegionParam)
+}
+
+func TestMetadataDBAuthConfigFromPGXConfigRequiresFields(t *testing.T) {
+ tests := []struct {
+ name string
+ configure func(*pgx.ConnConfig)
+ wantErr string
+ }{
+ {
+ name: "region",
+ configure: func(config *pgx.ConnConfig) { delete(config.RuntimeParams, metadataDBAWSRegionParam) },
+ wantErr: "bytebase_aws_region is required",
+ },
+ {
+ name: "user",
+ configure: func(config *pgx.ConnConfig) { config.User = "" },
+ wantErr: "database user is required",
+ },
+ {
+ name: "host",
+ configure: func(config *pgx.ConnConfig) { config.Host = "" },
+ wantErr: "database host is required",
+ },
+ {
+ name: "port",
+ configure: func(config *pgx.ConnConfig) { config.Port = 0 },
+ wantErr: "database port is required",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ pgxConfig := mustParseMetadataDBPGXConfig(t, "postgres://[email protected]:5432/bytebase?sslmode=verify-full&bytebase_aws_rds_iam=true&bytebase_aws_region=us-east-1")
+ tt.configure(pgxConfig)
+
+ _, err := metadataDBAuthConfigFromPGXConfig(pgxConfig)
+
+ require.ErrorContains(t, err, tt.wantErr)
+ })
+ }
+}
+
+func TestMetadataDBAuthConfigFromPGXConfigNonURIAllowsAWSParamNamesInValues(t *testing.T) {
+ pgxConfig := mustParseMetadataDBPGXConfig(t, "host=example.us-east-1.rds.amazonaws.com port=5432 user=bb password=bytebase_aws_region application_name=bytebase_aws_rds_iam")
+
+ authConfig, err := metadataDBAuthConfigFromPGXConfig(pgxConfig)
+
+ require.NoError(t, err)
+ require.Nil(t, authConfig)
+}
+
+func TestMetadataDBAuthConfigFromPGXConfigRequiresVerifiedTLS(t *testing.T) {
+ tests := []struct {
+ name string
+ pgURL string
+ }{
+ {
+ name: "disable",
+ pgURL: "postgres://[email protected]:5432/bytebase?sslmode=disable&bytebase_aws_rds_iam=true&bytebase_aws_region=us-east-1",
+ },
+ {
+ name: "require",
+ pgURL: "postgres://[email protected]:5432/bytebase?sslmode=require&bytebase_aws_rds_iam=true&bytebase_aws_region=us-east-1",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ pgxConfig := mustParseMetadataDBPGXConfig(t, tt.pgURL)
+
+ _, err := metadataDBAuthConfigFromPGXConfig(pgxConfig)
+
+ require.ErrorContains(t, err, "verified TLS is required")
+ })
+ }
+}
+
+func TestMetadataDBAuthConfigFromPGXConfigRejectsFallbacks(t *testing.T) {
+ pgxConfig := mustParseMetadataDBPGXConfig(t, "postgres://[email protected]:5432/bytebase?sslmode=prefer&bytebase_aws_rds_iam=true&bytebase_aws_region=us-east-1")
+
+ _, err := metadataDBAuthConfigFromPGXConfig(pgxConfig)
+
+ require.ErrorContains(t, err, "fallback hosts or TLS fallback")
+}
+
+func TestNewMetadataDBBeforeConnectSetsPassword(t *testing.T) {
+ tokenProvider := &fakeMetadataDBTokenProvider{token: "generated-token"}
+ hook := newMetadataDBBeforeConnect(&metadataDBAuthConfig{
+ endpoint: "example.us-east-1.rds.amazonaws.com:5432",
+ region: "us-east-1",
+ user: "bb_meta",
+ }, tokenProvider)
+ connConfig := &pgx.ConnConfig{}
+
+ err := hook(context.Background(), connConfig)
+
+ require.NoError(t, err)
+ require.Equal(t, "generated-token", connConfig.Password)
+ require.Equal(t, []fakeMetadataDBTokenProviderCall{
+ {
+ endpoint: "example.us-east-1.rds.amazonaws.com:5432",
+ region: "us-east-1",
+ user: "bb_meta",
+ },
+ }, tokenProvider.calls)
+}
+
+func TestNewMetadataDBBeforeConnectReturnsTokenError(t *testing.T) {
+ tokenProvider := &fakeMetadataDBTokenProvider{err: errors.New("credential chain failed")}
+ hook := newMetadataDBBeforeConnect(&metadataDBAuthConfig{
+ endpoint: "example.us-east-1.rds.amazonaws.com:5432",
+ region: "us-east-1",
+ user: "bb_meta",
+ }, tokenProvider)
+ connConfig := &pgx.ConnConfig{}
+
+ err := hook(context.Background(), connConfig)
+
+ require.ErrorContains(t, err, "failed to build metadata database AWS RDS IAM auth token")
+ require.ErrorContains(t, err, "example.us-east-1.rds.amazonaws.com:5432")
+ require.ErrorContains(t, err, "us-east-1")
+ require.ErrorContains(t, err, "bb_meta")
+ require.Empty(t, connConfig.Password)
+}
+
+func TestMetadataDBOpenOptions(t *testing.T) {
+ require.Empty(t, metadataDBOpenOptions(nil, &fakeMetadataDBTokenProvider{}))
+
+ authConfig := &metadataDBAuthConfig{
+ enabled: true,
+ region: "us-east-1",
+ endpoint: "example.us-east-1.rds.amazonaws.com:5432",
+ user: "bb_meta",
+ }
+
+ require.Len(t, metadataDBOpenOptions(authConfig, &fakeMetadataDBTokenProvider{}), 1)
+}
+
+func mustParseMetadataDBPGXConfig(t *testing.T, pgURL string) *pgx.ConnConfig {
+ t.Helper()
+
+ pgxConfig, err := pgx.ParseConfig(pgURL)
+ require.NoError(t, err)
+ return pgxConfig
+}
diff --git a/docs/operations/high-availability.md b/docs/operations/high-availability.md
index 7407a01582..9f54edbf0c 100644
--- a/docs/operations/high-availability.md
+++ b/docs/operations/high-availability.md
@@ -24,6 +24,16 @@ Before you keep more than one Bytebase server active at the same time, make sure
4. **Your platform provides traffic management and rollout control.**
- For example, a load balancer plus a rolling update strategy managed by your orchestrator.
+### AWS RDS IAM authentication for metadata PostgreSQL
+
+When the shared metadata PostgreSQL database is AWS RDS or Aurora PostgreSQL, every Bytebase replica can enable IAM auth by adding the Bytebase AWS parameters to `PG_URL`. URI-style values are recommended. Direct compact keyword/value values such as `host=... port=...` are also supported; this URI-style value is the typical shape:
+
+```text
+postgres://[email protected]:5432/bytebase?sslmode=verify-full&bytebase_aws_rds_iam=true&bytebase_aws_region=us-east-1
+```
+
+The PostgreSQL user must be granted `rds_iam`, and the AWS principal used by each Bytebase process must have `rds-db:connect` for that database user. Use verified TLS, such as `sslmode=verify-full`, with a trust store that validates the RDS certificate. Do not put AWS access keys in `PG_URL`; use the standard AWS SDK credential chain through the runtime environment, such as EKS IRSA, ECS task roles, EC2 instance profiles, environment variables, or shared AWS config.
+
## How replica detection works
Bytebase tracks live replicas with heartbeats:
diff --git a/docs/superpowers/plans/2026-04-29-aws-rds-iam-metadata-db.md b/docs/superpowers/plans/2026-04-29-aws-rds-iam-metadata-db.md
new file mode 100644
index 0000000000..b3f1d91d72
--- /dev/null
+++ b/docs/superpowers/plans/2026-04-29-aws-rds-iam-metadata-db.md
@@ -0,0 +1,812 @@
+# AWS RDS IAM Metadata DB Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add native AWS RDS IAM authentication for Bytebase's metadata PostgreSQL database while preserving existing `PG_URL` behavior.
+
+**Architecture:** Keep the feature inside `backend/store`, where metadata DB connections are created today. Parse and strip reserved `bytebase_aws_*` query parameters before pgx sees the URL, then use pgx stdlib `OptionBeforeConnect` to generate an AWS RDS auth token for each new physical connection. Helm renders the same URL shape for Kubernetes deployments, and docs explain operator prerequisites.
+
+**Tech Stack:** Go, pgx v5 stdlib, AWS SDK for Go v2 `config` and `feature/rds/auth`, Helm templates, Markdown docs.
+
+---
+
+## File Structure
+
+- Create `backend/store/metadata_db_auth.go`: private parser, auth config, token provider, and `BeforeConnect` hook for metadata DB IAM auth.
+- Create `backend/store/metadata_db_auth_test.go`: unit tests for URL parsing, stripping, validation, and hook behavior with fake token providers.
+- Modify `backend/store/db_connection.go`: call the parser before `pgx.ParseConfig` and pass `stdlib.OptionBeforeConnect` when IAM auth is enabled.
+- Modify `helm-charts/bytebase/values.yaml`: add `bytebase.option.externalPg.awsRdsIam.enabled` and `region` defaults.
+- Modify `helm-charts/bytebase/templates/statefulset.yaml`: render passwordless IAM `PG_URL` when `awsRdsIam.enabled` is true.
+- Modify `helm-charts/bytebase/README.md`: document the new chart values.
+- Modify `docs/operations/high-availability.md`: add a short note that all HA replicas using RDS IAM must share the same IAM-enabled metadata `PG_URL` shape and AWS principal setup.
+
+## Task 1: Add Metadata DB IAM URL Parser
+
+**Files:**
+- Create: `backend/store/metadata_db_auth.go`
+- Create: `backend/store/metadata_db_auth_test.go`
+
+- [ ] **Step 1: Write parser tests**
+
+Create `backend/store/metadata_db_auth_test.go` with:
+
+```go
+package store
+
+import (
+ "testing"
+
+ "github.com/stretchr/testify/require"
+)
+
+func TestParseMetadataDBAuthConfigDisabled(t *testing.T) {
+ cleanURL, authConfig, err := parseMetadataDBAuthConfig("postgres://bb:[email protected]:5432/bytebase?sslmode=verify-full")
+ require.NoError(t, err)
+ require.Nil(t, authConfig)
+ require.Equal(t, "postgres://bb:[email protected]:5432/bytebase?sslmode=verify-full", cleanURL)
+}
+
+func TestParseMetadataDBAuthConfigEnabled(t *testing.T) {
+ cleanURL, authConfig, err := parseMetadataDBAuthConfig("postgres://[email protected]:5432/bytebase?sslmode=verify-full&bytebase_aws_rds_iam=true&bytebase_aws_region=us-east-1")
+ require.NoError(t, err)
+ require.Equal(t, "postgres://[email protected]:5432/bytebase?sslmode=verify-full", cleanURL)
+ require.NotNil(t, authConfig)
+ require.True(t, authConfig.enabled)
+ require.Equal(t, "us-east-1", authConfig.region)
+ require.Equal(t, "example.us-east-1.rds.amazonaws.com:5432", authConfig.endpoint)
+ require.Equal(t, "bb_meta", authConfig.user)
+}
+
+func TestParseMetadataDBAuthConfigStripsDisabledBytebaseAWSParams(t *testing.T) {
+ cleanURL, authConfig, err := parseMetadataDBAuthConfig("postgres://bb:[email protected]:5432/bytebase?bytebase_aws_rds_iam=false&bytebase_aws_region=us-east-1&sslmode=verify-full")
+ require.NoError(t, err)
+ require.Nil(t, authConfig)
+ require.Equal(t, "postgres://bb:[email protected]:5432/bytebase?sslmode=verify-full", cleanURL)
+}
+
+func TestParseMetadataDBAuthConfigRequiresFields(t *testing.T) {
+ tests := []struct {
+ name string
+ pgURL string
+ wantErr string
+ }{
+ {
+ name: "region",
+ pgURL: "postgres://[email protected]:5432/bytebase?sslmode=verify-full&bytebase_aws_rds_iam=true",
+ wantErr: "bytebase_aws_region is required",
+ },
+ {
+ name: "user",
+ pgURL: "postgres://example.us-east-1.rds.amazonaws.com:5432/bytebase?sslmode=verify-full&bytebase_aws_rds_iam=true&bytebase_aws_region=us-east-1",
+ wantErr: "database user is required",
+ },
+ {
+ name: "host",
+ pgURL: "postgres://bb@:5432/bytebase?sslmode=verify-full&bytebase_aws_rds_iam=true&bytebase_aws_region=us-east-1",
+ wantErr: "database host is required",
+ },
+ {
+ name: "port",
+ pgURL: "postgres://[email protected]/bytebase?sslmode=verify-full&bytebase_aws_rds_iam=true&bytebase_aws_region=us-east-1",
+ wantErr: "database port is required",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ _, _, err := parseMetadataDBAuthConfig(tt.pgURL)
+ require.ErrorContains(t, err, tt.wantErr)
+ })
+ }
+}
+
+func TestParseMetadataDBAuthConfigRejectsIAMForNonURI(t *testing.T) {
+ _, _, err := parseMetadataDBAuthConfig("host=example.us-east-1.rds.amazonaws.com port=5432 user=bb bytebase_aws_rds_iam=true bytebase_aws_region=us-east-1")
+ require.ErrorContains(t, err, "metadata database AWS RDS IAM auth requires a postgres:// or postgresql:// URL")
+}
+
+func TestParseMetadataDBAuthConfigRequiresVerifyFullSSLMode(t *testing.T) {
+ tests := []struct {
+ name string
+ pgURL string
+ }{
+ {
+ name: "missing",
+ pgURL: "postgres://[email protected]:5432/bytebase?bytebase_aws_rds_iam=true&bytebase_aws_region=us-east-1",
+ },
+ {
+ name: "disable",
+ pgURL: "postgres://[email protected]:5432/bytebase?sslmode=disable&bytebase_aws_rds_iam=true&bytebase_aws_region=us-east-1",
+ },
+ {
+ name: "require",
+ pgURL: "postgres://[email protected]:5432/bytebase?sslmode=require&bytebase_aws_rds_iam=true&bytebase_aws_region=us-east-1",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ _, _, err := parseMetadataDBAuthConfig(tt.pgURL)
+ require.ErrorContains(t, err, "sslmode=verify-full is required")
+ })
+ }
+}
+```
+
+- [ ] **Step 2: Run parser tests to verify they fail**
+
+Run:
+
+```bash
+go test -v -count=1 ./backend/store -run '^TestParseMetadataDBAuthConfig'
+```
+
+Expected: FAIL with `undefined: parseMetadataDBAuthConfig`.
+
+- [ ] **Step 3: Implement the parser**
+
+Create `backend/store/metadata_db_auth.go` with:
+
+```go
+package store
+
+import (
+ "context"
+ "net"
+ "net/url"
+ "strings"
+
+ "github.com/jackc/pgx/v5"
+ "github.com/pkg/errors"
+)
+
+const (
+ metadataDBAWSRDSIAMParam = "bytebase_aws_rds_iam"
+ metadataDBAWSRegionParam = "bytebase_aws_region"
+)
+
+type metadataDBAuthConfig struct {
+ enabled bool
+ region string
+ endpoint string
+ user string
+}
+
+type metadataDBTokenProvider interface {
+ BuildAuthToken(ctx context.Context, endpoint, region, user string) (string, error)
+}
+
+func parseMetadataDBAuthConfig(pgURL string) (string, *metadataDBAuthConfig, error) {
+ if !strings.HasPrefix(pgURL, "postgres://") && !strings.HasPrefix(pgURL, "postgresql://") {
+ if strings.Contains(pgURL, metadataDBAWSRDSIAMParam) || strings.Contains(pgURL, metadataDBAWSRegionParam) {
+ return "", nil, errors.New("metadata database AWS RDS IAM auth requires a postgres:// or postgresql:// URL")
+ }
+ return pgURL, nil, nil
+ }
+
+ u, err := url.Parse(pgURL)
+ if err != nil {
+ return "", nil, errors.Wrap(err, "failed to parse database URL")
+ }
+
+ q := u.Query()
+ iamEnabled := q.Get(metadataDBAWSRDSIAMParam) == "true"
+ region := q.Get(metadataDBAWSRegionParam)
+ q.Del(metadataDBAWSRDSIAMParam)
+ q.Del(metadataDBAWSRegionParam)
+ u.RawQuery = q.Encode()
+ cleanURL := u.String()
+
+ if !iamEnabled {
+ return cleanURL, nil, nil
+ }
+
+ if region == "" {
+ return "", nil, errors.Errorf("%s is required when metadata database AWS RDS IAM auth is enabled", metadataDBAWSRegionParam)
+ }
+
+ if q.Get("sslmode") != "verify-full" {
+ return "", nil, errors.New("sslmode=verify-full is required when metadata database AWS RDS IAM auth is enabled")
+ }
+
+ user := u.User.Username()
+ if user == "" {
+ return "", nil, errors.New("database user is required when metadata database AWS RDS IAM auth is enabled")
+ }
+
+ host := u.Hostname()
+ if host == "" {
+ return "", nil, errors.New("database host is required when metadata database AWS RDS IAM auth is enabled")
+ }
+
+ port := u.Port()
+ if port == "" {
+ return "", nil, errors.New("database port is required when metadata database AWS RDS IAM auth is enabled")
+ }
+
+ return cleanURL, &metadataDBAuthConfig{
+ enabled: true,
+ region: region,
+ endpoint: net.JoinHostPort(host, port),
+ user: user,
+ }, nil
+}
+
+func newMetadataDBBeforeConnect(authConfig *metadataDBAuthConfig, tokenProvider metadataDBTokenProvider) func(context.Context, *pgx.ConnConfig) error {
+ return func(ctx context.Context, connConfig *pgx.ConnConfig) error {
+ token, err := tokenProvider.BuildAuthToken(ctx, authConfig.endpoint, authConfig.region, authConfig.user)
+ if err != nil {
+ return errors.Wrapf(err, "failed to build metadata database AWS RDS IAM auth token for endpoint %q, region %q, user %q", authConfig.endpoint, authConfig.region, authConfig.user)
+ }
+ connConfig.Password = token
+ return nil
+ }
+}
+```
+
+- [ ] **Step 4: Run parser tests to verify they pass**
+
+Run:
+
+```bash
+go test -v -count=1 ./backend/store -run '^TestParseMetadataDBAuthConfig'
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit parser**
+
+Run:
+
+```bash
+gofmt -w backend/store/metadata_db_auth.go backend/store/metadata_db_auth_test.go
+git add backend/store/metadata_db_auth.go backend/store/metadata_db_auth_test.go
+git commit -m "feat(store): parse metadata DB AWS IAM auth config"
+```
+
+## Task 2: Add Token Provider and BeforeConnect Tests
+
+**Files:**
+- Modify: `backend/store/metadata_db_auth.go`
+- Modify: `backend/store/metadata_db_auth_test.go`
+
+- [ ] **Step 1: Add hook tests**
+
+Update the import block in `backend/store/metadata_db_auth_test.go` to:
+
+```go
+import (
+ "context"
+ "errors"
+ "testing"
+
+ "github.com/jackc/pgx/v5"
+ "github.com/stretchr/testify/require"
+)
+```
+
+Then append this test code:
+
+```go
+type fakeMetadataDBTokenProvider struct {
+ token string
+ err error
+ calls []fakeMetadataDBTokenProviderCall
+}
+
+type fakeMetadataDBTokenProviderCall struct {
+ endpoint string
+ region string
+ user string
+}
+
+func (p *fakeMetadataDBTokenProvider) BuildAuthToken(_ context.Context, endpoint, region, user string) (string, error) {
+ p.calls = append(p.calls, fakeMetadataDBTokenProviderCall{
+ endpoint: endpoint,
+ region: region,
+ user: user,
+ })
+ return p.token, p.err
+}
+
+func TestNewMetadataDBBeforeConnectSetsPassword(t *testing.T) {
+ provider := &fakeMetadataDBTokenProvider{token: "generated-token"}
+ hook := newMetadataDBBeforeConnect(&metadataDBAuthConfig{
+ enabled: true,
+ region: "us-east-1",
+ endpoint: "example.us-east-1.rds.amazonaws.com:5432",
+ user: "bb_meta",
+ }, provider)
+
+ connConfig := &pgx.ConnConfig{}
+ require.NoError(t, hook(context.Background(), connConfig))
+ require.Equal(t, "generated-token", connConfig.Password)
+ require.Equal(t, []fakeMetadataDBTokenProviderCall{{
+ endpoint: "example.us-east-1.rds.amazonaws.com:5432",
+ region: "us-east-1",
+ user: "bb_meta",
+ }}, provider.calls)
+}
+
+func TestNewMetadataDBBeforeConnectReturnsTokenError(t *testing.T) {
+ provider := &fakeMetadataDBTokenProvider{err: errors.New("credential chain failed")}
+ hook := newMetadataDBBeforeConnect(&metadataDBAuthConfig{
+ enabled: true,
+ region: "us-east-1",
+ endpoint: "example.us-east-1.rds.amazonaws.com:5432",
+ user: "bb_meta",
+ }, provider)
+
+ connConfig := &pgx.ConnConfig{}
+ err := hook(context.Background(), connConfig)
+ require.ErrorContains(t, err, "failed to build metadata database AWS RDS IAM auth token")
+ require.ErrorContains(t, err, "example.us-east-1.rds.amazonaws.com:5432")
+ require.ErrorContains(t, err, "us-east-1")
+ require.ErrorContains(t, err, "bb_meta")
+ require.Empty(t, connConfig.Password)
+}
+```
+
+- [ ] **Step 2: Run hook tests**
+
+Run:
+
+```bash
+go test -v -count=1 ./backend/store -run '^TestNewMetadataDBBeforeConnect'
+```
+
+Expected: PASS. These tests use the hook already added in Task 1.
+
+- [ ] **Step 3: Add AWS production provider test seam**
+
+Modify the imports in `backend/store/metadata_db_auth.go` to include AWS SDK packages:
+
+```go
+import (
+ "context"
+ "net"
+ "net/url"
+ "strings"
+
+ "github.com/aws/aws-sdk-go-v2/aws"
+ "github.com/aws/aws-sdk-go-v2/config"
+ "github.com/aws/aws-sdk-go-v2/feature/rds/auth"
+ "github.com/jackc/pgx/v5"
+ "github.com/pkg/errors"
+)
+```
+
+Append the production provider to `backend/store/metadata_db_auth.go`. AWS config is loaded once while the metadata DB pool is being created; each `BeforeConnect` call reuses the cached credential provider and only builds a fresh RDS auth token:
+
+```go
+type awsMetadataDBTokenProvider struct {
+ credentials aws.CredentialsProvider
+}
+
+func newAWSMetadataDBTokenProvider(ctx context.Context, region string) (*awsMetadataDBTokenProvider, error) {
+ cfg, err := config.LoadDefaultConfig(ctx, config.WithRegion(region))
+ if err != nil {
+ return nil, errors.Wrap(err, "failed to load AWS config")
+ }
+
+ return &awsMetadataDBTokenProvider{
+ credentials: cfg.Credentials,
+ }, nil
+}
+
+func (p *awsMetadataDBTokenProvider) BuildAuthToken(ctx context.Context, endpoint, region, user string) (string, error) {
+ token, err := auth.BuildAuthToken(ctx, endpoint, region, user, p.credentials)
+ if err != nil {
+ return "", errors.Wrap(err, "failed to create authentication token")
+ }
+ return token, nil
+}
+```
+
+- [ ] **Step 4: Run focused store tests**
+
+Run:
+
+```bash
+go test -v -count=1 ./backend/store -run '^(TestParseMetadataDBAuthConfig|TestNewMetadataDBBeforeConnect)'
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit hook and provider**
+
+Run:
+
+```bash
+gofmt -w backend/store/metadata_db_auth.go backend/store/metadata_db_auth_test.go
+git add backend/store/metadata_db_auth.go backend/store/metadata_db_auth_test.go
+git commit -m "feat(store): add metadata DB AWS IAM token hook"
+```
+
+## Task 3: Wire IAM Auth into Metadata DB Connection Creation
+
+**Files:**
+- Modify: `backend/store/db_connection.go`
+- Modify: `backend/store/metadata_db_auth.go`
+
+- [ ] **Step 1: Add connection option helper test**
+
+Append this test to `backend/store/metadata_db_auth_test.go`:
+
+```go
+func TestMetadataDBOpenOptions(t *testing.T) {
+ require.Empty(t, metadataDBOpenOptions(nil, &fakeMetadataDBTokenProvider{}))
+
+ authConfig := &metadataDBAuthConfig{
+ enabled: true,
+ region: "us-east-1",
+ endpoint: "example.us-east-1.rds.amazonaws.com:5432",
+ user: "bb_meta",
+ }
+ require.Len(t, metadataDBOpenOptions(authConfig, &fakeMetadataDBTokenProvider{}), 1)
+}
+```
+
+- [ ] **Step 2: Run helper test to verify it fails**
+
+Run:
+
+```bash
+go test -v -count=1 ./backend/store -run '^TestMetadataDBOpenOptions$'
+```
+
+Expected: FAIL with `undefined: metadataDBOpenOptions`.
+
+- [ ] **Step 3: Add the connection option helper**
+
+Modify `backend/store/metadata_db_auth.go` imports to include pgx stdlib:
+
+```go
+ "github.com/jackc/pgx/v5/stdlib"
+```
+
+Append this function to `backend/store/metadata_db_auth.go`:
+
+```go
+func metadataDBOpenOptions(authConfig *metadataDBAuthConfig, tokenProvider metadataDBTokenProvider) []stdlib.OptionOpenDB {
+ if authConfig == nil || !authConfig.enabled {
+ return nil
+ }
+ return []stdlib.OptionOpenDB{
+ stdlib.OptionBeforeConnect(newMetadataDBBeforeConnect(authConfig, tokenProvider)),
+ }
+}
+```
+
+- [ ] **Step 4: Wire parser and open options into `createConnectionWithTracer`**
+
+Modify `createConnectionWithTracer` in `backend/store/db_connection.go` from:
+
+```go
+func createConnectionWithTracer(ctx context.Context, pgURL string) (*sql.DB, error) {
+ pgxConfig, err := pgx.ParseConfig(pgURL)
+ if err != nil {
+ return nil, errors.Wrap(err, "failed to parse database URL")
+ }
+
+ pgxConfig.Tracer = &metadataDBTracer{}
+ db := stdlib.OpenDB(*pgxConfig)
+```
+
+to:
+
+```go
+func createConnectionWithTracer(ctx context.Context, pgURL string) (*sql.DB, error) {
+ cleanURL, authConfig, err := parseMetadataDBAuthConfig(pgURL)
+ if err != nil {
+ return nil, err
+ }
+
+ pgxConfig, err := pgx.ParseConfig(cleanURL)
+ if err != nil {
+ return nil, errors.Wrap(err, "failed to parse database URL")
+ }
+
+ pgxConfig.Tracer = &metadataDBTracer{}
+ var tokenProvider metadataDBTokenProvider
+ if authConfig != nil && authConfig.enabled {
+ tokenProvider, err = newAWSMetadataDBTokenProvider(ctx, authConfig.region)
+ if err != nil {
+ return nil, err
+ }
+ }
+ db := stdlib.OpenDB(*pgxConfig, metadataDBOpenOptions(authConfig, tokenProvider)...)
+```
+
+- [ ] **Step 5: Run focused store tests**
+
+Run:
+
+```bash
+go test -v -count=1 ./backend/store -run '^(TestParseMetadataDBAuthConfig|TestNewMetadataDBBeforeConnect|TestMetadataDBOpenOptions)'
+```
+
+Expected: PASS.
+
+- [ ] **Step 6: Commit connection wiring**
+
+Run:
+
+```bash
+gofmt -w backend/store/db_connection.go backend/store/metadata_db_auth.go backend/store/metadata_db_auth_test.go
+git add backend/store/db_connection.go backend/store/metadata_db_auth.go backend/store/metadata_db_auth_test.go
+git commit -m "feat(store): enable AWS IAM auth for metadata DB connections"
+```
+
+## Task 4: Add Helm Values and Rendering
+
+**Files:**
+- Modify: `helm-charts/bytebase/values.yaml`
+- Modify: `helm-charts/bytebase/templates/statefulset.yaml`
+- Modify: `helm-charts/bytebase/README.md`
+
+- [ ] **Step 1: Add default Helm values**
+
+Modify `helm-charts/bytebase/values.yaml` under `bytebase.option.externalPg`:
+
+```yaml
+ awsRdsIam:
+ enabled: false
+ region: ""
+```
+
+- [ ] **Step 2: Add template variables**
+
+Modify the variable block near the top of `helm-charts/bytebase/templates/statefulset.yaml` by adding:
+
+```gotemplate
+{{- $externalPgAWSRDSIAMEnabled := .Values.bytebase.option.externalPg.awsRdsIam.enabled -}}
+{{- $externalPgAWSRDSIAMRegion := .Values.bytebase.option.externalPg.awsRdsIam.region -}}
+```
+
+- [ ] **Step 3: Render passwordless IAM `PG_URL` for direct externalPg fields**
+
+Modify the constructed `PG_URL` branch in `helm-charts/bytebase/templates/statefulset.yaml` so the `{{- else }}` branch after `{{- else if $externalPgURL }}` starts with an IAM branch:
+
+```gotemplate
+ {{- if $externalPgAWSRDSIAMEnabled }}
+ - name: PG_URL
+ value: postgres://{{ $externalPgUsername }}@{{ $externalPgHost }}:{{ $externalPgPort }}/{{ $externalPgDatabase }}?sslmode=verify-full&bytebase_aws_rds_iam=true&bytebase_aws_region={{ required "bytebase.option.externalPg.awsRdsIam.region is required when bytebase.option.externalPg.awsRdsIam.enabled is true" $externalPgAWSRDSIAMRegion }}
+ {{- else if and $externalPgExistingPgPasswordSecret (not $externalPgEscapePgPassword) }}
+```
+
+Keep the existing password-secret and password branches under the new `else if`.
+
+- [ ] **Step 4: Disable escaped-password init when IAM auth is enabled**
+
+Change both `if $externalPgEscapePgPassword` template guards in `helm-charts/bytebase/templates/statefulset.yaml` to:
+
+```gotemplate
+{{- if and $externalPgEscapePgPassword (not $externalPgAWSRDSIAMEnabled) }}
+```
+
+This affects the init container block and the shell `export PG_URL=...` block. IAM auth does not use a password, so it must not run the password-escaping path.
+
+- [ ] **Step 5: Document Helm values**
+
+Add these rows to the parameters table in `helm-charts/bytebase/README.md` after `bytebase.option.externalPg.escapePassword`:
+
+```markdown
+| `bytebase.option.externalPg.awsRdsIam.enabled` | Enables AWS RDS IAM authentication for the Bytebase metadata PostgreSQL database when the chart constructs `PG_URL` from externalPg fields, including `sslmode=verify-full`. | false |
+| `bytebase.option.externalPg.awsRdsIam.region` | AWS region used to sign RDS IAM authentication tokens for the Bytebase metadata PostgreSQL database. Required when `awsRdsIam.enabled` is true. | "" |
+```
+
+- [ ] **Step 6: Render chart with IAM auth enabled**
+
+Run:
+
+```bash
+helm template bytebase-release helm-charts/bytebase \
+ --set bytebase.option.externalPg.pgHost=example.us-east-1.rds.amazonaws.com \
+ --set bytebase.option.externalPg.pgPort=5432 \
+ --set bytebase.option.externalPg.pgUsername=bb_meta \
+ --set bytebase.option.externalPg.pgPassword=unused \
+ --set bytebase.option.externalPg.pgDatabase=bytebase \
+ --set bytebase.option.externalPg.awsRdsIam.enabled=true \
+ --set bytebase.option.externalPg.awsRdsIam.region=us-east-1 \
+ | rg 'PG_URL|bytebase_aws_rds_iam|PG_PASSWORD|init-container'
+```
+
+Expected output includes:
+
+```text
+- name: PG_URL
+value: postgres://[email protected]:5432/bytebase?sslmode=verify-full&bytebase_aws_rds_iam=true&bytebase_aws_region=us-east-1
+```
+
+Expected output does not include `PG_PASSWORD` or `init-container`.
+
+- [ ] **Step 7: Render chart with IAM auth enabled and missing region**
+
+Run:
+
+```bash
+helm template bytebase-release helm-charts/bytebase \
+ --set bytebase.option.externalPg.pgHost=example.us-east-1.rds.amazonaws.com \
+ --set bytebase.option.externalPg.pgPort=5432 \
+ --set bytebase.option.externalPg.pgUsername=bb_meta \
+ --set bytebase.option.externalPg.pgDatabase=bytebase \
+ --set bytebase.option.externalPg.awsRdsIam.enabled=true
+```
+
+Expected: FAIL with `bytebase.option.externalPg.awsRdsIam.region is required when bytebase.option.externalPg.awsRdsIam.enabled is true`.
+
+- [ ] **Step 8: Render chart with IAM auth disabled**
+
+Run:
+
+```bash
+helm template bytebase-release helm-charts/bytebase \
+ --set bytebase.option.externalPg.pgHost=example.us-east-1.rds.amazonaws.com \
+ --set bytebase.option.externalPg.pgPort=5432 \
+ --set bytebase.option.externalPg.pgUsername=bb_meta \
+ --set bytebase.option.externalPg.pgPassword=secret \
+ --set bytebase.option.externalPg.pgDatabase=bytebase \
+ | rg 'PG_URL|bytebase_aws_rds_iam'
+```
+
+Expected output includes:
+
+```text
+value: postgres://bb_meta:[email protected]:5432/bytebase
+```
+
+Expected output does not include `bytebase_aws_rds_iam`.
+
+- [ ] **Step 9: Commit Helm changes**
+
+Run:
+
+```bash
+git add helm-charts/bytebase/values.yaml helm-charts/bytebase/templates/statefulset.yaml helm-charts/bytebase/README.md
+git commit -m "feat(helm): render metadata DB AWS IAM PG_URL"
+```
+
+## Task 5: Add Operator Documentation
+
+**Files:**
+- Modify: `docs/operations/high-availability.md`
+
+- [ ] **Step 1: Add metadata DB IAM note**
+
+Add this section near the external PostgreSQL requirement in `docs/operations/high-availability.md`:
+
+````markdown
+### AWS RDS IAM authentication for metadata PostgreSQL
+
+When the shared metadata PostgreSQL database is AWS RDS or Aurora PostgreSQL, every Bytebase replica can use the same IAM-enabled `PG_URL` shape:
+
+```text
+postgres://[email protected]:5432/bytebase?sslmode=verify-full&bytebase_aws_rds_iam=true&bytebase_aws_region=us-east-1
+```
+
+The PostgreSQL user must be granted `rds_iam`, and the AWS principal used by each Bytebase process must have `rds-db:connect` for that database user. Use `sslmode=verify-full` with a trust store that validates the RDS certificate. Do not put AWS access keys in `PG_URL`; use the standard AWS SDK credential chain through the runtime environment, such as EKS IRSA, ECS task roles, EC2 instance profiles, environment variables, or shared AWS config.
+````
+
+- [ ] **Step 2: Run docs diff review**
+
+Run:
+
+```bash
+git diff -- docs/operations/high-availability.md
+```
+
+Expected: The diff contains only the RDS IAM metadata database note.
+
+- [ ] **Step 3: Commit docs**
+
+Run:
+
+```bash
+git add docs/operations/high-availability.md
+git commit -m "docs: describe metadata DB AWS IAM setup"
+```
+
+## Task 6: Final Verification
+
+**Files:**
+- Verify all changed files from Tasks 1 through 5.
+
+- [ ] **Step 1: Run focused Go tests**
+
+Run:
+
+```bash
+go test -v -count=1 ./backend/store -run '^(TestParseMetadataDBAuthConfig|TestNewMetadataDBBeforeConnect|TestMetadataDBOpenOptions)'
+```
+
+Expected: PASS.
+
+- [ ] **Step 2: Run Go formatting**
+
+Run:
+
+```bash
+gofmt -w backend/store/db_connection.go backend/store/metadata_db_auth.go backend/store/metadata_db_auth_test.go
+git diff --check
+```
+
+Expected: `git diff --check` exits 0.
+
+- [ ] **Step 3: Run backend lint**
+
+Run:
+
+```bash
+golangci-lint run --allow-parallel-runners
+```
+
+Expected: PASS. If it reports issues in files changed by this plan, fix them and rerun the command until it exits 0.
+
+- [ ] **Step 4: Run backend build**
+
+Run:
+
+```bash
+go build -ldflags "-w -s" -p=16 -o ./bytebase-build/bytebase ./backend/bin/server/main.go
+```
+
+Expected: PASS and produces `./bytebase-build/bytebase`.
+
+- [ ] **Step 5: Render Helm IAM configuration**
+
+Run:
+
+```bash
+helm template bytebase-release helm-charts/bytebase \
+ --set bytebase.option.externalPg.pgHost=example.us-east-1.rds.amazonaws.com \
+ --set bytebase.option.externalPg.pgPort=5432 \
+ --set bytebase.option.externalPg.pgUsername=bb_meta \
+ --set bytebase.option.externalPg.pgDatabase=bytebase \
+ --set bytebase.option.externalPg.awsRdsIam.enabled=true \
+ --set bytebase.option.externalPg.awsRdsIam.region=us-east-1 \
+ >/tmp/bytebase-iam-rendered.yaml
+
+rg 'postgres://[email protected]:5432/bytebase\\?sslmode=verify-full&bytebase_aws_rds_iam=true&bytebase_aws_region=us-east-1' /tmp/bytebase-iam-rendered.yaml
+```
+
+Expected: `rg` finds exactly the rendered IAM `PG_URL`.
+
+- [ ] **Step 6: Render Helm default password configuration**
+
+Run:
+
+```bash
+helm template bytebase-release helm-charts/bytebase \
+ --set bytebase.option.externalPg.pgHost=example.us-east-1.rds.amazonaws.com \
+ --set bytebase.option.externalPg.pgPort=5432 \
+ --set bytebase.option.externalPg.pgUsername=bb_meta \
+ --set bytebase.option.externalPg.pgPassword=secret \
+ --set bytebase.option.externalPg.pgDatabase=bytebase \
+ >/tmp/bytebase-password-rendered.yaml
+
+rg 'postgres://bb_meta:[email protected]:5432/bytebase' /tmp/bytebase-password-rendered.yaml
+```
+
+Expected: `rg` finds the existing password-style `PG_URL`.
+
+- [ ] **Step 7: Review accumulated diff**
+
+Run:
+
+```bash
+git diff origin/main...HEAD -- backend/store helm-charts/bytebase docs/operations/high-availability.md
+```
+
+Expected: The diff is limited to metadata DB IAM auth, Helm rendering, and operator docs.
+
+- [ ] **Step 8: Final commit if verification required fixes**
+
+If Steps 1 through 7 required fixes after the Task 5 commit, run:
+
+```bash
+git add backend/store helm-charts/bytebase docs/operations/high-availability.md
+git commit -m "fix: complete metadata DB AWS IAM verification fixes"
+```
+
+Expected: a commit is created only when verification changed files.
diff --git a/docs/superpowers/specs/2026-04-29-aws-rds-iam-metadata-db-design.md b/docs/superpowers/specs/2026-04-29-aws-rds-iam-metadata-db-design.md
new file mode 100644
index 0000000000..726158b184
--- /dev/null
+++ b/docs/superpowers/specs/2026-04-29-aws-rds-iam-metadata-db-design.md
@@ -0,0 +1,154 @@
+# AWS RDS IAM Auth for Metadata Database
+
+Status: Draft for peer review
+
+Issue: [BYT-9073](https://linear.app/bytebase/issue/BYT-9073/aws-rds-iam-auth-for-bytebase-metadata-database)
+
+Date: 2026-04-29
+
+## Background
+
+BYT-9073 asks Bytebase to support AWS RDS IAM authentication for Bytebase's own metadata PostgreSQL database. The issue has no additional requirements or comments, so this design scopes the work to self-hosted Bytebase deployments that use external PostgreSQL as metadata storage.
+
+The current metadata database connection path is `backend/store/db_connection.go`. `DBConnectionManager` accepts `PG_URL` or a file path containing `PG_URL`, parses the final value with `pgx.ParseConfig`, opens a `database/sql` pool through pgx stdlib, pings it, and configures max open connections from PostgreSQL server settings.
+
+Bytebase already supports AWS RDS IAM auth for user-managed PostgreSQL instances in `backend/plugin/db/pg/pg.go`. That path uses `github.com/aws/aws-sdk-go-v2/feature/rds/auth.BuildAuthToken` plus existing AWS credential helpers. The metadata database path cannot directly reuse that datasource flow today because it receives only `PG_URL`, not a stored datasource protobuf.
+
+AWS RDS IAM tokens are generated with AWS Signature Version 4, are valid for 15 minutes, and are used to authenticate a new database session. Existing database sessions are not invalidated when the token expires. For PostgreSQL, when a user has the `rds_iam` role, IAM authentication takes precedence over password authentication.
+
+Standard implementations in other products follow the same general model: AWS credentials are configured separately from the PostgreSQL password, and the driver or product generates an RDS IAM token when opening a database connection. The AWS Advanced JDBC Wrapper exposes this as an IAM authentication plugin. Tools such as StrongDM, DBeaver, and DataGrip model AWS credentials separately from the PostgreSQL connection target.
+
+## Goals
+
+- Allow Bytebase to run against an AWS RDS or Aurora PostgreSQL metadata database without storing a static database password.
+- Generate a valid IAM auth token for every new physical metadata database connection, including connections opened after the process has been running longer than 15 minutes.
+- Keep existing `PG_URL` deployments backward compatible, including password-based `PG_URL`, file-based `PG_URL` rotation, and embedded local PostgreSQL.
+- Use the AWS SDK default credential chain so EC2 instance profiles, ECS task roles, EKS IRSA, environment variables, shared config, and AWS profiles work according to standard SDK behavior.
+- Keep the implementation isolated to metadata database connection setup, Helm configuration, and deployment documentation.
+
+## Non-goals
+
+- Do not add a UI workflow. This is a server startup and operator configuration feature.
+- Do not provision AWS resources, RDS users, IAM policies, database grants, RDS Proxy, or Secrets Manager resources.
+- Do not store AWS access keys in Bytebase-specific `PG_URL` parameters.
+- Do not require RDS Proxy or Secrets Manager for the primary path.
+- Do not change Bytebase's managed database instance connection model.
+
+## Design
+
+Implement native metadata database IAM authentication in `backend/store`. Bytebase should generate an AWS RDS auth token whenever the metadata connection pool opens a new physical PostgreSQL connection. This keeps the operator-facing `PG_URL` model, avoids storing a static database password, and matches the way AWS-supported drivers and database tools handle RDS IAM auth.
+
+Operators enable IAM auth through reserved Bytebase parameters in `PG_URL`:
+
+```text
+postgres://[email protected]:5432/bytebase?sslmode=verify-full&bytebase_aws_rds_iam=true&bytebase_aws_region=us-east-1
+```
+
+The initial version supports these parameters:
+
+- `bytebase_aws_rds_iam=true`: enables metadata database IAM auth.
+- `bytebase_aws_region=<region>`: sets the AWS region used to sign the RDS auth token.
+
+`bytebase_aws_region` is required in v1. Region derivation from RDS endpoint hostnames can be considered later, but requiring the region avoids surprising behavior with custom endpoints, Aurora endpoints, and future proxy setups.
+
+Bytebase reads the `bytebase_aws_*` parameters from pgx's parsed runtime parameters and deletes them before opening the database, so they are not sent as PostgreSQL startup parameters. When IAM auth is enabled, Bytebase must require verified TLS so the generated auth token is sent only over a verified connection. When `bytebase_aws_rds_iam` is absent or false, existing behavior is unchanged.
+
+The existing `PG_URL` file watcher remains available as a generic credential rotation mechanism, but it should not be the recommended RDS IAM path. An external token refresher pushes correctness to another process and swaps the whole `sql.DB` pool whenever the file changes. Native per-connection token generation is simpler for operators and better aligned with database pooling.
+
+For the Helm chart, add optional values that render the same `PG_URL` shape without a password:
+
+```yaml
+bytebase:
+ option:
+ externalPg:
+ awsRdsIam:
+ enabled: true
+ region: us-east-1
+```
+
+When `awsRdsIam.enabled` is true, the chart should render `PG_URL` with the username, host, port, database, `bytebase_aws_rds_iam=true`, and `bytebase_aws_region=<region>`, but without a password. The existing `serviceAccount.annotations` value is sufficient for EKS IRSA. Users of `existingPgURLSecret` can include the Bytebase query parameters directly in the secret.
+
+The security model is the standard RDS IAM model:
+
+- The PostgreSQL user must exist and be granted `rds_iam`.
+- The AWS principal used by the Bytebase process must have `rds-db:connect` permission for the database resource and user.
+- IAM auth requires verified TLS, such as `sslmode=verify-full`, with an AWS RDS CA bundle or platform trust store that validates the RDS certificate.
+- No generated token should be persisted to disk, exported to logs, stored in settings, or exposed through metrics labels.
+
+## Implementation design
+
+Add a small private metadata database auth layer in `backend/store`.
+
+Define a metadata auth extractor that runs after `pgx.ParseConfig`:
+
+- it reads `bytebase_aws_rds_iam` and `bytebase_aws_region` from `pgxConfig.RuntimeParams`
+- it deletes those Bytebase parameters from `RuntimeParams` so they are not sent to PostgreSQL
+- it returns a metadata auth config used by Bytebase before opening the pool
+
+Because pgx handles the connection string parsing after Bytebase classifies the input as a direct connection string, IAM auth works with URI-style values and compact keyword/value `PG_URL` values such as `host=... port=...`. Bytebase should reject pgx fallback configs while IAM is enabled because the generated token is scoped to one host:port endpoint.
+
+The metadata auth config should contain:
+
+- whether IAM auth is enabled
+- AWS region
+- host and port used to build the token endpoint
+- database username
+
+Define a token provider interface so tests can inject a fake token builder. The production provider loads AWS config once during metadata DB pool creation with `config.LoadDefaultConfig(ctx, config.WithRegion(region))`, stores the resulting credential provider, and calls `auth.BuildAuthToken(ctx, hostPort, region, user, credentials)` from the `BeforeConnect` hook.
+
+In `createConnectionWithTracer`, call `pgx.ParseConfig`, extract and validate the metadata auth config, then open the pool with:
+
+```go
+stdlib.OpenDB(*pgxConfig, stdlib.OptionBeforeConnect(...))
+```
+
+The `BeforeConnect` hook should generate a token, assign it to `connConfig.Password`, and return any generation error. This makes token generation happen exactly when pgx opens a new physical connection.
+
+Keep the existing `metadataDBTracer` behavior, startup ping, and `max_connections` probing. These operations will use the hook during initial connection creation.
+
+Do not set `ConnMaxLifetime` to 15 minutes. Token expiration does not terminate established sessions, and forced churn would increase token generation pressure without improving correctness.
+
+Startup should fail with a clear message when IAM auth is enabled but region, verified TLS, host, port, or user is missing, or when pgx parsed fallback configs are present. Token-generation errors should include enough context to identify the endpoint, region, and user, but must not include the generated token or a full secret-bearing `PG_URL`. If PostgreSQL rejects the token, Bytebase should surface the database ping or connection error normally.
+
+Testing should cover:
+
+- `PG_URL` parsing and Bytebase query-parameter stripping
+- non-IAM `PG_URL` compatibility
+- required field validation for region, verified TLS, user, host, port, and unsupported fallback configs
+- `BeforeConnect` behavior with a fake token provider
+- token-generation error propagation
+- Helm rendering when `awsRdsIam.enabled` is true
+- Helm rendering compatibility when IAM auth is disabled
+
+A manual integration test should create an RDS or Aurora PostgreSQL user, grant `rds_iam`, attach an IAM role with `rds-db:connect`, start Bytebase with the IAM `PG_URL`, confirm migrations run, leave the process running past 15 minutes, and force new pool connections to verify fresh token generation.
+
+## Appendix
+
+### Alternatives considered
+
+Native pgx `BeforeConnect` hook is the recommended approach. The token is generated exactly when a new physical connection is created. It fits `database/sql` pooling, avoids whole-pool swaps, and keeps the auth behavior local to the metadata connection layer.
+
+External token generator plus `PG_URL` file watcher can work with the existing file-watcher behavior, but it pushes correctness to an external process. It also swaps the whole `sql.DB` pool whenever the file changes, which is heavier than refreshing auth only for new connections.
+
+Separate typed metadata database config fields may be useful if metadata database configuration grows beyond `PG_URL`, but it is larger than needed for v1. Bytebase already centers metadata database setup on `PG_URL`, and reserved query parameters keep the initial surface small.
+
+RDS Proxy and Secrets Manager can solve adjacent operational problems, but they either still need client-side IAM auth or introduce a different credential-management system. They should remain compatible, not required.
+
+### Rollout and compatibility
+
+This change is additive. Existing `PG_URL` deployments continue using static password auth or file-based rotation. No database migration is required. No frontend change is required. Helm changes should be backward compatible and only alter `PG_URL` rendering when `awsRdsIam.enabled` is true.
+
+### Open questions for review
+
+- Should v1 support explicit assume-role parameters for the metadata database, or should operators rely on the AWS SDK default chain and platform role configuration first?
+- Should a later version derive `bytebase_aws_region` from standard RDS endpoint hostnames and allow the parameter as an override?
+- Should RDS Proxy with IAM client authentication be listed as supported in v1, or treated as best-effort until tested?
+
+### Source links
+
+- [AWS RDS IAM database authentication](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html)
+- [AWS SDK for Go v2 RDS utilities](https://docs.aws.amazon.com/sdk-for-go/v2/developer-guide/sdk-utilities-rds.html)
+- [AWS Advanced JDBC IAM authentication plugin](https://github.com/aws/aws-advanced-jdbc-wrapper/blob/main/docs/using-the-jdbc-driver/using-plugins/UsingTheIamAuthenticationPlugin.md)
+- [StrongDM RDS PostgreSQL IAM datasource](https://docs.strongdm.com/admin/resources/datasources/rds-postgresql-iam)
+- [DBeaver AWS credentials](https://dbeaver.com/docs/dbeaver/AWS-Credentials/)
+- [DataGrip AWS cloud connections](https://www.jetbrains.com/help/datagrip/clouds-aws.html)
diff --git a/helm-charts/bytebase/README.md b/helm-charts/bytebase/README.md
index bcdc13fe58..01a08af63d 100644
--- a/helm-charts/bytebase/README.md
+++ b/helm-charts/bytebase/README.md
@@ -103,6 +103,8 @@ upgrade bytebase-release bytebase-repo/bytebase
| `bytebase.option.externalPg.existingPgPasswordSecret` | The name of Secret that stores the existing PostgreSQL password for Bytebase metadata storage. | "" |
| `bytebase.option.externalPg.existingPgPasswordSecretKey` | The key of Secret storing the existing PostgreSQL password. Should be used with `bytebase.option.externalPg.existingPgPasswordSecret`. | "" |
| `bytebase.option.externalPg.escapePassword` | Controls whether to escape the password in the connection string. `bytebase.option.externalPg.existingPgPasswordSecret` or `bytebase.option.externalPg.pgPassword` should be specified with this value together. **Experimental feature.** | false |
+| `bytebase.option.externalPg.awsRdsIam.enabled` | Enables AWS RDS IAM authentication for the Bytebase metadata PostgreSQL database when the chart constructs PG_URL from externalPg fields, including `sslmode=verify-full`. | false |
+| `bytebase.option.externalPg.awsRdsIam.region` | AWS region used to sign RDS IAM authentication tokens for the Bytebase metadata PostgreSQL database. Required when awsRdsIam.enabled is true. | "" |
| `bytebase.persistence.enabled` | Enable/disable persistence for Bytebase. | false |
| `bytebase.persistence.existingClaim` | Name of the existing PersistentVolumeClaim for Bytebase persistence. | "" |
| `bytebase.persistence.storage` | Size of the persistent volume for Bytebase data. | "2Gi" |
diff --git a/helm-charts/bytebase/templates/statefulset.yaml b/helm-charts/bytebase/templates/statefulset.yaml
index 2e4c62e51f..8375e99a87 100644
--- a/helm-charts/bytebase/templates/statefulset.yaml
+++ b/helm-charts/bytebase/templates/statefulset.yaml
@@ -19,7 +19,9 @@
{{- $externalPgDatabase := .Values.bytebase.option.externalPg.pgDatabase | default "database" -}}
{{- $externalPgExistingPgPasswordSecret := .Values.bytebase.option.externalPg.existingPgPasswordSecret -}}
{{- $externalPgExistingPgPasswordSecretKey := .Values.bytebase.option.externalPg.existingPgPasswordSecretKey -}}
-{{- $externalPgEscapePgPassword := .Values.bytebase.option.externalPg.escapePassword }}
+{{- $externalPgEscapePgPassword := .Values.bytebase.option.externalPg.escapePassword -}}
+{{- $externalPgAWSRDSIAMEnabled := .Values.bytebase.option.externalPg.awsRdsIam.enabled -}}
+{{- $externalPgAWSRDSIAMRegion := .Values.bytebase.option.externalPg.awsRdsIam.region -}}
# bytbease.persistence
{{- $persistenceEnable := .Values.bytebase.persistence.enabled -}}
{{- $persistenceExistingClaim := .Values.bytebase.persistence.existingClaim -}}
@@ -47,7 +49,7 @@ spec:
app: bytebase
spec:
serviceAccountName: {{ template "bytebase.serviceAccountName" . }}
- {{- if $externalPgEscapePgPassword }}
+ {{- if and $externalPgEscapePgPassword (not $externalPgAWSRDSIAMEnabled) }}
# If user specify the externalPgEscapePgPassword, we should escape the password in the PG_URL in the shell,
# because the password may comes from a secret, which is invisible in helm.
# Hence, we do the escaping in the initialization container, and write the escaped password to the shared volume.
@@ -158,7 +160,10 @@ spec:
value: {{ $externalPgURL }}
{{- else }}
# Otherwise, we should construct the external pg connection string from the specified parameters.
- {{- if and $externalPgExistingPgPasswordSecret (not $externalPgEscapePgPassword) }}
+ {{- if $externalPgAWSRDSIAMEnabled }}
+ - name: PG_URL
+ value: postgres://{{ $externalPgUsername }}@{{ $externalPgHost }}:{{ $externalPgPort }}/{{ $externalPgDatabase }}?sslmode=verify-full&bytebase_aws_rds_iam=true&bytebase_aws_region={{ required "bytebase.option.externalPg.awsRdsIam.region is required when bytebase.option.externalPg.awsRdsIam.enabled is true" $externalPgAWSRDSIAMRegion }}
+ {{- else if and $externalPgExistingPgPasswordSecret (not $externalPgEscapePgPassword) }}
# If user specifies an existing secret, we should read the external pg password in that secret.
- name: PG_PASSWORD
valueFrom:
@@ -177,7 +182,7 @@ spec:
- -c
args:
- |
- {{- if $externalPgEscapePgPassword }}
+ {{- if and $externalPgEscapePgPassword (not $externalPgAWSRDSIAMEnabled) }}
# If user escape the password, we should read the escaped password from the shared volume, and construct the PG_PASSWORD.
export PG_URL=postgres://{{ $externalPgUsername }}:$(cat /mnt/bytebase-shared-volume/pg_escaped_password)@{{ $externalPgHost }}:{{ $externalPgPort }}/{{ $externalPgDatabase }}
{{- end }}
@@ -265,4 +270,4 @@ spec:
resources:
requests:
storage: {{ $persistenceStorage }}
-{{- end }}
\ No newline at end of file
+{{- end }}
diff --git a/helm-charts/bytebase/values.yaml b/helm-charts/bytebase/values.yaml
index 343f8f9218..605177e6b0 100644
--- a/helm-charts/bytebase/values.yaml
+++ b/helm-charts/bytebase/values.yaml
@@ -40,6 +40,9 @@ bytebase:
# It's only be applied in pgPassword or existingPgPasswordSecret.
# NOTE: This is an experimental feature and it may be removed in the future without any notice!!!
escapePassword: false
+ awsRdsIam:
+ enabled: false
+ region: ""
persistence:
enabled: false
existingClaim: ""