refactor: assemble and reuse Instance dependencies

internal/controller/postgresqlinstance_controller.go

@@ -18,6 +18,7 @@ package controller
 
 import (
 	"context"
+	"fmt"
 	"reflect"
 	"time"
 
@@ -33,15 +34,16 @@ import (
 // PostgreSQLInstanceReconciler reconciles a PostgreSQLInstance object
 type PostgreSQLInstanceReconciler struct {
 	client.Client
-	Scheme      *runtime.Scheme
-	Initializer PostgreSQLInstanceInitializer
-	Timeout     time.Duration
+	Scheme    *runtime.Scheme
+	Instances PostgreSQLInstances
+	Timeout   time.Duration
 }
 
-// PostgreSQLInstanceInitializer is the external dependency boundary used by the Instance state machine.
-type PostgreSQLInstanceInitializer interface {
+// PostgreSQLInstances is the external dependency boundary used by the Instance state machine.
+type PostgreSQLInstances interface {
 	Validate(context.Context, *databasev1alpha1.PostgreSQLInstance) (string, error)
 	InitializeRegistry(context.Context, *databasev1alpha1.PostgreSQLInstance) (string, error)
+	Forget(string)
 }
 
 // +kubebuilder:rbac:groups=database.ddupan.top,resources=postgresqlinstances,verbs=get;list;watch;create;update;patch;delete
@@ -61,16 +63,20 @@ func (r *PostgreSQLInstanceReconciler) Reconcile(ctx context.Context, req ctrl.R
 	logger := logf.FromContext(ctx)
 	instance := &databasev1alpha1.PostgreSQLInstance{}
 	if err := r.Get(ctx, req.NamespacedName, instance); err != nil {
+		if apierrors.IsNotFound(err) {
+			r.Instances.Forget(req.Name)
+		}
 		return ctrl.Result{}, client.IgnoreNotFound(err)
 	}
 
 	before := instance.DeepCopy()
+	operationCtx := ctx
 	if r.Timeout > 0 {
 		var cancel context.CancelFunc
-		ctx, cancel = context.WithTimeout(ctx, r.Timeout)
+		operationCtx, cancel = context.WithTimeout(ctx, r.Timeout)
 		defer cancel()
 	}
-	result, reconcileErr := newInstanceStateMachine(r.Initializer).reconcile(ctx, instance)
+	result, reconcileErr := newInstanceStateMachine(r.Instances).reconcile(operationCtx, instance)
 
 	if !reflect.DeepEqual(before.Status, instance.Status) {
 		if err := r.Status().Patch(ctx, instance, client.MergeFrom(before)); err != nil {
@@ -86,6 +92,9 @@ func (r *PostgreSQLInstanceReconciler) Reconcile(ctx context.Context, req ctrl.R
 
 // SetupWithManager sets up the controller with the Manager.
 func (r *PostgreSQLInstanceReconciler) SetupWithManager(mgr ctrl.Manager) error {
+	if r.Instances == nil {
+		return fmt.Errorf("instance service must be injected before controller setup")
+	}
 	return ctrl.NewControllerManagedBy(mgr).
 		For(&databasev1alpha1.PostgreSQLInstance{}).
 		Named("postgresqlinstance").

internal/controller/postgresqlinstance_controller_test.go

@@ -77,8 +77,9 @@ var _ = Describe("PostgreSQLInstance Controller", func() {
 		It("should successfully reconcile the resource", func() {
 			By("Reconciling the created resource")
 			controllerReconciler := &PostgreSQLInstanceReconciler{
-				Client: k8sClient,
-				Scheme: k8sClient.Scheme(),
+				Client:    k8sClient,
+				Scheme:    k8sClient.Scheme(),
+				Instances: fakeInstances{validateVersion: testPostgreSQLVersion, registryVersion: testPostgreSQLVersion},
 			}
 
 			_, err := controllerReconciler.Reconcile(ctx, reconcile.Request{
@@ -95,6 +96,14 @@ var _ = Describe("PostgreSQLInstance Controller", func() {
 				HaveField("ObservedGeneration", actual.Generation),
 			)))
 
+			// Advance to Ready using an injected fake, then prove an unchanged
+			// readiness observation does not patch status.
+			for range 2 {
+				_, err = controllerReconciler.Reconcile(ctx, reconcile.Request{NamespacedName: typeNamespacedName})
+				Expect(err).NotTo(HaveOccurred())
+			}
+			Expect(k8sClient.Get(ctx, typeNamespacedName, actual)).To(Succeed())
+			Expect(actual.Status.Phase).To(Equal(databasev1alpha1.PostgreSQLInstancePhaseReady))
 			resourceVersion := actual.ResourceVersion
 			_, err = controllerReconciler.Reconcile(ctx, reconcile.Request{NamespacedName: typeNamespacedName})
 			Expect(err).NotTo(HaveOccurred())

internal/controller/postgresqlinstance_state_machine.go

@@ -28,12 +28,12 @@ import (
 type instancePhaseHandler func(context.Context, *databasev1alpha1.PostgreSQLInstance) (ctrl.Result, error)
 
 type instanceStateMachine struct {
-	initializer PostgreSQLInstanceInitializer
-	handlers    map[databasev1alpha1.PostgreSQLInstancePhase]instancePhaseHandler
+	instances PostgreSQLInstances
+	handlers  map[databasev1alpha1.PostgreSQLInstancePhase]instancePhaseHandler
 }
 
-func newInstanceStateMachine(initializer PostgreSQLInstanceInitializer) *instanceStateMachine {
-	m := &instanceStateMachine{initializer: initializer}
+func newInstanceStateMachine(instances PostgreSQLInstances) *instanceStateMachine {
+	m := &instanceStateMachine{instances: instances}
 	m.handlers = map[databasev1alpha1.PostgreSQLInstancePhase]instancePhaseHandler{
 		databasev1alpha1.PostgreSQLInstancePhasePending:              m.pending,
 		databasev1alpha1.PostgreSQLInstancePhaseValidating:           m.validate,
@@ -45,6 +45,8 @@ func newInstanceStateMachine(initializer PostgreSQLInstanceInitializer) *instanc
 }
 
 func (m *instanceStateMachine) reconcile(ctx context.Context, instance *databasev1alpha1.PostgreSQLInstance) (ctrl.Result, error) {
+	// Dispatch exactly one handler from the persisted checkpoint. A handler performs
+	// its state action and returns the next checkpoint for the Reconciler to save.
 	phase := instance.Status.Phase
 	if !instance.DeletionTimestamp.IsZero() {
 		phase = databasev1alpha1.PostgreSQLInstancePhaseDeleting
@@ -69,15 +71,13 @@ func (m *instanceStateMachine) reconcile(ctx context.Context, instance *database
 }
 
 func (m *instanceStateMachine) pending(_ context.Context, instance *databasev1alpha1.PostgreSQLInstance) (ctrl.Result, error) {
+	// Persist intent before the next reconcile opens external connections.
 	return advanceInstance(instance, databasev1alpha1.PostgreSQLInstancePhaseValidating,
 		"instance dependencies are being validated"), nil
 }
 
 func (m *instanceStateMachine) validate(ctx context.Context, instance *databasev1alpha1.PostgreSQLInstance) (ctrl.Result, error) {
-	if m.initializer == nil {
-		return ctrl.Result{}, nil
-	}
-	version, err := m.initializer.Validate(ctx, instance)
+	version, err := m.instances.Validate(ctx, instance)
 	if err != nil {
 		return ctrl.Result{}, err
 	}
@@ -87,10 +87,7 @@ func (m *instanceStateMachine) validate(ctx context.Context, instance *databasev
 }
 
 func (m *instanceStateMachine) initializeRegistry(ctx context.Context, instance *databasev1alpha1.PostgreSQLInstance) (ctrl.Result, error) {
-	if m.initializer == nil {
-		return ctrl.Result{}, nil
-	}
-	version, err := m.initializer.InitializeRegistry(ctx, instance)
+	version, err := m.instances.InitializeRegistry(ctx, instance)
 	if err != nil {
 		return ctrl.Result{}, err
 	}
@@ -105,10 +102,7 @@ func (m *instanceStateMachine) ready(ctx context.Context, instance *databasev1al
 	if instance.Status.ObservedGeneration != instance.Generation {
 		return m.pending(ctx, instance)
 	}
-	if m.initializer == nil {
-		return ctrl.Result{}, nil
-	}
-	version, err := m.initializer.Validate(ctx, instance)
+	version, err := m.instances.Validate(ctx, instance)
 	if err != nil {
 		instance.Status.Phase = databasev1alpha1.PostgreSQLInstancePhaseValidating
 		return ctrl.Result{}, err
@@ -118,6 +112,7 @@ func (m *instanceStateMachine) ready(ctx context.Context, instance *databasev1al
 }
 
 func (m *instanceStateMachine) deleting(_ context.Context, instance *databasev1alpha1.PostgreSQLInstance) (ctrl.Result, error) {
+	m.instances.Forget(instance.Name)
 	instance.Status.Phase = databasev1alpha1.PostgreSQLInstancePhaseDeleting
 	setReconcilingCondition(&instance.Status.Conditions, instance.Generation, "instance deletion is reconciling")
 	return ctrl.Result{}, nil

internal/controller/state_machine_test.go

@@ -28,7 +28,7 @@ import (
 	databasev1alpha1 "git.ddupan.top/panxiao81/postgresql-tenant-operator/api/v1alpha1"
 )
 
-type fakeInstanceInitializer struct {
+type fakeInstances struct {
 	validateVersion string
 	registryVersion string
 	err             error
@@ -36,18 +36,20 @@ type fakeInstanceInitializer struct {
 
 const testPostgreSQLVersion = "17.6"
 
-func (f fakeInstanceInitializer) Validate(context.Context, *databasev1alpha1.PostgreSQLInstance) (string, error) {
+func (f fakeInstances) Forget(string) {}
+
+func (f fakeInstances) Validate(context.Context, *databasev1alpha1.PostgreSQLInstance) (string, error) {
 	return f.validateVersion, f.err
 }
 
-func (f fakeInstanceInitializer) InitializeRegistry(context.Context, *databasev1alpha1.PostgreSQLInstance) (string, error) {
+func (f fakeInstances) InitializeRegistry(context.Context, *databasev1alpha1.PostgreSQLInstance) (string, error) {
 	return f.registryVersion, f.err
 }
 
 var _ = Describe("phase handler state machines", func() {
 	It("persists validation intent before touching unavailable dependencies", func() {
 		instance := &databasev1alpha1.PostgreSQLInstance{}
-		machine := newInstanceStateMachine(fakeInstanceInitializer{err: errors.New("must not be called")})
+		machine := newInstanceStateMachine(fakeInstances{err: errors.New("must not be called")})
 		result, err := machine.reconcile(context.Background(), instance)
 		Expect(err).NotTo(HaveOccurred())
 		Expect(result.RequeueAfter).To(BeNumerically(">", 0))
@@ -62,7 +64,7 @@ var _ = Describe("phase handler state machines", func() {
 				Phase: databasev1alpha1.PostgreSQLInstancePhaseReady, ObservedGeneration: 3,
 			},
 		}
-		machine := newInstanceStateMachine(fakeInstanceInitializer{err: errors.New("must not be called")})
+		machine := newInstanceStateMachine(fakeInstances{err: errors.New("must not be called")})
 		_, err := machine.reconcile(context.Background(), instance)
 		Expect(err).NotTo(HaveOccurred())
 		Expect(instance.Status.Phase).To(Equal(databasev1alpha1.PostgreSQLInstancePhaseValidating))
@@ -76,12 +78,12 @@ var _ = Describe("phase handler state machines", func() {
 				Phase: databasev1alpha1.PostgreSQLInstancePhaseReady, ObservedGeneration: 3,
 			},
 		}
-		machine := newInstanceStateMachine(fakeInstanceInitializer{err: errors.New("unavailable")})
+		machine := newInstanceStateMachine(fakeInstances{err: errors.New("unavailable")})
 		_, err := machine.reconcile(context.Background(), instance)
 		Expect(err).To(MatchError("unavailable"))
 		Expect(instance.Status.Phase).To(Equal(databasev1alpha1.PostgreSQLInstancePhaseValidating))
 		Expect(instance.Status.Conditions[0].Status).To(Equal(metav1.ConditionFalse))
-		machine.initializer = fakeInstanceInitializer{
+		machine.instances = fakeInstances{
 			validateVersion: testPostgreSQLVersion,
 			registryVersion: testPostgreSQLVersion,
 		}
@@ -102,7 +104,7 @@ var _ = Describe("phase handler state machines", func() {
 			ObjectMeta: metav1.ObjectMeta{Generation: 3},
 			Status:     databasev1alpha1.PostgreSQLInstanceStatus{Phase: databasev1alpha1.PostgreSQLInstancePhaseValidating},
 		}
-		machine := newInstanceStateMachine(fakeInstanceInitializer{
+		machine := newInstanceStateMachine(fakeInstances{
 			validateVersion: testPostgreSQLVersion,
 			registryVersion: testPostgreSQLVersion,
 		})
@@ -124,7 +126,7 @@ var _ = Describe("phase handler state machines", func() {
 			ObjectMeta: metav1.ObjectMeta{Generation: 2},
 			Status:     databasev1alpha1.PostgreSQLInstanceStatus{Phase: databasev1alpha1.PostgreSQLInstancePhaseValidating},
 		}
-		machine := newInstanceStateMachine(fakeInstanceInitializer{err: errors.New("unavailable")})
+		machine := newInstanceStateMachine(fakeInstances{err: errors.New("unavailable")})
 		_, err := machine.reconcile(context.Background(), instance)
 		Expect(err).To(MatchError("unavailable"))
 		Expect(instance.Status.Phase).To(Equal(databasev1alpha1.PostgreSQLInstancePhaseValidating))
@@ -135,7 +137,7 @@ var _ = Describe("phase handler state machines", func() {
 
 	DescribeTable("dispatches Instance phases",
 		func(instance *databasev1alpha1.PostgreSQLInstance, expected databasev1alpha1.PostgreSQLInstancePhase, hasMessage bool) {
-			_, err := newInstanceStateMachine(nil).reconcile(context.Background(), instance)
+			_, err := newInstanceStateMachine(fakeInstances{}).reconcile(context.Background(), instance)
 			Expect(err).NotTo(HaveOccurred())
 			Expect(instance.Status.Phase).To(Equal(expected))
 			if hasMessage {
@@ -149,12 +151,12 @@ var _ = Describe("phase handler state machines", func() {
 			databasev1alpha1.PostgreSQLInstancePhaseValidating,
 			true,
 		),
-		Entry("keeps an active phase until its handler can observe dependencies",
+		Entry("initializes the registry and reaches Ready",
 			&databasev1alpha1.PostgreSQLInstance{Status: databasev1alpha1.PostgreSQLInstanceStatus{
 				Phase: databasev1alpha1.PostgreSQLInstancePhaseInitializingRegistry,
 			}},
-			databasev1alpha1.PostgreSQLInstancePhaseInitializingRegistry,
-			false,
+			databasev1alpha1.PostgreSQLInstancePhaseReady,
+			true,
 		),
 		Entry("routes deletion independently of the previous phase",
 			deletingInstance(),

internal/instance/errors.go

@@ -0,0 +1,27 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package instance
+
+// Failure contains only a safe operation message and a Condition reason.
+// Raw driver errors can contain credentials and must not escape through wrapping.
+type Failure struct {
+	Reason    string
+	Operation string
+}
+
+func (e Failure) Error() string           { return e.Operation }
+func (e Failure) ConditionReason() string { return e.Reason }

internal/instance/initializer.go

@@ -1,216 +0,0 @@
-/*
-Copyright 2026.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-*/
-
-// Package instance validates PostgreSQLInstance dependencies and initializes
-// the controller registry without exposing administrative credentials.
-package instance
-
-import (
-	"context"
-	"errors"
-	"net"
-	"net/url"
-	"path/filepath"
-	"strconv"
-	"strings"
-	"time"
-
-	"github.com/jackc/pgx/v5/pgxpool"
-	kubernetesauth "github.com/openbao/openbao/api/auth/kubernetes/v2"
-	openbao "github.com/openbao/openbao/api/v2"
-	"k8s.io/apimachinery/pkg/util/validation"
-
-	databasev1alpha1 "git.ddupan.top/panxiao81/postgresql-tenant-operator/api/v1alpha1"
-	"git.ddupan.top/panxiao81/postgresql-tenant-operator/internal/postgresql/registry"
-)
-
-// Config contains the deployment-level settings needed by Instance readiness.
-type Config struct {
-	OpenBaoAddress          string
-	OpenBaoConsumerAddress  string
-	OpenBaoAuthMount        string
-	OpenBaoAuthRole         string
-	ServiceAccountTokenPath string
-	OpenBaoKVMount          string
-	OpenBaoTenantBasePath   string
-	ExternalSecretStoreName string
-	PostgreSQLCABundlePath  string
-	Timeout                 time.Duration
-}
-
-// Initializer implements the Instance validation and registry phases.
-type Initializer struct{ config Config }
-
-type failure struct {
-	reason  string
-	message string
-}
-
-func (e failure) Error() string           { return e.message }
-func (e failure) ConditionReason() string { return e.reason }
-
-func dependencyFailure(message string) error {
-	return failure{reason: databasev1alpha1.ReasonDependencyUnavailable, message: message}
-}
-
-func authenticationFailure(message string) error {
-	return failure{reason: databasev1alpha1.ReasonAuthenticationFailed, message: message}
-}
-
-func privilegeFailure(message string) error {
-	return failure{reason: databasev1alpha1.ReasonInsufficientPrivileges, message: message}
-}
-
-// New validates config and constructs an Initializer.
-func New(config Config) (*Initializer, error) {
-	if config.OpenBaoAddress == "" || config.OpenBaoAuthRole == "" || config.OpenBaoAuthMount == "" ||
-		config.ServiceAccountTokenPath == "" || config.OpenBaoKVMount == "" || config.OpenBaoTenantBasePath == "" ||
-		config.ExternalSecretStoreName == "" || config.Timeout <= 0 {
-		return nil, errors.New("initialize instance dependencies: required configuration is missing")
-	}
-	if err := validateAddress(config.OpenBaoAddress); err != nil {
-		return nil, err
-	}
-	if config.OpenBaoConsumerAddress == "" {
-		config.OpenBaoConsumerAddress = config.OpenBaoAddress
-	}
-	if err := validateAddress(config.OpenBaoConsumerAddress); err != nil {
-		return nil, err
-	}
-	if !filepath.IsAbs(config.ServiceAccountTokenPath) || validateRelativePath(config.OpenBaoAuthMount, false) != nil ||
-		validateRelativePath(config.OpenBaoKVMount, false) != nil || validateRelativePath(config.OpenBaoTenantBasePath, true) != nil ||
-		len(validation.IsDNS1123Subdomain(config.ExternalSecretStoreName)) != 0 {
-		return nil, errors.New("initialize instance dependencies: invalid path or resource name configuration")
-	}
-	return &Initializer{config: config}, nil
-}
-
-// Validate authenticates to OpenBao, reads the administrative credential, and
-// verifies that PostgreSQL accepts it. It returns only public server metadata.
-func (i *Initializer) Validate(ctx context.Context, instance *databasev1alpha1.PostgreSQLInstance) (string, error) {
-	pool, err := i.connect(ctx, instance)
-	if err != nil {
-		return "", err
-	}
-	defer pool.Close()
-
-	var version string
-	if err := pool.QueryRow(ctx, "SHOW server_version").Scan(&version); err != nil {
-		return "", errors.New("validate PostgreSQL server metadata")
-	}
-	return version, nil
-}
-
-// InitializeRegistry repeats dependency validation and applies registry migrations.
-func (i *Initializer) InitializeRegistry(ctx context.Context, instance *databasev1alpha1.PostgreSQLInstance) (string, error) {
-	pool, err := i.connect(ctx, instance)
-	if err != nil {
-		return "", err
-	}
-	defer pool.Close()
-
-	if err := registry.NewStore(pool).Bootstrap(ctx); err != nil {
-		return "", privilegeFailure("initialize PostgreSQL registry")
-	}
-	var version string
-	if err := pool.QueryRow(ctx, "SHOW server_version").Scan(&version); err != nil {
-		return "", errors.New("validate PostgreSQL server metadata")
-	}
-	return version, nil
-}
-
-func (i *Initializer) connect(ctx context.Context, instance *databasev1alpha1.PostgreSQLInstance) (*pgxpool.Pool, error) {
-	if instance.Spec.Endpoint.SSLMode != databasev1alpha1.PostgreSQLSSLModeDisable && i.config.PostgreSQLCABundlePath == "" {
-		return nil, errors.New("configure PostgreSQL TLS: CA bundle path is required")
-	}
-	ctx, cancel := context.WithTimeout(ctx, i.config.Timeout)
-	defer cancel()
-
-	clientConfig := openbao.DefaultConfig()
-	clientConfig.Address = i.config.OpenBaoAddress
-	clientConfig.Timeout = i.config.Timeout
-	clientConfig.DisableEnvironment = true
-	client, err := openbao.NewClient(clientConfig)
-	if err != nil {
-		return nil, dependencyFailure("create OpenBao client")
-	}
-	auth, err := kubernetesauth.NewKubernetesAuth(
-		i.config.OpenBaoAuthRole,
-		kubernetesauth.WithMountPath(i.config.OpenBaoAuthMount),
-		kubernetesauth.WithServiceAccountTokenPath(i.config.ServiceAccountTokenPath),
-	)
-	if err != nil {
-		return nil, errors.New("configure OpenBao Kubernetes authentication")
-	}
-	if secret, err := client.Auth().Login(ctx, auth); err != nil || secret == nil || secret.Auth == nil {
-		return nil, authenticationFailure("authenticate to OpenBao")
-	}
-
-	secret, err := client.KVv2(i.config.OpenBaoKVMount).Get(ctx, instance.Spec.AdminCredentialRef.Path)
-	if err != nil {
-		return nil, privilegeFailure("read PostgreSQL administrative credential")
-	}
-	username, usernameOK := secret.Data[instance.Spec.AdminCredentialRef.UsernameKey].(string)
-	password, passwordOK := secret.Data[instance.Spec.AdminCredentialRef.PasswordKey].(string)
-	if !usernameOK || !passwordOK || username == "" || password == "" {
-		return nil, errors.New("read PostgreSQL administrative credential fields")
-	}
-
-	connectionURL := &url.URL{
-		Scheme: "postgresql",
-		User:   url.UserPassword(username, password),
-		Host:   net.JoinHostPort(instance.Spec.Endpoint.Host, strconv.Itoa(int(instance.Spec.Endpoint.Port))),
-		Path:   instance.Spec.Endpoint.Database,
-	}
-	query := connectionURL.Query()
-	query.Set("sslmode", string(instance.Spec.Endpoint.SSLMode))
-	if instance.Spec.Endpoint.SSLMode != databasev1alpha1.PostgreSQLSSLModeDisable {
-		query.Set("sslrootcert", i.config.PostgreSQLCABundlePath)
-	}
-	connectionURL.RawQuery = query.Encode()
-	poolConfig, err := pgxpool.ParseConfig(connectionURL.String())
-	if err != nil {
-		return nil, errors.New("configure PostgreSQL connection")
-	}
-	pool, err := pgxpool.NewWithConfig(ctx, poolConfig)
-	if err != nil {
-		return nil, errors.New("connect to PostgreSQL")
-	}
-	if err := pool.Ping(ctx); err != nil {
-		pool.Close()
-		return nil, authenticationFailure("authenticate to PostgreSQL")
-	}
-	return pool, nil
-}
-
-func validateAddress(value string) error {
-	parsed, err := url.Parse(value)
-	if err != nil || !parsed.IsAbs() || (parsed.Scheme != "http" && parsed.Scheme != "https") || parsed.Host == "" ||
-		parsed.User != nil || parsed.RawQuery != "" || parsed.Fragment != "" {
-		return errors.New("initialize instance dependencies: invalid OpenBao address")
-	}
-	return nil
-}
-
-func validateRelativePath(value string, rejectAPILayer bool) error {
-	for index, segment := range strings.Split(value, "/") {
-		if segment == "" || segment == "." || segment == ".." ||
-			(rejectAPILayer && index == 0 && (segment == "data" || segment == "metadata")) {
-			return errors.New("invalid mount-relative path")
-		}
-	}
-	return nil
-}

internal/instance/initializer_test.go

@@ -1,44 +0,0 @@
-/*
-Copyright 2026.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-*/
-
-package instance
-
-import (
-	"testing"
-	"time"
-)
-
-func TestNewValidatesDeploymentConfiguration(t *testing.T) {
-	valid := Config{
-		OpenBaoAddress: "http://openbao:8200", OpenBaoAuthMount: "kubernetes", OpenBaoAuthRole: "controller",
-		ServiceAccountTokenPath: "/var/run/secrets/token", OpenBaoKVMount: "secret",
-		OpenBaoTenantBasePath: "postgresql-tenants", ExternalSecretStoreName: "openbao", Timeout: 30 * time.Second,
-	}
-	if _, err := New(valid); err != nil {
-		t.Fatalf("New(valid) error = %v", err)
-	}
-
-	invalid := valid
-	invalid.OpenBaoTenantBasePath = "metadata/tenants"
-	if _, err := New(invalid); err == nil {
-		t.Fatal("New() accepted a KV v2 API-layer base path")
-	}
-	invalid = valid
-	invalid.OpenBaoAddress = "http://user:password@openbao:8200?token=secret"
-	if _, err := New(invalid); err == nil {
-		t.Fatal("New() accepted credentials in the OpenBao address")
-	}
-}

internal/instance/service.go

@@ -0,0 +1,152 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// Package instance manages the lifetime and capabilities of external PostgreSQL instances.
+package instance
+
+import (
+	"context"
+	"errors"
+	"sync"
+
+	api "git.ddupan.top/panxiao81/postgresql-tenant-operator/api/v1alpha1"
+	"k8s.io/apimachinery/pkg/types"
+)
+
+// Credentials are supplied by the credential source, never by the database adapter.
+type Credentials struct{ Username, Password string }
+
+func (Credentials) String() string   { return "[redacted credentials]" }
+func (Credentials) GoString() string { return "[redacted credentials]" }
+
+// CredentialSource resolves administrative credentials when an Instance is assembled.
+type CredentialSource interface {
+	Read(context.Context, api.OpenBaoSecretReference) (Credentials, error)
+}
+
+// Database exposes the capabilities of an assembled Instance.
+type Database interface {
+	Version(context.Context) (string, error)
+	EnsureRegistry(context.Context) error
+	Close()
+}
+
+// Connector creates a database without knowing where credentials came from.
+type Connector interface {
+	Connect(context.Context, api.PostgreSQLEndpoint, Credentials) (Database, error)
+}
+
+type identity struct {
+	uid       types.UID
+	endpoint  api.PostgreSQLEndpoint
+	reference api.OpenBaoSecretReference
+}
+
+type entry struct {
+	identity    identity
+	credentials *Credentials
+	database    Database
+}
+
+// Service owns Instance connections. Reconciles reuse credentials and pools until
+// the UID, endpoint or credential reference changes; allowlist changes do not rotate them.
+// Operations are serialized to prevent Close racing with an active database operation.
+type Service struct {
+	mu        sync.Mutex
+	source    CredentialSource
+	connector Connector
+	entries   map[string]*entry
+	closed    bool
+}
+
+func NewService(source CredentialSource, connector Connector) *Service {
+	return &Service{source: source, connector: connector, entries: make(map[string]*entry)}
+}
+
+func (s *Service) Validate(ctx context.Context, resource *api.PostgreSQLInstance) (string, error) {
+	return s.observe(ctx, resource, false)
+}
+
+func (s *Service) InitializeRegistry(ctx context.Context, resource *api.PostgreSQLInstance) (string, error) {
+	return s.observe(ctx, resource, true)
+}
+
+func (s *Service) observe(ctx context.Context, resource *api.PostgreSQLInstance, ensureRegistry bool) (string, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.closed {
+		return "", errors.New("instance service is closed")
+	}
+	db, err := s.database(ctx, resource)
+	if err != nil {
+		return "", err
+	}
+	if ensureRegistry {
+		if err := db.EnsureRegistry(ctx); err != nil {
+			return "", err
+		}
+	}
+	return db.Version(ctx)
+}
+
+func (s *Service) database(ctx context.Context, resource *api.PostgreSQLInstance) (Database, error) {
+	key := identity{uid: resource.UID, endpoint: resource.Spec.Endpoint, reference: resource.Spec.AdminCredentialRef}
+	current := s.entries[resource.Name]
+	if current == nil || current.identity != key {
+		s.release(resource.Name)
+		current = &entry{identity: key}
+		s.entries[resource.Name] = current
+	}
+	if current.credentials == nil {
+		credentials, err := s.source.Read(ctx, key.reference)
+		if err != nil {
+			return nil, err
+		}
+		current.credentials = &credentials
+	}
+	if current.database == nil {
+		database, err := s.connector.Connect(ctx, key.endpoint, *current.credentials)
+		if err != nil {
+			return nil, err
+		}
+		current.database = database
+	}
+	return current.database, nil
+}
+
+// Forget releases local resources only. It never deletes the external registry.
+func (s *Service) Forget(name string) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.release(name)
+}
+
+func (s *Service) release(name string) {
+	if current := s.entries[name]; current != nil && current.database != nil {
+		current.database.Close()
+	}
+	delete(s.entries, name)
+}
+
+// Close is called after manager workers stop, and is safe to repeat.
+func (s *Service) Close() {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.closed = true
+	for name := range s.entries {
+		s.release(name)
+	}
+}

internal/instance/service_test.go

@@ -0,0 +1,156 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package instance
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+	"testing"
+
+	api "git.ddupan.top/panxiao81/postgresql-tenant-operator/api/v1alpha1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+type sourceStub struct {
+	reads int
+	err   error
+}
+
+func (s *sourceStub) Read(context.Context, api.OpenBaoSecretReference) (Credentials, error) {
+	s.reads++
+	return Credentials{Username: "admin", Password: "canary-secret"}, s.err
+}
+
+type databaseStub struct {
+	closes, migrations int
+	err                error
+}
+
+func (d *databaseStub) Version(context.Context) (string, error) { return "17", d.err }
+func (d *databaseStub) EnsureRegistry(context.Context) error    { d.migrations++; return d.err }
+func (d *databaseStub) Close()                                  { d.closes++ }
+
+type connectorStub struct {
+	databases []*databaseStub
+	err       error
+}
+
+func (c *connectorStub) Connect(context.Context, api.PostgreSQLEndpoint, Credentials) (Database, error) {
+	if c.err != nil {
+		return nil, c.err
+	}
+	database := &databaseStub{}
+	c.databases = append(c.databases, database)
+	return database, nil
+}
+
+func TestInstanceConnectionLifetime(t *testing.T) {
+	source, connector := &sourceStub{}, &connectorStub{}
+	service := NewService(source, connector)
+	defer service.Close()
+	resource := &api.PostgreSQLInstance{ObjectMeta: metav1.ObjectMeta{Name: "shared", UID: "uid-1"}}
+	ctx := context.Background()
+	check := func() {
+		t.Helper()
+		if _, err := service.Validate(ctx, resource); err != nil {
+			t.Fatalf("validate: %v", err)
+		}
+	}
+	check()
+	if _, err := service.InitializeRegistry(ctx, resource); err != nil {
+		t.Fatal(err)
+	}
+	resource.Generation++
+	resource.Spec.AllowedExtensions = []string{"pg_trgm"}
+	check()
+	if source.reads != 1 || len(connector.databases) != 1 || connector.databases[0].migrations != 1 {
+		t.Fatal("reconciliation or allowlist update unnecessarily reassembled dependencies")
+	}
+	connector.databases[0].err = errors.New("network outage")
+	if _, err := service.Validate(ctx, resource); err == nil {
+		t.Fatal("outage went unnoticed")
+	}
+	connector.databases[0].err = nil
+	check()
+	if source.reads != 1 {
+		t.Fatal("network recovery reread the password")
+	}
+
+	changes := []func(){
+		func() { resource.Spec.Endpoint.Host = "new.example" },
+		func() { resource.Spec.AdminCredentialRef.Path = "new/admin" },
+		func() { resource.UID = "uid-2" },
+	}
+	for index, change := range changes {
+		change()
+		check()
+		if connector.databases[index].closes != 1 {
+			t.Fatal("replaced pool was not closed")
+		}
+	}
+	if source.reads != 4 {
+		t.Fatal("changed connection identity did not reload credentials")
+	}
+	service.Forget(resource.Name)
+	service.Forget(resource.Name)
+	if connector.databases[3].closes != 1 {
+		t.Fatal("deletion did not close pool exactly once")
+	}
+	check()
+	service.Close()
+	service.Close()
+	if connector.databases[4].closes != 1 {
+		t.Fatal("shutdown did not close pool exactly once")
+	}
+	if _, err := service.Validate(ctx, resource); err == nil {
+		t.Fatal("closed service accepted work")
+	}
+}
+
+func TestAssemblyRetriesWithoutPasswordRotation(t *testing.T) {
+	source := &sourceStub{err: errors.New("bao unavailable")}
+	connector := &connectorStub{err: errors.New("connection unavailable")}
+	service := NewService(source, connector)
+	defer service.Close()
+	resource := &api.PostgreSQLInstance{ObjectMeta: metav1.ObjectMeta{Name: "shared"}}
+	ctx := context.Background()
+	if _, err := service.Validate(ctx, resource); err == nil {
+		t.Fatal("expected source failure")
+	}
+	source.err = nil
+	if _, err := service.Validate(ctx, resource); err == nil {
+		t.Fatal("expected connection failure")
+	}
+	connector.err = nil
+	if _, err := service.Validate(ctx, resource); err != nil {
+		t.Fatal(err)
+	}
+	if source.reads != 2 {
+		t.Fatal("retry reread successfully cached credentials")
+	}
+}
+
+func TestCredentialsFormattingIsRedacted(t *testing.T) {
+	value := Credentials{Username: "canary-user", Password: "canary-secret"}
+	for _, format := range []string{"%v", "%+v", "%#v"} {
+		if strings.Contains(fmt.Sprintf(format, value), "canary") {
+			t.Fatal("credential formatting leaked data")
+		}
+	}
+}

internal/openbao/credentials.go

@@ -0,0 +1,133 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// Package openbao supplies credentials using one shared client and Kubernetes identity.
+package openbao
+
+import (
+	"context"
+	"errors"
+	"sync"
+	"time"
+
+	api "git.ddupan.top/panxiao81/postgresql-tenant-operator/api/v1alpha1"
+	"git.ddupan.top/panxiao81/postgresql-tenant-operator/internal/instance"
+	kubernetesauth "github.com/openbao/openbao/api/auth/kubernetes/v2"
+	bao "github.com/openbao/openbao/api/v2"
+)
+
+// Credentials owns authentication; database connections never depend on this client.
+type Credentials struct {
+	client       *bao.Client
+	mount        string
+	authenticate func(context.Context) (*bao.Secret, error)
+	mu           sync.Mutex
+	expires      time.Time
+}
+
+func NewCredentials(client *bao.Client, mount, authMount, role string) *Credentials {
+	source := &Credentials{client: client, mount: mount}
+	source.authenticate = func(ctx context.Context) (*bao.Secret, error) {
+		// Constructing auth here rereads the projected JWT after Kubernetes rotates it.
+		auth, err := kubernetesauth.NewKubernetesAuth(role, kubernetesauth.WithMountPath(authMount))
+		if err != nil {
+			return nil, instance.Failure{Reason: api.ReasonAuthenticationFailed, Operation: "read Kubernetes identity"}
+		}
+		return client.Auth().Login(ctx, auth)
+	}
+	return source
+}
+
+func (s *Credentials) login(ctx context.Context) error {
+	secret, err := s.authenticate(ctx)
+	if err != nil {
+		return classify("authenticate to OpenBao", err, true)
+	}
+	if secret == nil || secret.Auth == nil || secret.Auth.ClientToken == "" || secret.Auth.LeaseDuration <= 0 {
+		return instance.Failure{Reason: api.ReasonAuthenticationFailed, Operation: "OpenBao returned no leased identity"}
+	}
+	s.client.SetToken(secret.Auth.ClientToken)
+	ttl := time.Duration(secret.Auth.LeaseDuration) * time.Second
+	s.expires = time.Now().Add(ttl - ttl/10)
+	return nil
+}
+
+func (s *Credentials) Read(ctx context.Context, reference api.OpenBaoSecretReference) (instance.Credentials, error) {
+	// Login and reads share a lock so concurrent first-use requests cannot race token replacement.
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if !time.Now().Before(s.expires) {
+		if err := s.login(ctx); err != nil {
+			return instance.Credentials{}, err
+		}
+	}
+	secret, err := s.client.KVv2(s.mount).Get(ctx, reference.Path)
+	var response *bao.ResponseError
+	if errors.As(err, &response) && response.StatusCode == 403 {
+		// A token may be revoked before its TTL. Reauthenticate once, never loop on denied policies.
+		s.expires = time.Time{}
+		if err := s.login(ctx); err != nil {
+			return instance.Credentials{}, err
+		}
+		secret, err = s.client.KVv2(s.mount).Get(ctx, reference.Path)
+	}
+	if err != nil {
+		return instance.Credentials{}, classify("read administrative credential", err, false)
+	}
+	usernameKey, passwordKey := reference.UsernameKey, reference.PasswordKey
+	if usernameKey == "" {
+		usernameKey = "username"
+	}
+	if passwordKey == "" {
+		passwordKey = "password"
+	}
+	if secret == nil {
+		return instance.Credentials{}, invalidCredential()
+	}
+	username, usernameOK := secret.Data[usernameKey].(string)
+	password, passwordOK := secret.Data[passwordKey].(string)
+	if !usernameOK || !passwordOK || username == "" || password == "" {
+		return instance.Credentials{}, invalidCredential()
+	}
+	return instance.Credentials{Username: username, Password: password}, nil
+}
+
+func invalidCredential() error {
+	return instance.Failure{Reason: api.ReasonAuthenticationFailed, Operation: "administrative credential fields are missing"}
+}
+
+func classify(operation string, err error, login bool) error {
+	reason := api.ReasonDependencyUnavailable
+	var safe instance.Failure
+	if errors.As(err, &safe) {
+		return safe
+	}
+	var response *bao.ResponseError
+	if errors.As(err, &response) {
+		switch response.StatusCode {
+		case 403:
+			reason = api.ReasonInsufficientPrivileges
+			if login {
+				reason = api.ReasonAuthenticationFailed
+			}
+		case 400, 401:
+			reason = api.ReasonAuthenticationFailed
+		case 404:
+			reason = api.ReasonInvalidSpec
+		}
+	}
+	return instance.Failure{Reason: reason, Operation: operation}
+}

internal/openbao/credentials_test.go

@@ -0,0 +1,125 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package openbao
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	api "git.ddupan.top/panxiao81/postgresql-tenant-operator/api/v1alpha1"
+	bao "github.com/openbao/openbao/api/v2"
+)
+
+const testToken = "test-token"
+const testAdmin = "admin"
+
+func TestSharedIdentityReauthenticatesOnExpiryAndRevocation(t *testing.T) {
+	var logins atomic.Int32
+	var revoked atomic.Bool
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/secret/data/admin" {
+			http.NotFound(w, r)
+			return
+		}
+		if revoked.Swap(false) {
+			w.WriteHeader(http.StatusForbidden)
+			return
+		}
+		if r.Header.Get("X-Vault-Token") != testToken {
+			w.WriteHeader(http.StatusForbidden)
+			return
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"data": map[string]any{
+				"data":     map[string]any{"username": testAdmin, "password": "test-password"},
+				"metadata": map[string]any{"version": 1},
+			},
+		})
+	}))
+	defer server.Close()
+	config := bao.NewConfig()
+	config.Address = server.URL
+	config.MaxRetries = 0
+	client, err := bao.NewClient(config)
+	if err != nil {
+		t.Fatal(err)
+	}
+	source := NewCredentials(client, "secret", "kubernetes", "controller")
+	source.authenticate = func(context.Context) (*bao.Secret, error) {
+		logins.Add(1)
+		return &bao.Secret{Auth: &bao.SecretAuth{ClientToken: testToken, LeaseDuration: 300}}, nil
+	}
+	reference := api.OpenBaoSecretReference{Path: testAdmin}
+	var wg sync.WaitGroup
+	for range 8 {
+		wg.Go(func() {
+			if _, err := source.Read(context.Background(), reference); err != nil {
+				t.Error(err)
+			}
+		})
+	}
+	wg.Wait()
+	if logins.Load() != 1 {
+		t.Fatal("concurrent reads repeatedly authenticated")
+	}
+	source.expires = time.Time{}
+	if _, err := source.Read(context.Background(), reference); err != nil {
+		t.Fatal(err)
+	}
+	if logins.Load() != 2 {
+		t.Fatal("expired identity was not refreshed")
+	}
+	revoked.Store(true)
+	if _, err := source.Read(context.Background(), reference); err != nil {
+		t.Fatal(err)
+	}
+	if logins.Load() != 3 {
+		t.Fatal("revoked identity was not refreshed")
+	}
+}
+
+func TestDeniedPolicyRetriesAuthenticationOnlyOnce(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusForbidden)
+	}))
+	defer server.Close()
+	config := bao.NewConfig()
+	config.Address = server.URL
+	config.MaxRetries = 0
+	client, err := bao.NewClient(config)
+	if err != nil {
+		t.Fatal(err)
+	}
+	source := NewCredentials(client, "secret", "kubernetes", "controller")
+	logins := 0
+	source.authenticate = func(context.Context) (*bao.Secret, error) {
+		logins++
+		return &bao.Secret{Auth: &bao.SecretAuth{ClientToken: testToken, LeaseDuration: 300}}, nil
+	}
+	if _, err := source.Read(context.Background(), api.OpenBaoSecretReference{Path: testAdmin}); err == nil {
+		t.Fatal("denied policy was accepted")
+	}
+	if logins != 2 {
+		t.Fatal("authentication did not stop after one retry")
+	}
+}

internal/postgresql/connection.go

@@ -0,0 +1,105 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package postgresql
+
+import (
+	"context"
+	"crypto/x509"
+	"errors"
+	"net"
+	"net/url"
+	"strconv"
+
+	api "git.ddupan.top/panxiao81/postgresql-tenant-operator/api/v1alpha1"
+	"git.ddupan.top/panxiao81/postgresql-tenant-operator/internal/instance"
+	"git.ddupan.top/panxiao81/postgresql-tenant-operator/internal/postgresql/registry"
+	"github.com/jackc/pgx/v5/pgconn"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// Connector is configured once with the deployment trust bundle.
+type Connector struct{ CABundlePath string }
+
+func (c Connector) Connect(ctx context.Context, endpoint api.PostgreSQLEndpoint, credentials instance.Credentials) (instance.Database, error) {
+	if endpoint.SSLMode != api.PostgreSQLSSLModeDisable && c.CABundlePath == "" {
+		return nil, instance.Failure{Reason: api.ReasonInvalidSpec, Operation: "PostgreSQL TLS requires a CA bundle"}
+	}
+	address := &url.URL{
+		Scheme: "postgresql",
+		Host:   net.JoinHostPort(endpoint.Host, strconv.Itoa(int(endpoint.Port))),
+		Path:   endpoint.Database,
+	}
+	query := address.Query()
+	query.Set("sslmode", string(endpoint.SSLMode))
+	if endpoint.SSLMode != api.PostgreSQLSSLModeDisable {
+		query.Set("sslrootcert", c.CABundlePath)
+	}
+	address.RawQuery = query.Encode()
+	config, err := pgxpool.ParseConfig(address.String())
+	if err != nil {
+		return nil, classify("configure PostgreSQL connection", err)
+	}
+	// Avoid embedding credentials in the driver's original connection string.
+	config.ConnConfig.User = credentials.Username
+	config.ConnConfig.Password = credentials.Password
+	config.MaxConns = 2
+	pool, err := pgxpool.NewWithConfig(ctx, config)
+	if err != nil {
+		return nil, classify("create PostgreSQL pool", err)
+	}
+	// Pool construction is lazy. Version performs the first authenticated query.
+	return &Database{pool: pool}, nil
+}
+
+type Database struct{ pool *pgxpool.Pool }
+
+func (d *Database) Version(ctx context.Context) (string, error) {
+	var version string
+	if err := d.pool.QueryRow(ctx, "SHOW server_version").Scan(&version); err != nil {
+		return "", classify("read PostgreSQL server version", err)
+	}
+	return version, nil
+}
+
+func (d *Database) EnsureRegistry(ctx context.Context) error {
+	if err := registry.NewStore(d.pool).Bootstrap(ctx); err != nil {
+		return classify("initialize PostgreSQL registry", err)
+	}
+	return nil
+}
+
+func (d *Database) Close() { d.pool.Close() }
+
+func classify(operation string, err error) error {
+	reason := api.ReasonDependencyUnavailable
+	var pgError *pgconn.PgError
+	var unknownCA x509.UnknownAuthorityError
+	var hostname x509.HostnameError
+	var invalidCertificate x509.CertificateInvalidError
+	switch {
+	case errors.As(err, &pgError):
+		switch pgError.Code {
+		case "28P01", "28000":
+			reason = api.ReasonAuthenticationFailed
+		case "42501":
+			reason = api.ReasonInsufficientPrivileges
+		}
+	case errors.As(err, &unknownCA), errors.As(err, &hostname), errors.As(err, &invalidCertificate):
+		reason = api.ReasonAuthenticationFailed
+	}
+	return instance.Failure{Reason: reason, Operation: operation}
+}

internal/postgresql/connection_test.go

@@ -0,0 +1,53 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package postgresql
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+	"testing"
+
+	api "git.ddupan.top/panxiao81/postgresql-tenant-operator/api/v1alpha1"
+	"git.ddupan.top/panxiao81/postgresql-tenant-operator/internal/instance"
+	"github.com/jackc/pgx/v5/pgconn"
+)
+
+const testCanary = "canary-secret"
+
+func TestDatabaseFailuresDoNotLeakDriverMessages(t *testing.T) {
+	tests := []struct {
+		err    error
+		reason string
+	}{
+		{context.DeadlineExceeded, api.ReasonDependencyUnavailable},
+		{&pgconn.PgError{Code: "28P01", Message: testCanary}, api.ReasonAuthenticationFailed},
+		{&pgconn.PgError{Code: "42501", Message: testCanary}, api.ReasonInsufficientPrivileges},
+		{&pgconn.PgError{Code: "53300", Message: testCanary}, api.ReasonDependencyUnavailable},
+	}
+	for _, tt := range tests {
+		err := classify("database operation", fmt.Errorf("driver canary-secret: %w", tt.err))
+		var failure instance.Failure
+		if !errors.As(err, &failure) || failure.Reason != tt.reason {
+			t.Fatal("wrong error category")
+		}
+		if strings.Contains(fmt.Sprintf("%+v %#v", err, err), "canary") {
+			t.Fatal("driver message escaped")
+		}
+	}
+}