Database governance built for humans and agents — controlling changes and access across every major database.
Go cicddata-governancedata-maskingdata-securitydatabase-accessdatabase-governancedevopsdevsecopsflywaygitopsliquibasemongodbmysqloraclepostgresqlschema-migrationssecuritysql-clientsqlservertidb
refactor(store): move metadata DB auth to dbauth package (#20203)
p0nya93a2bcac3ea
diff --git a/backend/store/db_connection.go b/backend/store/db_connection.goindex d96aaddf9b..013f5e44aa 100644--- a/backend/store/db_connection.go+++ b/backend/store/db_connection.go@@ -15,6 +15,7 @@ import ("github.com/pkg/errors""github.com/bytebase/bytebase/backend/common/qb"+ "github.com/bytebase/bytebase/backend/store/dbauth")// DBConnectionManager manages database connections with support for dynamic updates.@@ -216,10 +217,12 @@ func isKeywordValuePGURL(s string) bool {"service","servicefile","target_session_attrs",- "application_name",- metadataDBAWSRDSIAMParam,- metadataDBAWSRegionParam:+ "application_name":return true+ default:+ if dbauth.IsKeywordValueRuntimeParam(field[:eqIdx]) {+ return true+ }}}return false@@ -239,20 +242,13 @@ func createConnectionWithTracer(ctx context.Context, pgURL string) (*sql.DB, errreturn nil, errors.Wrap(err, "failed to parse database URL")}- authConfig, err := metadataDBAuthConfigFromPGXConfig(pgxConfig)+ openOptions, err := dbauth.Configure(ctx, pgxConfig)if err != nil {return nil, err}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)...)+ db := stdlib.OpenDB(*pgxConfig, openOptions...)// Validate connectionif err := db.PingContext(ctx); err != nil {diff --git a/backend/store/dbauth/auth.go b/backend/store/dbauth/auth.gonew file mode 100644index 0000000000..8e4f7a83fd--- /dev/null+++ b/backend/store/dbauth/auth.go@@ -0,0 +1,35 @@+package dbauth++import (+ "context"++ "github.com/jackc/pgx/v5"+ "github.com/jackc/pgx/v5/stdlib"+)++// Configure applies metadata database authentication settings to pgxConfig.+func Configure(ctx context.Context, pgxConfig *pgx.ConnConfig) ([]stdlib.OptionOpenDB, error) {+ authConfig, err := awsConfigFromPGXConfig(pgxConfig)+ if err != nil {+ return nil, err+ }+ if authConfig == nil || !authConfig.enabled {+ return nil, nil+ }++ tokenProvider, err := newAWSMetadataDBTokenProvider(ctx, authConfig.region)+ if err != nil {+ return nil, err+ }+ return awsOpenOptions(authConfig, tokenProvider), nil+}++// IsKeywordValueRuntimeParam reports whether key is a Bytebase metadata DB auth runtime parameter.+func IsKeywordValueRuntimeParam(key string) bool {+ switch key {+ case awsRDSIAMParam, awsRegionParam:+ return true+ default:+ return false+ }+}diff --git a/backend/store/metadata_db_auth.go b/backend/store/dbauth/aws.gosimilarity index 72%rename from backend/store/metadata_db_auth.gorename to backend/store/dbauth/aws.goindex 767c42f715..1314299c91 100644--- a/backend/store/metadata_db_auth.go+++ b/backend/store/dbauth/aws.go@@ -1,4 +1,4 @@-package store+package dbauthimport ("context"@@ -14,18 +14,18 @@ import ()const (- metadataDBAWSRDSIAMParam = "bytebase_aws_rds_iam"- metadataDBAWSRegionParam = "bytebase_aws_region"+ awsRDSIAMParam = "bytebase_aws_rds_iam"+ awsRegionParam = "bytebase_aws_region")-type metadataDBAuthConfig struct {+type awsConfig struct {enabled boolregion stringendpoint stringuser string}-type metadataDBTokenProvider interface {+type awsTokenProvider interface {BuildAuthToken(ctx context.Context, endpoint, region, user string) (string, error)}@@ -52,18 +52,18 @@ func (p *awsMetadataDBTokenProvider) BuildAuthToken(ctx context.Context, endpoinreturn 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)+func awsConfigFromPGXConfig(pgxConfig *pgx.ConnConfig) (*awsConfig, error) {+ iamEnabled := pgxConfig.RuntimeParams[awsRDSIAMParam] == "true"+ region := pgxConfig.RuntimeParams[awsRegionParam]+ delete(pgxConfig.RuntimeParams, awsRDSIAMParam)+ delete(pgxConfig.RuntimeParams, awsRegionParam)if !iamEnabled {return nil, nil}if region == "" {- return nil, errors.Errorf("%s is required when metadata database AWS RDS IAM auth is enabled", metadataDBAWSRegionParam)+ return nil, errors.Errorf("%s is required when metadata database AWS RDS IAM auth is enabled", awsRegionParam)}if pgxConfig.User == "" {@@ -86,7 +86,7 @@ func metadataDBAuthConfigFromPGXConfig(pgxConfig *pgx.ConnConfig) (*metadataDBAureturn nil, errors.New("verified TLS is required when metadata database AWS RDS IAM auth is enabled")}- return &metadataDBAuthConfig{+ return &awsConfig{enabled: true,region: region,endpoint: net.JoinHostPort(pgxConfig.Host, strconv.FormatUint(uint64(pgxConfig.Port), 10)),@@ -94,7 +94,7 @@ func metadataDBAuthConfigFromPGXConfig(pgxConfig *pgx.ConnConfig) (*metadataDBAu}, nil}-func newMetadataDBBeforeConnect(authConfig *metadataDBAuthConfig, tokenProvider metadataDBTokenProvider) func(context.Context, *pgx.ConnConfig) error {+func newAWSBeforeConnect(authConfig *awsConfig, tokenProvider awsTokenProvider) 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 {@@ -105,9 +105,9 @@ func newMetadataDBBeforeConnect(authConfig *metadataDBAuthConfig, tokenProvider}}-func metadataDBOpenOptions(authConfig *metadataDBAuthConfig, tokenProvider metadataDBTokenProvider) []stdlib.OptionOpenDB {+func awsOpenOptions(authConfig *awsConfig, tokenProvider awsTokenProvider) []stdlib.OptionOpenDB {if authConfig == nil || !authConfig.enabled {return nil}- return []stdlib.OptionOpenDB{stdlib.OptionBeforeConnect(newMetadataDBBeforeConnect(authConfig, tokenProvider))}+ return []stdlib.OptionOpenDB{stdlib.OptionBeforeConnect(newAWSBeforeConnect(authConfig, tokenProvider))}}diff --git a/backend/store/dbauth/aws_test.go b/backend/store/dbauth/aws_test.gonew file mode 100644index 0000000000..2279d92c61--- /dev/null+++ b/backend/store/dbauth/aws_test.go@@ -0,0 +1,263 @@+package dbauth++import (+ "context"+ "errors"+ "testing"++ "github.com/jackc/pgx/v5"+ "github.com/stretchr/testify/require"+)++type contextKey struct{}++type fakeTokenProvider struct {+ token string+ err error+ calls []fakeTokenProviderCall+}++type fakeTokenProviderCall struct {+ ctx context.Context+ endpoint string+ region string+ user string+}++func (p *fakeTokenProvider) BuildAuthToken(ctx context.Context, endpoint, region, user string) (string, error) {+ p.calls = append(p.calls, fakeTokenProviderCall{+ ctx: ctx,+ endpoint: endpoint,+ region: region,+ user: user,+ })+ return p.token, p.err+}++func TestAWSConfigFromPGXConfigDisabled(t *testing.T) {+ pgxConfig := mustParsePGXConfig(t, "postgres://bb:[email protected]:5432/bytebase?sslmode=verify-full")++ authConfig, err := awsConfigFromPGXConfig(pgxConfig)++ require.NoError(t, err)+ require.Nil(t, authConfig)+}++func TestAWSConfigFromPGXConfigEnabledURL(t *testing.T) {+ pgxConfig := mustParsePGXConfig(t, "postgres://[email protected]:5432/bytebase?sslmode=verify-full&bytebase_aws_rds_iam=true&bytebase_aws_region=us-east-1")++ authConfig, err := awsConfigFromPGXConfig(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, awsRDSIAMParam)+ require.NotContains(t, pgxConfig.RuntimeParams, awsRegionParam)+}++func TestAWSConfigFromPGXConfigEnabledKeywordValue(t *testing.T) {+ pgxConfig := mustParsePGXConfig(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 := awsConfigFromPGXConfig(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, awsRDSIAMParam)+ require.NotContains(t, pgxConfig.RuntimeParams, awsRegionParam)+}++func TestAWSConfigFromPGXConfigStripsDisabledParams(t *testing.T) {+ pgxConfig := mustParsePGXConfig(t, "postgres://bb:[email protected]:5432/bytebase?bytebase_aws_rds_iam=false&bytebase_aws_region=us-east-1&sslmode=verify-full")++ authConfig, err := awsConfigFromPGXConfig(pgxConfig)++ require.NoError(t, err)+ require.Nil(t, authConfig)+ require.NotContains(t, pgxConfig.RuntimeParams, awsRDSIAMParam)+ require.NotContains(t, pgxConfig.RuntimeParams, awsRegionParam)+}++func TestAWSConfigFromPGXConfigRequiresFields(t *testing.T) {+ tests := []struct {+ name string+ configure func(*pgx.ConnConfig)+ wantErr string+ }{+ {+ name: "region",+ configure: func(config *pgx.ConnConfig) { delete(config.RuntimeParams, awsRegionParam) },+ 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 := mustParsePGXConfig(t, "postgres://[email protected]:5432/bytebase?sslmode=verify-full&bytebase_aws_rds_iam=true&bytebase_aws_region=us-east-1")+ tt.configure(pgxConfig)++ _, err := awsConfigFromPGXConfig(pgxConfig)++ require.ErrorContains(t, err, tt.wantErr)+ })+ }+}++func TestAWSConfigFromPGXConfigNonURIAllowsParamNamesInValues(t *testing.T) {+ pgxConfig := mustParsePGXConfig(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 := awsConfigFromPGXConfig(pgxConfig)++ require.NoError(t, err)+ require.Nil(t, authConfig)+}++func TestAWSConfigFromPGXConfigRequiresVerifiedTLS(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 := mustParsePGXConfig(t, tt.pgURL)++ _, err := awsConfigFromPGXConfig(pgxConfig)++ require.ErrorContains(t, err, "verified TLS is required")+ })+ }+}++func TestAWSConfigFromPGXConfigRejectsFallbacks(t *testing.T) {+ pgxConfig := mustParsePGXConfig(t, "postgres://[email protected]:5432/bytebase?sslmode=prefer&bytebase_aws_rds_iam=true&bytebase_aws_region=us-east-1")++ _, err := awsConfigFromPGXConfig(pgxConfig)++ require.ErrorContains(t, err, "fallback hosts or TLS fallback")+}++func TestNewAWSBeforeConnectSetsPassword(t *testing.T) {+ tokenProvider := &fakeTokenProvider{token: "generated-token"}+ hook := newAWSBeforeConnect(&awsConfig{+ endpoint: "example.us-east-1.rds.amazonaws.com:5432",+ region: "us-east-1",+ user: "bb_meta",+ }, tokenProvider)+ connConfig := &pgx.ConnConfig{}+ ctx := context.WithValue(context.Background(), contextKey{}, "marker")++ err := hook(ctx, connConfig)++ require.NoError(t, err)+ require.Equal(t, "generated-token", connConfig.Password)+ require.Equal(t, []fakeTokenProviderCall{+ {+ ctx: ctx,+ endpoint: "example.us-east-1.rds.amazonaws.com:5432",+ region: "us-east-1",+ user: "bb_meta",+ },+ }, tokenProvider.calls)+}++func TestNewAWSBeforeConnectReturnsTokenError(t *testing.T) {+ tokenProvider := &fakeTokenProvider{err: errors.New("credential chain failed")}+ hook := newAWSBeforeConnect(&awsConfig{+ 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 TestAWSOpenOptions(t *testing.T) {+ require.Empty(t, awsOpenOptions(nil, &fakeTokenProvider{}))++ authConfig := &awsConfig{+ enabled: true,+ region: "us-east-1",+ endpoint: "example.us-east-1.rds.amazonaws.com:5432",+ user: "bb_meta",+ }++ require.Len(t, awsOpenOptions(authConfig, &fakeTokenProvider{}), 1)+}++func TestConfigure(t *testing.T) {+ pgxConfig := mustParsePGXConfig(t, "postgres://[email protected]:5432/bytebase?sslmode=verify-full")++ options, err := Configure(context.Background(), pgxConfig)++ require.NoError(t, err)+ require.Empty(t, options)+}++func TestConfigureRequiresAWSRegion(t *testing.T) {+ pgxConfig := mustParsePGXConfig(t, "postgres://[email protected]:5432/bytebase?sslmode=verify-full&bytebase_aws_rds_iam=true")++ _, err := Configure(context.Background(), pgxConfig)++ require.ErrorContains(t, err, "bytebase_aws_region is required")+}++func TestConfigureEnabledAWSReturnsOpenOption(t *testing.T) {+ pgxConfig := mustParsePGXConfig(t, "postgres://[email protected]:5432/bytebase?sslmode=verify-full&bytebase_aws_rds_iam=true&bytebase_aws_region=us-east-1")++ options, err := Configure(context.Background(), pgxConfig)++ require.NoError(t, err)+ require.Len(t, options, 1)+}++func TestIsKeywordValueRuntimeParam(t *testing.T) {+ require.True(t, IsKeywordValueRuntimeParam("bytebase_aws_rds_iam"))+ require.True(t, IsKeywordValueRuntimeParam("bytebase_aws_region"))+ require.False(t, IsKeywordValueRuntimeParam("host"))+}++func mustParsePGXConfig(t *testing.T, pgURL string) *pgx.ConnConfig {+ t.Helper()++ pgxConfig, err := pgx.ParseConfig(pgURL)+ require.NoError(t, err)+ return pgxConfig+}diff --git a/backend/store/metadata_db_auth_test.go b/backend/store/metadata_db_auth_test.godeleted file mode 100644index 4189042564..0000000000--- a/backend/store/metadata_db_auth_test.go+++ /dev/null@@ -1,225 +0,0 @@-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/superpowers/plans/2026-05-06-metadata-db-auth-refactor.md b/docs/superpowers/plans/2026-05-06-metadata-db-auth-refactor.mdnew file mode 100644index 0000000000..6505d9366b--- /dev/null+++ b/docs/superpowers/plans/2026-05-06-metadata-db-auth-refactor.md@@ -0,0 +1,672 @@+# Metadata DB Auth Refactor 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:** Move metadata database auth setup into one provider-neutral `backend/store/dbauth` package while preserving existing AWS RDS IAM behavior.++**Architecture:** `backend/store/db_connection.go` remains responsible for reading `PG_URL`, parsing pgx config, tracing, pinging, and pool sizing. The new `backend/store/dbauth` package owns metadata database auth runtime params, provider dispatch, AWS validation, and pgx open options. Managed-instance auth under `backend/plugin/db` is not changed.++**Tech Stack:** Go, pgx v5, pgx stdlib `OptionOpenDB`, AWS SDK v2 RDS IAM auth, testify, gofmt, golangci-lint.++---++## File Structure++- Create `backend/store/dbauth/auth.go`: public metadata DB auth entrypoints and provider runtime-param detection.+- Create `backend/store/dbauth/aws.go`: AWS RDS IAM metadata DB auth implementation moved from `backend/store/metadata_db_auth.go`.+- Create `backend/store/dbauth/aws_test.go`: tests moved from `backend/store/metadata_db_auth_test.go`, adjusted for package `dbauth`.+- Modify `backend/store/db_connection.go`: import `dbauth`, delegate auth configuration, and delegate provider-specific keyword-value runtime param detection.+- Modify `backend/store/db_connection_test.go`: keep file-path detection coverage after provider param names move out of `store`.+- Delete `backend/store/metadata_db_auth.go`.+- Delete `backend/store/metadata_db_auth_test.go`.++## Task 1: Create `dbauth` Package API With Failing Tests++**Files:**+- Create: `backend/store/dbauth/auth.go`+- Create: `backend/store/dbauth/aws_test.go`++- [ ] **Step 1: Create a minimal package shell**++Create `backend/store/dbauth/auth.go`:++```go+package dbauth++import (+ "context"++ "github.com/jackc/pgx/v5"+ "github.com/jackc/pgx/v5/stdlib"+)++// Configure applies metadata database authentication settings to pgxConfig.+func Configure(_ context.Context, _ *pgx.ConnConfig) ([]stdlib.OptionOpenDB, error) {+ return nil, nil+}++// IsKeywordValueRuntimeParam reports whether key is a Bytebase metadata DB auth runtime parameter.+func IsKeywordValueRuntimeParam(_ string) bool {+ return false+}+```++- [ ] **Step 2: Add failing AWS auth tests**++Create `backend/store/dbauth/aws_test.go`:++```go+package dbauth++import (+ "context"+ "errors"+ "testing"++ "github.com/jackc/pgx/v5"+ "github.com/stretchr/testify/require"+)++type fakeTokenProvider struct {+ token string+ err error+ calls []fakeTokenProviderCall+}++type fakeTokenProviderCall struct {+ endpoint string+ region string+ user string+}++func (p *fakeTokenProvider) BuildAuthToken(_ context.Context, endpoint, region, user string) (string, error) {+ p.calls = append(p.calls, fakeTokenProviderCall{+ endpoint: endpoint,+ region: region,+ user: user,+ })+ return p.token, p.err+}++func TestAWSConfigFromPGXConfigDisabled(t *testing.T) {+ pgxConfig := mustParsePGXConfig(t, "postgres://bb:[email protected]:5432/bytebase?sslmode=verify-full")++ authConfig, err := awsConfigFromPGXConfig(pgxConfig)++ require.NoError(t, err)+ require.Nil(t, authConfig)+}++func TestAWSConfigFromPGXConfigEnabledURL(t *testing.T) {+ pgxConfig := mustParsePGXConfig(t, "postgres://[email protected]:5432/bytebase?sslmode=verify-full&bytebase_aws_rds_iam=true&bytebase_aws_region=us-east-1")++ authConfig, err := awsConfigFromPGXConfig(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, awsRDSIAMParam)+ require.NotContains(t, pgxConfig.RuntimeParams, awsRegionParam)+}++func TestAWSConfigFromPGXConfigEnabledKeywordValue(t *testing.T) {+ pgxConfig := mustParsePGXConfig(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 := awsConfigFromPGXConfig(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, awsRDSIAMParam)+ require.NotContains(t, pgxConfig.RuntimeParams, awsRegionParam)+}++func TestAWSConfigFromPGXConfigStripsDisabledParams(t *testing.T) {+ pgxConfig := mustParsePGXConfig(t, "postgres://bb:[email protected]:5432/bytebase?bytebase_aws_rds_iam=false&bytebase_aws_region=us-east-1&sslmode=verify-full")++ authConfig, err := awsConfigFromPGXConfig(pgxConfig)++ require.NoError(t, err)+ require.Nil(t, authConfig)+ require.NotContains(t, pgxConfig.RuntimeParams, awsRDSIAMParam)+ require.NotContains(t, pgxConfig.RuntimeParams, awsRegionParam)+}++func TestAWSConfigFromPGXConfigRequiresFields(t *testing.T) {+ tests := []struct {+ name string+ configure func(*pgx.ConnConfig)+ wantErr string+ }{+ {+ name: "region",+ configure: func(config *pgx.ConnConfig) { delete(config.RuntimeParams, awsRegionParam) },+ 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 := mustParsePGXConfig(t, "postgres://[email protected]:5432/bytebase?sslmode=verify-full&bytebase_aws_rds_iam=true&bytebase_aws_region=us-east-1")+ tt.configure(pgxConfig)++ _, err := awsConfigFromPGXConfig(pgxConfig)++ require.ErrorContains(t, err, tt.wantErr)+ })+ }+}++func TestAWSConfigFromPGXConfigNonURIAllowsParamNamesInValues(t *testing.T) {+ pgxConfig := mustParsePGXConfig(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 := awsConfigFromPGXConfig(pgxConfig)++ require.NoError(t, err)+ require.Nil(t, authConfig)+}++func TestAWSConfigFromPGXConfigRequiresVerifiedTLS(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 := mustParsePGXConfig(t, tt.pgURL)++ _, err := awsConfigFromPGXConfig(pgxConfig)++ require.ErrorContains(t, err, "verified TLS is required")+ })+ }+}++func TestAWSConfigFromPGXConfigRejectsFallbacks(t *testing.T) {+ pgxConfig := mustParsePGXConfig(t, "postgres://[email protected]:5432/bytebase?sslmode=prefer&bytebase_aws_rds_iam=true&bytebase_aws_region=us-east-1")++ _, err := awsConfigFromPGXConfig(pgxConfig)++ require.ErrorContains(t, err, "fallback hosts or TLS fallback")+}++func TestNewAWSBeforeConnectSetsPassword(t *testing.T) {+ tokenProvider := &fakeTokenProvider{token: "generated-token"}+ hook := newAWSBeforeConnect(&awsConfig{+ 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, []fakeTokenProviderCall{+ {+ endpoint: "example.us-east-1.rds.amazonaws.com:5432",+ region: "us-east-1",+ user: "bb_meta",+ },+ }, tokenProvider.calls)+}++func TestNewAWSBeforeConnectReturnsTokenError(t *testing.T) {+ tokenProvider := &fakeTokenProvider{err: errors.New("credential chain failed")}+ hook := newAWSBeforeConnect(&awsConfig{+ 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 TestAWSOpenOptions(t *testing.T) {+ require.Empty(t, awsOpenOptions(nil, &fakeTokenProvider{}))++ authConfig := &awsConfig{+ enabled: true,+ region: "us-east-1",+ endpoint: "example.us-east-1.rds.amazonaws.com:5432",+ user: "bb_meta",+ }++ require.Len(t, awsOpenOptions(authConfig, &fakeTokenProvider{}), 1)+}++func TestConfigure(t *testing.T) {+ pgxConfig := mustParsePGXConfig(t, "postgres://[email protected]:5432/bytebase?sslmode=verify-full")++ options, err := Configure(context.Background(), pgxConfig)++ require.NoError(t, err)+ require.Empty(t, options)+}++func TestIsKeywordValueRuntimeParam(t *testing.T) {+ require.True(t, IsKeywordValueRuntimeParam("bytebase_aws_rds_iam"))+ require.True(t, IsKeywordValueRuntimeParam("bytebase_aws_region"))+ require.False(t, IsKeywordValueRuntimeParam("host"))+}++func mustParsePGXConfig(t *testing.T, pgURL string) *pgx.ConnConfig {+ t.Helper()++ pgxConfig, err := pgx.ParseConfig(pgURL)+ require.NoError(t, err)+ return pgxConfig+}+```++- [ ] **Step 3: Run test to verify failure**++Run:++```bash+go test -v -count=1 ./backend/store/dbauth+```++Expected: FAIL with undefined identifiers including `awsConfigFromPGXConfig`, `awsRDSIAMParam`, `awsRegionParam`, `newAWSBeforeConnect`, and `awsOpenOptions`.++## Task 2: Move AWS Implementation Into `dbauth`++**Files:**+- Create: `backend/store/dbauth/aws.go`+- Modify: `backend/store/dbauth/auth.go`++- [ ] **Step 1: Implement provider-neutral dispatch**++Replace `backend/store/dbauth/auth.go` with:++```go+package dbauth++import (+ "context"++ "github.com/jackc/pgx/v5"+ "github.com/jackc/pgx/v5/stdlib"+)++// Configure applies metadata database authentication settings to pgxConfig.+func Configure(ctx context.Context, pgxConfig *pgx.ConnConfig) ([]stdlib.OptionOpenDB, error) {+ authConfig, err := awsConfigFromPGXConfig(pgxConfig)+ if err != nil {+ return nil, err+ }+ if authConfig == nil || !authConfig.enabled {+ return nil, nil+ }++ tokenProvider, err := newAWSMetadataDBTokenProvider(ctx, authConfig.region)+ if err != nil {+ return nil, err+ }+ return awsOpenOptions(authConfig, tokenProvider), nil+}++// IsKeywordValueRuntimeParam reports whether key is a Bytebase metadata DB auth runtime parameter.+func IsKeywordValueRuntimeParam(key string) bool {+ switch key {+ case awsRDSIAMParam, awsRegionParam:+ return true+ default:+ return false+ }+}+```++- [ ] **Step 2: Implement AWS provider**++Create `backend/store/dbauth/aws.go`:++```go+package dbauth++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 (+ awsRDSIAMParam = "bytebase_aws_rds_iam"+ awsRegionParam = "bytebase_aws_region"+)++type awsConfig struct {+ enabled bool+ region string+ endpoint string+ user string+}++type awsTokenProvider 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 awsConfigFromPGXConfig(pgxConfig *pgx.ConnConfig) (*awsConfig, error) {+ iamEnabled := pgxConfig.RuntimeParams[awsRDSIAMParam] == "true"+ region := pgxConfig.RuntimeParams[awsRegionParam]+ delete(pgxConfig.RuntimeParams, awsRDSIAMParam)+ delete(pgxConfig.RuntimeParams, awsRegionParam)++ if !iamEnabled {+ return nil, nil+ }++ if region == "" {+ return nil, errors.Errorf("%s is required when metadata database AWS RDS IAM auth is enabled", awsRegionParam)+ }++ 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 &awsConfig{+ enabled: true,+ region: region,+ endpoint: net.JoinHostPort(pgxConfig.Host, strconv.FormatUint(uint64(pgxConfig.Port), 10)),+ user: pgxConfig.User,+ }, nil+}++func newAWSBeforeConnect(authConfig *awsConfig, tokenProvider awsTokenProvider) 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 awsOpenOptions(authConfig *awsConfig, tokenProvider awsTokenProvider) []stdlib.OptionOpenDB {+ if authConfig == nil || !authConfig.enabled {+ return nil+ }+ return []stdlib.OptionOpenDB{stdlib.OptionBeforeConnect(newAWSBeforeConnect(authConfig, tokenProvider))}+}+```++- [ ] **Step 3: Run dbauth tests**++Run:++```bash+go test -v -count=1 ./backend/store/dbauth+```++Expected: PASS.++- [ ] **Step 4: Commit**++Run:++```bash+git add backend/store/dbauth/auth.go backend/store/dbauth/aws.go backend/store/dbauth/aws_test.go+git commit -m "refactor(store): add metadata DB auth package"+```++## Task 3: Wire `db_connection.go` To `dbauth` And Remove Old Store Auth++**Files:**+- Modify: `backend/store/db_connection.go`+- Modify: `backend/store/db_connection_test.go`+- Delete: `backend/store/metadata_db_auth.go`+- Delete: `backend/store/metadata_db_auth_test.go`++- [ ] **Step 1: Update imports and keyword-value detection**++In `backend/store/db_connection.go`, add:++```go+ "github.com/bytebase/bytebase/backend/store/dbauth"+```++Update the `isKeywordValuePGURL` switch so provider-specific keys are delegated:++```go+ case "host",+ "hostaddr",+ "port",+ "dbname",+ "database",+ "user",+ "password",+ "passfile",+ "connect_timeout",+ "sslmode",+ "sslrootcert",+ "sslcert",+ "sslkey",+ "service",+ "servicefile",+ "target_session_attrs",+ "application_name":+ return true+ default:+ if dbauth.IsKeywordValueRuntimeParam(field[:eqIdx]) {+ return true+ }+ }+```++- [ ] **Step 2: Delegate metadata auth setup**++Replace the auth setup block in `createConnectionWithTracer`:++```go+ authConfig, err := metadataDBAuthConfigFromPGXConfig(pgxConfig)+ if err != nil {+ return nil, err+ }++ 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)...)+```++with:++```go+ openOptions, err := dbauth.Configure(ctx, pgxConfig)+ if err != nil {+ return nil, err+ }++ pgxConfig.Tracer = &metadataDBTracer{}+ db := stdlib.OpenDB(*pgxConfig, openOptions...)+```++- [ ] **Step 3: Keep file-path detection test coverage**++In `backend/store/db_connection_test.go`, keep the existing `"keyword value IAM DSN"` case exactly:++```go+{+ 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,+},+```++This verifies `db_connection.go` still recognizes auth runtime params through `dbauth.IsKeywordValueRuntimeParam`.++- [ ] **Step 4: Delete old store-level auth files**++Use `apply_patch`:++```diff+*** Begin Patch+*** Delete File: backend/store/metadata_db_auth.go+*** Delete File: backend/store/metadata_db_auth_test.go+*** End Patch+```++- [ ] **Step 5: Format modified Go files**++Run:++```bash+gofmt -w backend/store/db_connection.go backend/store/db_connection_test.go backend/store/dbauth/*.go+```++- [ ] **Step 6: Run focused tests**++Run:++```bash+go test -v -count=1 ./backend/store ./backend/store/dbauth+```++Expected: PASS.++- [ ] **Step 7: Commit**++Run:++```bash+git add backend/store/db_connection.go backend/store/db_connection_test.go backend/store/dbauth backend/store/metadata_db_auth.go backend/store/metadata_db_auth_test.go+git commit -m "refactor(store): move metadata DB auth out of store package"+```++## Task 4: Final Validation++**Files:**+- Verify only.++- [ ] **Step 1: Run Go lint**++Run:++```bash+golangci-lint run --allow-parallel-runners+```++Expected: PASS. If it reports issues, fix the reported issues and run the same command again until it passes.++- [ ] **Step 2: Run focused tests again**++Run:++```bash+go test -v -count=1 ./backend/store ./backend/store/dbauth+```++Expected: PASS.++- [ ] **Step 3: Inspect final diff**++Run:++```bash+git diff --stat origin/main...HEAD+git diff --name-status origin/main...HEAD+```++Expected: the diff includes the spec and plan docs plus the metadata DB auth package move. It should not include managed-instance auth files under `backend/plugin/db`.++- [ ] **Step 4: Commit validation fixes if any**++If lint or tests required code changes, run:++```bash+git add backend/store backend/store/dbauth+git commit -m "fix(store): address metadata DB auth refactor validation"+```++If no validation fixes were needed, do not create an empty commit.diff --git a/docs/superpowers/specs/2026-05-06-metadata-db-auth-refactor-design.md b/docs/superpowers/specs/2026-05-06-metadata-db-auth-refactor-design.mdnew file mode 100644index 0000000000..a4e25be681--- /dev/null+++ b/docs/superpowers/specs/2026-05-06-metadata-db-auth-refactor-design.md@@ -0,0 +1,148 @@+# Metadata Database Auth Refactor Design++## Context++Bytebase now supports AWS RDS IAM authentication for the metadata PostgreSQL database. The merged implementation lives directly in `backend/store/metadata_db_auth.go`, while metadata database connection creation lives in `backend/store/db_connection.go`.++Bytebase also supports cloud IAM authentication for managed instances, but those paths use `db.ConnectionConfig`, datasource protobuf fields, optional static credentials, optional AWS assume-role, and engine-specific connection setup. Metadata database auth is different: it is configured from startup `PG_URL`, uses runtime environment credentials, and runs during server bootstrap.++This refactor should improve metadata database auth organization without unifying it with managed-instance auth code. There are only two high-level call sites, and a shared cloud primitive layer would add coupling without enough payoff.++## Goals++- Move metadata database auth code out of the top-level `store` package into one focused package layer.+- Keep managed-instance cloud auth code unchanged.+- Introduce provider-neutral metadata database auth entrypoints now, with AWS as the only implementation in this refactor.+- Avoid leaking provider-specific runtime parameter names into `db_connection.go`.+- Preserve existing AWS RDS IAM behavior exactly.++## Non-Goals++- Do not add GCP or Azure metadata database auth in this refactor.+- Do not create shared cloud auth primitives under `backend/common`.+- Do not change Helm values or documented `PG_URL` parameters.+- Do not change managed-instance auth behavior for PostgreSQL, MySQL, OpenSearch, SQL Server, CosmosDB, or DynamoDB.+- Do not alter metadata database connection pooling, tracing, file watching, or reconnection behavior except for calling the new auth package.++## Package Layout++Create one new package:++```text+backend/store/dbauth/+ auth.go+ aws.go+ aws_test.go+```++The package is metadata-database-specific. Future providers should be added as sibling files:++```text+backend/store/dbauth/gcp.go+backend/store/dbauth/azure.go+```++This keeps the path shallow and avoids a nested `store/metadatadb/auth` package.++## Public API++`backend/store/dbauth` should expose:++```go+func Configure(ctx context.Context, pgxConfig *pgx.ConnConfig) ([]stdlib.OptionOpenDB, error)++func IsKeywordValueRuntimeParam(key string) bool+```++`Configure` owns metadata database auth setup. It may mutate `pgxConfig` and return `stdlib.OptionOpenDB` values. This is intentionally broader than a password-token abstraction because future providers may need different connection hooks:++- AWS uses `OptionBeforeConnect` to set a fresh RDS IAM token as the password.+- GCP Cloud SQL may need to set `pgxConfig.DialFunc`.+- Azure may need token/password injection or provider-specific connection behavior.++`IsKeywordValueRuntimeParam` lets `db_connection.go` classify keyword-value PostgreSQL DSNs without knowing provider-specific Bytebase auth parameter names.++## Data Flow++`backend/store/db_connection.go` should parse the PostgreSQL URL and delegate auth setup:++```go+pgxConfig, err := pgx.ParseConfig(pgURL)+if err != nil {+ return nil, errors.Wrap(err, "failed to parse database URL")+}++openOptions, err := dbauth.Configure(ctx, pgxConfig)+if err != nil {+ return nil, err+}++pgxConfig.Tracer = &metadataDBTracer{}+db := stdlib.OpenDB(*pgxConfig, openOptions...)+```++`isKeywordValuePGURL` should continue to recognize standard PostgreSQL keyword-value fields locally, but provider-specific Bytebase auth keys should be checked through `dbauth.IsKeywordValueRuntimeParam(key)`.++## AWS Provider Behavior++Move the current AWS implementation from `backend/store/metadata_db_auth.go` into `backend/store/dbauth/aws.go`.++The behavior must remain the same:++1. Detect `bytebase_aws_rds_iam=true`.+2. Read `bytebase_aws_region`.+3. Delete `bytebase_aws_rds_iam` and `bytebase_aws_region` from `pgxConfig.RuntimeParams`, regardless of whether IAM is enabled.+4. If AWS IAM is disabled, return no open options.+5. If enabled, require region, database user, host, and port.+6. Reject fallback hosts and TLS fallback.+7. Require verified TLS.+8. Load AWS default config with the configured region.+9. Return `stdlib.OptionBeforeConnect`, which signs a fresh auth token and assigns `connConfig.Password`.++The AWS token provider interface should remain internal to `dbauth` so tests can inject a fake token builder without exporting unnecessary surface area.++## Future Provider Direction++Future GCP and Azure metadata database auth should extend `dbauth.Configure`, not `backend/store/db_connection.go`.++The current AWS parameters remain supported for compatibility:++```text+bytebase_aws_rds_iam=true+bytebase_aws_region=us-east-1+```++If future provider parameters are added, their provider-specific names should be owned by `dbauth` and exposed to `db_connection.go` only through `IsKeywordValueRuntimeParam`.++This design does not require a provider registry. Providers are compile-time code, and a registry would be more abstraction than the current problem needs.++## Testing++Move the current metadata database auth tests into `backend/store/dbauth/aws_test.go`, adjusted for package `dbauth`.++Keep `backend/store/db_connection_test.go`, but make sure keyword-value DSN detection still covers a DSN with Bytebase auth params.++Test coverage should include:++- AWS disabled returns no open options and strips Bytebase AWS params.+- AWS URI-style DSN parses and configures endpoint, region, and user.+- AWS keyword-value DSN parses and configures endpoint, region, and user.+- Missing region, user, host, and port return errors.+- `sslmode=disable`, `sslmode=require`, and TLS fallback continue to return errors.+- Fallback host rejection remains.+- `BeforeConnect` sets the generated token as the password.+- Token generation errors are wrapped with endpoint, region, and user context.+- `Configure` returns one open option for AWS enabled and none for disabled.+- `isFilePath` still treats keyword-value DSNs with Bytebase auth params as DSNs, not file paths.++## Validation++After implementation, run:++```bash+gofmt -w backend/store/db_connection.go backend/store/db_connection_test.go backend/store/dbauth/*.go+go test -v -count=1 ./backend/store ./backend/store/dbauth+golangci-lint run --allow-parallel-runners+```++Because this is Go code, repeat `golangci-lint run --allow-parallel-runners` until it reports no issues.