Skip to content

PostgreSQL backup tool with Point-In-Time-Recovery and restore verification

FIX (healthcheck): Probe physical sources over a plain connection, so a backup holding every WAL sender slot no longer turns the healthcheck red

Rostislav Duginfbe7718a34ef
diff --git a/backend/internal/features/databases/databases/postgresql/physical/model.go b/backend/internal/features/databases/databases/postgresql/physical/model.go
index bff923ca..27c41911 100644
--- a/backend/internal/features/databases/databases/postgresql/physical/model.go
+++ b/backend/internal/features/databases/databases/postgresql/physical/model.go
@@ -310,6 +310,32 @@ func (p *PostgresqlPhysicalDatabase) TestReplicationConnection(
return p.checkReplicationReadiness(logger, encryptor)
}
+// ProbeLiveness answers only whether the source accepts the stored credentials. It deliberately
+// avoids a replication connection: that would take a WAL sender slot, which on a source sized
+// tightly for its replicas makes the probe fail during every backup and can starve the backup
+// itself. Replication readiness stays the job of TestReplicationConnection.
+func (p *PostgresqlPhysicalDatabase) ProbeLiveness(
+ ctx context.Context,
+ logger *slog.Logger,
+ encryptor encryption.FieldEncryptor,
+) error {
+ ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
+ defer cancel()
+
+ conn, err := openConn(ctx, p, encryptor)
+ if err != nil {
+ return fmt.Errorf("failed to connect to the source: %w", err)
+ }
+ defer closeConnQuietly(ctx, conn, logger)
+
+ var result int
+ if err := conn.QueryRow(ctx, "SELECT 1").Scan(&result); err != nil {
+ return fmt.Errorf("failed to query the source: %w", err)
+ }
+
+ return nil
+}
+
// VerifyWalSlot ensures a physical replication slot named p.ReplicationSlotName
// exists on the target cluster. Idempotent: a second call after first create
// is a no-op. Caller is the backup runner — slot existence is a backup-time
diff --git a/backend/internal/features/databases/databases/postgresql/physical/model_test.go b/backend/internal/features/databases/databases/postgresql/physical/model_test.go
index 222b25de..87716751 100644
--- a/backend/internal/features/databases/databases/postgresql/physical/model_test.go
+++ b/backend/internal/features/databases/databases/postgresql/physical/model_test.go
@@ -655,6 +655,49 @@ func Test_TestReplicationConnection_HostAllButNoReplicationHba_ReturnsPgHbaNoEnt
}
}
+func Test_ProbeLiveness_WhenWalSendersExhausted_Succeeds(t *testing.T) {
+ for _, fx := range physicalFixtures() {
+ t.Run(fx.name, func(t *testing.T) {
+ source := containers.StartPhysicalPostgres(t, fx.image, containers.WithMaxWalSenders(1))
+ m := newTestModelAt(t, source.Host, source.Port)
+
+ ctx, cancel := context.WithTimeout(t.Context(), 30*time.Second)
+ defer cancel()
+
+ // Stands in for the backup or WAL stream that holds the source's only WAL sender slot.
+ slotHolder, err := openPhysicalReplicationConn(ctx, m, nil)
+ require.NoError(t, err)
+ defer func() { _ = slotHolder.Close(ctx) }()
+
+ require.Error(t, m.TestReplicationConnection(testLogger(), nil),
+ "the fixture must leave no WAL sender slot free, or the liveness assertion proves nothing")
+
+ assert.NoError(t, m.ProbeLiveness(ctx, testLogger(), nil))
+ })
+ }
+}
+
+func Test_ProbeLiveness_WhenPasswordIsWrong_FailsWithoutLeakingPassword(t *testing.T) {
+ for _, fx := range physicalFixtures() {
+ t.Run(fx.name, func(t *testing.T) {
+ if fx.port() == "" {
+ t.Fatalf("%s port not configured", fx.name)
+ }
+
+ wrongPassword := "wrong-password-" + uuid.NewString()
+
+ m := newTestModel(t, fx.port())
+ m.Password = wrongPassword
+
+ err := m.ProbeLiveness(t.Context(), testLogger(), nil)
+
+ require.Error(t, err)
+ assert.Contains(t, err.Error(), "password authentication failed")
+ assert.NotContains(t, err.Error(), wrongPassword)
+ })
+ }
+}
+
func connTestErrorCode(t *testing.T, err error) postgresql_shared.ConnectionErrorCode {
t.Helper()
diff --git a/backend/internal/features/databases/model.go b/backend/internal/features/databases/model.go
index b0f3d23a..e5feb161 100644
--- a/backend/internal/features/databases/model.go
+++ b/backend/internal/features/databases/model.go
@@ -145,6 +145,26 @@ func (d *Database) TestConnection(
}
}
+// ProbeLiveness backs the scheduled healthcheck. Only the physical type swaps its full connection
+// test for a plain liveness probe, because only its test opens a replication connection that
+// competes with backups for WAL sender slots; the other types share nothing with their backups and
+// keep the full test.
+func (d *Database) ProbeLiveness(
+ ctx context.Context,
+ logger *slog.Logger,
+ encryptor encryption.FieldEncryptor,
+) error {
+ if d.Type != DatabaseTypePostgresPhysical {
+ return d.TestConnection(logger, encryptor)
+ }
+
+ if d.PostgresqlPhysical == nil {
+ return errors.New("postgresql physical config is not set")
+ }
+
+ return d.PostgresqlPhysical.ProbeLiveness(ctx, logger, encryptor)
+}
+
func (d *Database) GetRawDbSizeMb(
ctx context.Context,
logger *slog.Logger,
diff --git a/backend/internal/features/databases/model_test.go b/backend/internal/features/databases/model_test.go
index 4d064d8d..3a23e37e 100644
--- a/backend/internal/features/databases/model_test.go
+++ b/backend/internal/features/databases/model_test.go
@@ -50,6 +50,36 @@ func Test_TestConnection_ForEveryDatabaseType_WithoutEngineConfig_ReturnsErrorIn
}
}
+func Test_ProbeLiveness_ForEveryDatabaseType_WithoutEngineConfig_ReturnsErrorInsteadOfPanicking(
+ t *testing.T,
+) {
+ missingConfigCases := []struct {
+ databaseType DatabaseType
+ errorMessage string
+ }{
+ {DatabaseTypePostgresLogical, "postgresql logical config is not set"},
+ {DatabaseTypePostgresPhysical, "postgresql physical config is not set"},
+ {DatabaseTypeMysql, "mysql config is not set"},
+ {DatabaseTypeMariadb, "mariadb config is not set"},
+ {DatabaseTypeMongodb, "mongodb config is not set"},
+ {DatabaseType("CASSANDRA"), "connection test not supported for database type: CASSANDRA"},
+ }
+
+ for _, missingConfigCase := range missingConfigCases {
+ t.Run(string(missingConfigCase.databaseType), func(t *testing.T) {
+ databaseWithoutConfig := Database{Type: missingConfigCase.databaseType}
+
+ err := databaseWithoutConfig.ProbeLiveness(
+ t.Context(),
+ logger.GetLogger(),
+ encryption.GetFieldEncryptor(),
+ )
+
+ assert.EqualError(t, err, missingConfigCase.errorMessage)
+ })
+ }
+}
+
func Test_GetRawDbSizeMb_ForEveryDatabaseType_WithoutEngineConfig_ReturnsErrorInsteadOfPanicking(
t *testing.T,
) {
diff --git a/backend/internal/features/databases/service.go b/backend/internal/features/databases/service.go
index e2af75ce..8e4f87df 100644
--- a/backend/internal/features/databases/service.go
+++ b/backend/internal/features/databases/service.go
@@ -485,11 +485,28 @@ func (s *DatabaseService) TestDatabaseConnectionDirect(
return s.testDatabaseConnection(ctx, usingDatabase)
}
-func (s *DatabaseService) TestTrustedDatabaseConnection(
+func (s *DatabaseService) ProbeDatabaseLiveness(
ctx context.Context,
database *Database,
) error {
- return s.testDatabaseConnection(ctx, database)
+ if database == nil {
+ return errors.New("database is required")
+ }
+
+ logger := s.logger.With("database_id", database.ID)
+
+ tunneledDatabase, err := OpenTunnel(ctx, OpenTunnelSpec{
+ Database: database,
+ Logger: logger,
+ Encryptor: s.fieldEncryptor,
+ })
+ if err != nil {
+ return err
+ }
+
+ defer tunneledDatabase.Close()
+
+ return tunneledDatabase.GetDatabaseThroughTunnel().ProbeLiveness(ctx, logger, s.fieldEncryptor)
}
func (s *DatabaseService) GetDatabaseByID(
diff --git a/backend/internal/features/databases/service_test.go b/backend/internal/features/databases/service_test.go
new file mode 100644
index 00000000..96f53e4e
--- /dev/null
+++ b/backend/internal/features/databases/service_test.go
@@ -0,0 +1,49 @@
+package databases
+
+import (
+ "testing"
+
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+
+ postgresql_physical "databasus-backend/internal/features/databases/databases/postgresql/physical"
+ "databasus-backend/internal/util/testing/bastion"
+ "databasus-backend/internal/util/testing/containers"
+)
+
+// The healthcheck path runs without an end-user principal, so the embedded-target refusal inside
+// OpenTunnel is the only thing keeping a persisted row from probing Databasus's own cluster.
+func Test_ProbeDatabaseLiveness_WithEmbeddedPhysicalTarget_ReturnsError(t *testing.T) {
+ database := &Database{
+ Type: DatabaseTypePostgresPhysical,
+ PostgresqlPhysical: &postgresql_physical.PostgresqlPhysicalDatabase{
+ Host: "/tmp",
+ Port: 5437,
+ Username: "postgres",
+ Password: "stored-password",
+ },
+ }
+
+ err := GetDatabaseService().ProbeDatabaseLiveness(t.Context(), database)
+
+ require.ErrorContains(t, err, "backing up Databasus internal PostgreSQL cluster is not allowed")
+}
+
+// The source cluster publishes no port, so a passing probe proves it went through the bastion.
+func Test_ProbeDatabaseLiveness_WhenSourceIsBehindSshBastion_Succeeds(t *testing.T) {
+ topology := containers.StartPhysicalPostgresBehindSshBastion(t, "postgres:17")
+
+ physicalConfig := GetTestPhysicalPostgresConfigWithType(
+ topology.Database.Host, topology.Database.Port, "17", postgresql_physical.BackupTypeFullOnly,
+ )
+ physicalConfig.SshTunnel = bastion.GetTunnelConfig(topology)
+
+ database := &Database{
+ Type: DatabaseTypePostgresPhysical,
+ PostgresqlPhysical: physicalConfig,
+ }
+
+ err := GetDatabaseService().ProbeDatabaseLiveness(t.Context(), database)
+
+ assert.NoError(t, err)
+}
diff --git a/backend/internal/features/healthcheck/attempt/check_database_health_uc.go b/backend/internal/features/healthcheck/attempt/check_database_health_uc.go
index e778b7ba..6d4b3e51 100644
--- a/backend/internal/features/healthcheck/attempt/check_database_health_uc.go
+++ b/backend/internal/features/healthcheck/attempt/check_database_health_uc.go
@@ -154,7 +154,7 @@ func (uc *CheckDatabaseHealthUseCase) healthcheckDatabase(
// A database being down is the condition this probe exists to detect, and the caller reports it
// too, so it is a tolerated finding here rather than something needing attention.
- if err := uc.databaseService.TestTrustedDatabaseConnection(ctx, database); err != nil {
+ if err := uc.databaseService.ProbeDatabaseLiveness(ctx, database); err != nil {
healthStatus = databases.HealthStatusUnavailable
logger.WarnContext(ctx, "database healthcheck probe failed", "error", err)
diff --git a/backend/internal/features/healthcheck/attempt/check_database_health_uc_test.go b/backend/internal/features/healthcheck/attempt/check_database_health_uc_test.go
index 9070b199..5d494da1 100644
--- a/backend/internal/features/healthcheck/attempt/check_database_health_uc_test.go
+++ b/backend/internal/features/healthcheck/attempt/check_database_health_uc_test.go
@@ -89,7 +89,7 @@ func Test_CheckDatabaseHealthUseCase(t *testing.T) {
// Setup mock database service
mockDatabaseService := &MockDatabaseService{}
- mockDatabaseService.On("TestTrustedDatabaseConnection", database).
+ mockDatabaseService.On("ProbeDatabaseLiveness", database).
Return(errors.New("test error"))
unavailableStatus := databases.HealthStatusUnavailable
mockDatabaseService.On("SetHealthStatus", database.ID, &unavailableStatus).
@@ -151,7 +151,7 @@ func Test_CheckDatabaseHealthUseCase(t *testing.T) {
// Setup mock database service - connection fails but SetHealthStatus should not be called
mockDatabaseService := &MockDatabaseService{}
- mockDatabaseService.On("TestTrustedDatabaseConnection", database).
+ mockDatabaseService.On("ProbeDatabaseLiveness", database).
Return(errors.New("test error"))
mockDatabaseService.On("GetDatabaseByID", database.ID).
Return(database, nil)
@@ -220,7 +220,7 @@ func Test_CheckDatabaseHealthUseCase(t *testing.T) {
// Setup mock database service
mockDatabaseService := &MockDatabaseService{}
- mockDatabaseService.On("TestTrustedDatabaseConnection", database).
+ mockDatabaseService.On("ProbeDatabaseLiveness", database).
Return(errors.New("test error"))
unavailableStatus := databases.HealthStatusUnavailable
mockDatabaseService.On("SetHealthStatus", database.ID, &unavailableStatus).
@@ -297,7 +297,7 @@ func Test_CheckDatabaseHealthUseCase(t *testing.T) {
// Setup mock database service - connection succeeds
mockDatabaseService := &MockDatabaseService{}
- mockDatabaseService.On("TestTrustedDatabaseConnection", database).Return(nil)
+ mockDatabaseService.On("ProbeDatabaseLiveness", database).Return(nil)
availableStatus := databases.HealthStatusAvailable
mockDatabaseService.On("SetHealthStatus", database.ID, &availableStatus).
Return(nil)
@@ -359,7 +359,7 @@ func Test_CheckDatabaseHealthUseCase(t *testing.T) {
// Setup mock database service - connection succeeds
mockDatabaseService := &MockDatabaseService{}
- mockDatabaseService.On("TestTrustedDatabaseConnection", database).Return(nil)
+ mockDatabaseService.On("ProbeDatabaseLiveness", database).Return(nil)
availableStatus := databases.HealthStatusAvailable
mockDatabaseService.On("SetHealthStatus", database.ID, &availableStatus).
Return(nil)
@@ -510,7 +510,7 @@ func Test_CheckDatabaseHealthUseCase(t *testing.T) {
mockSender.On("SendNotification", mock.Anything, mock.Anything).Return()
mockDatabaseService := &MockDatabaseService{}
- mockDatabaseService.On("TestTrustedDatabaseConnection", database).
+ mockDatabaseService.On("ProbeDatabaseLiveness", database).
Return(errors.New("replication connection refused"))
unavailableStatus := databases.HealthStatusUnavailable
mockDatabaseService.On("SetHealthStatus", database.ID, &unavailableStatus).Return(nil)
diff --git a/backend/internal/features/healthcheck/attempt/interfaces.go b/backend/internal/features/healthcheck/attempt/interfaces.go
index 54d5cbad..24bbd9bd 100644
--- a/backend/internal/features/healthcheck/attempt/interfaces.go
+++ b/backend/internal/features/healthcheck/attempt/interfaces.go
@@ -21,7 +21,7 @@ type HealthcheckAttemptSender interface {
type DatabaseService interface {
GetDatabaseByID(id uuid.UUID) (*databases.Database, error)
- TestTrustedDatabaseConnection(ctx context.Context, database *databases.Database) error
+ ProbeDatabaseLiveness(ctx context.Context, database *databases.Database) error
SetHealthStatus(
databaseID uuid.UUID,
diff --git a/backend/internal/features/healthcheck/attempt/mocks.go b/backend/internal/features/healthcheck/attempt/mocks.go
index 8db587cd..5f40c660 100644
--- a/backend/internal/features/healthcheck/attempt/mocks.go
+++ b/backend/internal/features/healthcheck/attempt/mocks.go
@@ -27,7 +27,7 @@ type MockDatabaseService struct {
mock.Mock
}
-func (m *MockDatabaseService) TestTrustedDatabaseConnection(
+func (m *MockDatabaseService) ProbeDatabaseLiveness(
ctx context.Context,
database *databases.Database,
) error {
diff --git a/backend/internal/util/testing/containers/postgres_physical.go b/backend/internal/util/testing/containers/postgres_physical.go
index b10f3a2a..849ef34a 100644
--- a/backend/internal/util/testing/containers/postgres_physical.go
+++ b/backend/internal/util/testing/containers/postgres_physical.go
@@ -39,6 +39,7 @@ type physicalPostgresOptions struct {
shouldOmitReplicationHbaEntry bool
shouldSpreadCheckpoints bool
maxConnections int
+ maxWalSenders int
}
// PhysicalPostgresOption tunes a physical source container away from its replication-ready default.
@@ -70,6 +71,12 @@ func WithMaxConnections(connections int) PhysicalPostgresOption {
return func(o *physicalPostgresOptions) { o.maxConnections = connections }
}
+// WithMaxWalSenders caps the cluster's WAL sender slots so a test can hold all of them and observe
+// what a further replication connection, or a probe that must not need one, does at the limit.
+func WithMaxWalSenders(walSenders int) PhysicalPostgresOption {
+ return func(o *physicalPostgresOptions) { o.maxWalSenders = walSenders }
+}
+
// A promotion only requests its checkpoint, so on a node carrying dirty buffers that request stays
// outstanding for the length of a test and pg_control_checkpoint() keeps answering the pre-failover
// timeline — the stale reading a timeline probe must not trust. The completion target is pinned so
@@ -120,10 +127,16 @@ func physicalPostgresCmd(opts physicalPostgresOptions) []string {
fullPageWrites = "full_page_writes=on"
}
+ maxWalSenders := 10
+ if opts.maxWalSenders > 0 {
+ maxWalSenders = opts.maxWalSenders
+ }
+
cmd := []string{
"-c", "fsync=off", "-c", fullPageWrites, "-c", "synchronous_commit=off",
"-c", "wal_level=logical", "-c", summarize,
- "-c", "max_wal_senders=10", "-c", "max_replication_slots=10", "-c", "wal_keep_size=512MB",
+ "-c", fmt.Sprintf("max_wal_senders=%d", maxWalSenders),
+ "-c", "max_replication_slots=10", "-c", "wal_keep_size=512MB",
}
if opts.maxConnections > 0 {
cmd = append(cmd, "-c", fmt.Sprintf("max_connections=%d", opts.maxConnections))
diff --git a/openspec/changes/archive/2026-10-10-physical-healthcheck-liveness-probe/.openspec.yaml b/openspec/changes/archive/2026-10-10-physical-healthcheck-liveness-probe/.openspec.yaml
new file mode 100644
index 00000000..53f62d70
--- /dev/null
+++ b/openspec/changes/archive/2026-10-10-physical-healthcheck-liveness-probe/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-10
diff --git a/openspec/changes/archive/2026-10-10-physical-healthcheck-liveness-probe/design.md b/openspec/changes/archive/2026-10-10-physical-healthcheck-liveness-probe/design.md
new file mode 100644
index 00000000..4336834f
--- /dev/null
+++ b/openspec/changes/archive/2026-10-10-physical-healthcheck-liveness-probe/design.md
@@ -0,0 +1,81 @@
+## Context
+
+See proposal.md for the motivation and the reproduction.
+
+The healthcheck reaches the source through one chain, and every link except the last is shared with the user-facing connection test:
+
+- `CheckDatabaseHealthUseCase.healthcheckDatabase` calls `DatabaseService.TestTrustedDatabaseConnection` (`backend/internal/features/healthcheck/attempt/check_database_health_uc.go:157`), declared on the healthcheck's own interface (`backend/internal/features/healthcheck/attempt/interfaces.go:24`) and mocked in `backend/internal/features/healthcheck/attempt/mocks.go:30`.
+- `TestTrustedDatabaseConnection` (`backend/internal/features/databases/service.go:488`) is called by the healthcheck only. It delegates to the private `testDatabaseConnection` (`service.go:965`), which opens the SSH tunnel when one is configured and calls `Database.TestConnection` on the tunneled copy. The workspace-authorized connection test shares `testDatabaseConnection` (`service.go:485`).
+- `Database.TestConnection` (`backend/internal/features/databases/model.go:108`) dispatches by type. For a physical source it calls `TestReplicationConnection` (`backend/internal/features/databases/databases/postgresql/physical/model.go:306`), which runs `checkReplicationReadiness` (`model.go:836`). That check opens a replication connection, then an ordinary one, and on it runs up to four queries covering seven checks: custom tablespaces, `wal_level`, `max_wal_senders`, `max_replication_slots` and `summarize_wal` from one settings read, the `pg_switch_wal` privilege (WAL streaming only), and the cluster system identifier (only when one is stored).
+
+An ordinary connection to the source already exists as `openConn` (`backend/internal/features/databases/databases/postgresql/physical/connection.go:18`). It is the same connection the readiness check opens with the same credentials and TLS files, so any source that passes readiness today also accepts it.
+
+Constraints from `backend/AGENTS.md`: test names follow `Test_WhatWeDo_WhichConditions_WhatWeExpect`; tests live next to their source, not in `internal/features/tests/`, which is reserved for backup and restore cycles; errors go to logs as key-value pairs, and passwords never do.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- A physical source healthcheck that cannot be turned red by WAL sender exhaustion and cannot exhaust WAL senders itself.
+- The probe's failure reason reaches the existing `database healthcheck probe failed` log entry.
+
+**Non-Goals:**
+
+- Any change to the probe of other database types, which keep running their full `TestConnection`.
+- Any change to the readiness check or to its error classification.
+
+## Decisions
+
+### Decision 1: The physical healthcheck probes liveness with an ordinary connection and `SELECT 1`
+
+A new `PostgresqlPhysicalDatabase.ProbeLiveness(ctx, logger, encryptor)` in `postgresql/physical/model.go`, next to `TestReplicationConnection`, opens the connection through `openConn`, runs `SELECT 1`, and closes the connection. It bounds itself with a 30-second timeout derived from the caller's context, matching the readiness check's budget, so a hung source cannot stall a healthcheck goroutine past the next tick.
+
+Alternatives rejected:
+
+- **Keep the replication probe and treat the `max_wal_senders` refusal as available.** PostgreSQL refuses a surplus WAL sender before it authenticates the client, so such a pass would not even prove the credentials still work. The probe would also keep taking a WAL sender slot when one is free, which is the half of the problem that can fail a backup.
+- **Skip the healthcheck while a backup or WAL stream runs.** Continuous WAL streaming runs permanently, so the healthcheck would never run on a streaming database. It would also couple the healthcheck to backup scheduling state it does not own today.
+- **Keep the readiness checks but run them over the ordinary connection only.** This drops the WAL sender, but keeps re-validating configuration every minute. A transient failure of any of the inspection queries, or a configuration change already reported through the backups, would still paint the database red. The healthcheck exists to answer whether the source is up. Configuration drift that matters breaks the next backup, which notifies on its own.
+
+### Decision 2: The type dispatch gains `Database.ProbeLiveness`, which overrides only the physical case
+
+`Database.ProbeLiveness(ctx, logger, encryptor)` calls `PostgresqlPhysical.ProbeLiveness` for a physical source, with the same nil-config guard `TestConnection` has ("postgresql physical config is not set"). For every other type it runs the full `Database.TestConnection`, so for those types "liveness" still means today's connection test, privileges included. The method's doc comment says so, so the name does not overpromise. The service's trusted path calls `ProbeLiveness` instead of `TestConnection`, keeping the tunnel handling and the embedded-target refusal that `OpenTunnel` already applies (`backend/internal/features/databases/tunneled_database.go:39`).
+
+Alternatives rejected:
+
+- **Branch on the physical type inside the service method.** The model already owns per-type dispatch (`model.go:108`). A second, partial dispatch in the service would be the one place a reader must remember to check when a type is added.
+- **Give every type its own lightweight liveness probe.** Logical PostgreSQL, MySQL, MariaDB and MongoDB have no reported false alarms and no shared replication capacity to protect. Changing them would widen the change with no observed benefit.
+
+### Decision 3: Name the healthcheck path `Probe...`, not `Test...`
+
+`TestTrustedDatabaseConnection` becomes `ProbeDatabaseLiveness`, and the two new model methods are `ProbeLiveness`, not `TestLiveness`. After this change the path no longer tests a connection the way the user-facing "Test connection" does, and a `Test...` name beside `TestConnection` would invite a future caller to use it as one. The healthcheck interface, its mock, the use case and its tests are renamed in the same change. The old name is deleted, per the project rule against unrequested backward compatibility. The private `testDatabaseConnection` stays for the workspace-authorized path, and the trusted path gets its own short body: open the tunnel, call `ProbeLiveness`.
+
+Alternative rejected:
+
+- **Keep the name.** That makes a smaller diff, but the name would then describe behavior the method no longer has, and the healthcheck is its only caller, so the rename touches one feature.
+
+### Decision 4: The probe returns the driver error unclassified
+
+`ProbeLiveness` returns the `pgx` connect or query error wrapped with context. It does not map it to a `ConnectionTestError` code, because no UI consumes the healthcheck's error, and only the log does. The use case already logs it as `"error", err`. `pgx` reports a connect failure as ``failed to connect to `user=... database=...` `` followed by the server's message, without the password, which keeps the spec's no-password requirement without ad hoc redaction.
+
+Alternative rejected:
+
+- **Reuse `classifyReplicationConnectError`.** Its default branch reduces most failures to a bare `CONNECTION_FAILED` code. That is the opacity that made this bug hard to diagnose.
+
+### Decision 5: Pin the behavior with a source whose WAL senders are exhausted
+
+The physical PostgreSQL test container gains a `WithMaxWalSenders(n)` option beside the existing `WithMaxConnections` (`backend/internal/util/testing/containers/postgres_physical.go`). The test starts a source with `max_wal_senders=1`, holds that one slot with an open replication connection, and asserts two things: `ProbeLiveness` succeeds, and `TestReplicationConnection` fails. The second assertion proves the fixture really exhausted the slots, so the first one is meaningful. A probe that took a WAL sender could not pass this test, which also covers the "backup starts while the healthcheck runs" scenario without a timing race.
+
+Alternative rejected:
+
+- **Reproduce with a real `pg_basebackup`.** That is slower and timing-dependent, and it proves nothing beyond what holding the slot proves.
+
+## Risks / Trade-offs
+
+- [The healthcheck stops noticing a removed `host replication` rule or a revoked `REPLICATION` attribute] → The next backup or WAL stream reconnect fails and sends its own failure notification. The user-facing connection test still reports both.
+- [A source that allows the ordinary connection but not replication now shows green while backups fail] → Same mitigation. The healthcheck promises reachability, and backup health has its own status and notifications.
+- [The healthcheck stops noticing a source swapped for a different cluster, for example after a DNS change, because it no longer compares the cluster system identifier (`backend/internal/features/databases/databases/postgresql/physical/model.go:910-920`); it also stops noticing drift in `wal_level` or `summarize_wal` and a newly created custom tablespace] → Backup preflight still compares the identity and refuses to write a backup on a mismatch, pausing scheduling and reporting `SYSTEM_IDENTIFIER_MISMATCH` (`openspec/specs/postgresql-physical-backup-failover/spec.md`). Configuration drift fails the next backup, which notifies.
+- [The rename breaks an out-of-tree caller] → The healthcheck is the only caller in the repository, and the method is internal to the backend binary.
+
+## Migration Plan
+
+No data or schema migration. Healthcheck attempts recorded before the deploy stay as they are, and the next tick after the deploy uses the new probe. Rollback is a plain revert.
diff --git a/openspec/changes/archive/2026-10-10-physical-healthcheck-liveness-probe/proposal.md b/openspec/changes/archive/2026-10-10-physical-healthcheck-liveness-probe/proposal.md
new file mode 100644
index 00000000..c097f252
--- /dev/null
+++ b/openspec/changes/archive/2026-10-10-physical-healthcheck-liveness-probe/proposal.md
@@ -0,0 +1,38 @@
+## Why
+
+The scheduled healthcheck of a PostgreSQL physical database turns red while a backup is running, even though the backup itself succeeds. The probe runs the full replication-readiness check, and that check opens a replication connection, which takes a WAL sender slot exactly as `pg_basebackup` and `pg_receivewal` do. On a source whose `max_wal_senders` leaves no spare slot during a backup, PostgreSQL rejects the probe with `number of requested standby connections exceeds "max_wal_senders"`, and the attempt is recorded as unavailable.
+
+This was reproduced on PostgreSQL 17 with `max_wal_senders=2`: the probe passed with only `pg_receivewal` attached, failed while `pg_basebackup` ran, and the backup exited 0. The same contention also works in reverse: a probe that holds the last slot when a backup or a `pg_receivewal` restart begins makes the backup fail. A false alarm that can also break the thing it watches is worth fixing now.
+
+## What Changes
+
+- The scheduled healthcheck of a physical database checks liveness only: it opens an ordinary connection with the stored credentials and runs a trivial query. It no longer opens a replication connection and no longer re-validates the source's replication configuration.
+- The full replication-readiness check stays where it is used today, in the user-facing connection test and when a database is created or updated.
+- The healthcheck of logical PostgreSQL, MySQL, MariaDB and MongoDB databases is unchanged.
+- When the liveness probe fails, the underlying error reaches the healthcheck log instead of being reduced to a bare code.
+- **BREAKING (internal only):** the database service method the healthcheck calls is renamed from `TestTrustedDatabaseConnection` to `ProbeDatabaseLiveness`, along with the healthcheck's service interface and mock. The healthcheck is its only caller; the old name is deleted, not kept as an alias. No HTTP API, schema or configuration changes.
+
+## Capabilities
+
+### New Capabilities
+
+- `physical-backups/source-healthcheck`: what the scheduled healthcheck of a PostgreSQL physical source checks, and that it never competes with backups for replication capacity on the source.
+
+### Modified Capabilities
+
+None. The `internal-postgresql-protection` requirement that healthchecks use a trusted internal path and still run embedded-target protection keeps holding unchanged.
+
+## Out of scope
+
+- Changing the healthcheck of any database type other than PostgreSQL physical.
+- Changing the user-facing connection test or the readiness checks run on create and update.
+- Preserving the underlying error in the readiness check's connect-error classifier, which today reduces most failures to a bare code. That is a separate observability fix for a follow-up change.
+- A dedicated error code or UI hint for an exhausted `max_wal_senders` in the connection test.
+- Storing the failure reason on healthcheck attempts or showing it in the attempts UI.
+- Notifications, healthcheck intervals, and the attempts-before-down logic.
+
+## Impact
+
+- Backend only: `backend/internal/features/databases` (database model and service), `backend/internal/features/databases/databases/postgresql/physical` (new liveness probe), `backend/internal/features/healthcheck/attempt` (interface, mock, use case and its tests), and the physical PostgreSQL test container helper, which gains a `max_wal_senders` option.
+- Answers to `AGENTS.md` and `backend/AGENTS.md`.
+- Trade-off: the healthcheck stops noticing a removed `host replication` rule in `pg_hba.conf`, a revoked `REPLICATION` attribute, drift in `wal_level` or `summarize_wal`, a new custom tablespace, and a source swapped for a different cluster. Backup preflight still refuses a cluster whose system identifier changed, and the rest surface as failed backups with their own notifications.
diff --git a/openspec/changes/archive/2026-10-10-physical-healthcheck-liveness-probe/specs/physical-backups/source-healthcheck/spec.md b/openspec/changes/archive/2026-10-10-physical-healthcheck-liveness-probe/specs/physical-backups/source-healthcheck/spec.md
new file mode 100644
index 00000000..666e0044
--- /dev/null
+++ b/openspec/changes/archive/2026-10-10-physical-healthcheck-liveness-probe/specs/physical-backups/source-healthcheck/spec.md
@@ -0,0 +1,65 @@
+## Purpose
+
+Defines what the scheduled healthcheck of a PostgreSQL physical source verifies, and guarantees that the healthcheck never competes with backups for replication capacity on that source.
+
+## ADDED Requirements
+
+### Requirement: The physical source healthcheck reports whether the source accepts the stored credentials
+
+The scheduled healthcheck of a PostgreSQL physical source SHALL record the source as available when the source accepts an ordinary connection with the stored credentials and answers a trivial query within the probe's time limit. It SHALL record the source as unavailable when the connection or the query fails or does not finish in time.
+
+The healthcheck SHALL NOT re-validate the source's replication configuration. WAL level, WAL sender and replication slot limits, WAL summarization, tablespaces, the WAL switch privilege and the cluster identity remain checked by the user-facing connection test and when a database is created or changed.
+
+#### Scenario: Reachable source
+
+- **WHEN** the healthcheck probes a physical source that accepts the stored credentials
+- **THEN** the attempt is recorded as available
+
+#### Scenario: Unreachable source
+
+- **WHEN** the healthcheck probes a physical source that is stopped or cannot be reached
+- **THEN** the attempt is recorded as unavailable
+
+#### Scenario: Rejected credentials
+
+- **WHEN** the healthcheck probes a physical source that rejects the stored password
+- **THEN** the attempt is recorded as unavailable
+
+#### Scenario: Source behind an SSH bastion
+
+- **WHEN** the physical source is configured to be reached through an SSH bastion
+- **THEN** the healthcheck reaches it through that bastion, as backups do
+
+### Requirement: The physical source healthcheck never uses replication capacity
+
+The scheduled healthcheck of a PostgreSQL physical source SHALL NOT open a replication connection to the source. A backup or a WAL stream running on the source SHALL NOT turn the healthcheck unavailable when the source has no WAL sender slot to spare, and the healthcheck SHALL NOT take a WAL sender slot that a backup or a WAL stream needs.
+
+#### Scenario: Backup holds the last WAL sender slot
+
+- **WHEN** a backup and a WAL stream occupy every WAL sender slot the source allows
+- **AND** the healthcheck probes that source
+- **THEN** the attempt is recorded as available
+
+#### Scenario: Backup starts while the healthcheck runs
+
+- **WHEN** the healthcheck is probing a source whose WAL sender slots are all taken except one
+- **AND** a backup starts at the same moment
+- **THEN** the backup obtains the remaining WAL sender slot
+
+### Requirement: A failed physical source healthcheck leaves its cause in the log
+
+When the healthcheck of a PostgreSQL physical source records an unavailable attempt, the reason the source gave SHALL appear in the application log entry for that attempt, so an operator can tell a refused password from a timeout or an unreachable host.
+
+#### Scenario: Refused connection
+
+- **WHEN** the source refuses the healthcheck connection
+- **THEN** the log entry for the failed attempt contains the source's refusal message
+
+### Requirement: The physical source healthcheck never writes the source password to the log
+
+No log entry produced by the healthcheck of a PostgreSQL physical source SHALL contain the stored password of that source, whether the probe succeeds or fails.
+
+#### Scenario: Wrong password rejected by the source
+
+- **WHEN** the stored password is wrong and the source rejects the healthcheck connection
+- **THEN** the log entry for the failed attempt does not contain that password
diff --git a/openspec/changes/archive/2026-10-10-physical-healthcheck-liveness-probe/tasks.md b/openspec/changes/archive/2026-10-10-physical-healthcheck-liveness-probe/tasks.md
new file mode 100644
index 00000000..d8256dcf
--- /dev/null
+++ b/openspec/changes/archive/2026-10-10-physical-healthcheck-liveness-probe/tasks.md
@@ -0,0 +1,28 @@
+## 1. Test fixture
+
+- [x] 1.1 Add a `WithMaxWalSenders(n)` option to the physical PostgreSQL test container beside `WithMaxConnections` in `backend/internal/util/testing/containers/postgres_physical.go`, overriding the hard-coded `max_wal_senders=10`. Verify with `go build ./...` from `backend/`.
+
+## 2. Liveness probe on the physical model
+
+- [x] 2.1 Add `PostgresqlPhysicalDatabase.ProbeLiveness(ctx, logger, encryptor)` in `postgresql/physical/model.go`, next to `TestReplicationConnection`: an ordinary connection through `openConn`, `SELECT 1`, a 30-second timeout derived from `ctx`, and the driver error returned wrapped and unclassified. Verify with `go build ./...` from `backend/`.
+- [x] 2.2 In `postgresql/physical/model_test.go`, add `Test_ProbeLiveness_WhenWalSendersExhausted_Succeeds`: start a source with `WithMaxWalSenders(1)`, hold the slot with an open replication connection, then assert that `ProbeLiveness` succeeds and that `TestReplicationConnection` fails, so the fixture is proven to have exhausted the slot. Verify with `go test ./internal/features/databases/databases/postgresql/physical/... -run Test_ProbeLiveness -count=1`.
+- [x] 2.3 In the same file, add `Test_ProbeLiveness_WhenPasswordIsWrong_FailsWithoutLeakingPassword`: the probe returns an error, the error carries the server's authentication refusal, and the error text does not contain the wrong password. Verify with the same command as 2.2.
+
+## 3. Type dispatch
+
+- [x] 3.1 Add `Database.ProbeLiveness(ctx, logger, encryptor)` in `databases/model.go`: a physical source with a nil `PostgresqlPhysical` returns "postgresql physical config is not set", a physical source calls `PostgresqlPhysical.ProbeLiveness`, and every other type runs `TestConnection`. The doc comment explains why non-physical types still run their full connection test: they share no replication capacity with backups, so nothing needs protecting there. Verify with `go build ./...` from `backend/`.
+- [x] 3.2 In `databases/model_test.go`, add `Test_ProbeLiveness_ForEveryDatabaseType_WithoutEngineConfig_ReturnsErrorInsteadOfPanicking`, mirroring the existing `TestConnection` case table. Verify with `go test ./internal/features/databases/ -run Test_ProbeLiveness -count=1`.
+
+## 4. Wire the healthcheck to the probe
+
+- [x] 4.1 Rename `DatabaseService.TestTrustedDatabaseConnection` to `ProbeDatabaseLiveness` and give it its own body: open the tunnel through `OpenTunnel`, then call `ProbeLiveness` on the tunneled copy. Leave `testDatabaseConnection` serving the workspace-authorized path only. Delete the old name. Verify that `grep -rn TestTrustedDatabaseConnection backend/` returns nothing and that `go build ./...` passes.
+- [x] 4.2 Rename the method on the healthcheck `DatabaseService` interface, on `MockDatabaseService`, at the call site in `CheckDatabaseHealthUseCase`, and in `check_database_health_uc_test.go`. Verify with `go test ./internal/features/healthcheck/... -count=1`.
+- [x] 4.3 In a new `databases/service_test.go`, add `Test_ProbeDatabaseLiveness_WithEmbeddedPhysicalTarget_ReturnsError`, which pins that the trusted path still refuses an embedded target before any connection opens. Verify with `go test ./internal/features/databases/ -run Test_ProbeDatabaseLiveness -count=1`.
+- [x] 4.4 In the same file, add `Test_ProbeDatabaseLiveness_WhenSourceIsBehindSshBastion_Succeeds`, using `containers.StartPhysicalPostgresBehindSshBastion`. Verify with the same command as 4.3.
+
+## 5. Verification and review
+
+- [x] 5.1 Run `make lint` in `backend/` and fix every finding in the touched files.
+- [x] 5.2 Run the touched packages from `backend/` and confirm that they pass: `go test ./internal/features/databases/... ./internal/features/healthcheck/... -count=1`.
+- [x] 5.3 Run the reviewer subagent on the working-tree diff and resolve every CHANGES REQUIRED finding.
+- [x] 5.4 Run `openspec validate physical-healthcheck-liveness-probe --strict` and confirm that it passes.
diff --git a/openspec/specs/physical-backups/source-healthcheck/spec.md b/openspec/specs/physical-backups/source-healthcheck/spec.md
new file mode 100644
index 00000000..b91202c8
--- /dev/null
+++ b/openspec/specs/physical-backups/source-healthcheck/spec.md
@@ -0,0 +1,67 @@
+# Source Healthcheck Specification
+
+## Purpose
+
+Defines what the scheduled healthcheck of a PostgreSQL physical source verifies, and guarantees that the healthcheck never competes with backups for replication capacity on that source.
+
+## Requirements
+
+### Requirement: The physical source healthcheck reports whether the source accepts the stored credentials
+
+The scheduled healthcheck of a PostgreSQL physical source SHALL record the source as available when the source accepts an ordinary connection with the stored credentials and answers a trivial query within the probe's time limit. It SHALL record the source as unavailable when the connection or the query fails or does not finish in time.
+
+The healthcheck SHALL NOT re-validate the source's replication configuration. WAL level, WAL sender and replication slot limits, WAL summarization, tablespaces, the WAL switch privilege and the cluster identity remain checked by the user-facing connection test and when a database is created or changed.
+
+#### Scenario: Reachable source
+
+- **WHEN** the healthcheck probes a physical source that accepts the stored credentials
+- **THEN** the attempt is recorded as available
+
+#### Scenario: Unreachable source
+
+- **WHEN** the healthcheck probes a physical source that is stopped or cannot be reached
+- **THEN** the attempt is recorded as unavailable
+
+#### Scenario: Rejected credentials
+
+- **WHEN** the healthcheck probes a physical source that rejects the stored password
+- **THEN** the attempt is recorded as unavailable
+
+#### Scenario: Source behind an SSH bastion
+
+- **WHEN** the physical source is configured to be reached through an SSH bastion
+- **THEN** the healthcheck reaches it through that bastion, as backups do
+
+### Requirement: The physical source healthcheck never uses replication capacity
+
+The scheduled healthcheck of a PostgreSQL physical source SHALL NOT open a replication connection to the source. A backup or a WAL stream running on the source SHALL NOT turn the healthcheck unavailable when the source has no WAL sender slot to spare, and the healthcheck SHALL NOT take a WAL sender slot that a backup or a WAL stream needs.
+
+#### Scenario: Backup holds the last WAL sender slot
+
+- **WHEN** a backup and a WAL stream occupy every WAL sender slot the source allows
+- **AND** the healthcheck probes that source
+- **THEN** the attempt is recorded as available
+
+#### Scenario: Backup starts while the healthcheck runs
+
+- **WHEN** the healthcheck is probing a source whose WAL sender slots are all taken except one
+- **AND** a backup starts at the same moment
+- **THEN** the backup obtains the remaining WAL sender slot
+
+### Requirement: A failed physical source healthcheck leaves its cause in the log
+
+When the healthcheck of a PostgreSQL physical source records an unavailable attempt, the reason the source gave SHALL appear in the application log entry for that attempt, so an operator can tell a refused password from a timeout or an unreachable host.
+
+#### Scenario: Refused connection
+
+- **WHEN** the source refuses the healthcheck connection
+- **THEN** the log entry for the failed attempt contains the source's refusal message
+
+### Requirement: The physical source healthcheck never writes the source password to the log
+
+No log entry produced by the healthcheck of a PostgreSQL physical source SHALL contain the stored password of that source, whether the probe succeeds or fails.
+
+#### Scenario: Wrong password rejected by the source
+
+- **WHEN** the stored password is wrong and the source rejects the healthcheck connection
+- **THEN** the log entry for the failed attempt does not contain that password