fix(databases): preserve encoded postgres credentials

[flemzord]

Summary

• preserve URL-encoded PostgreSQL credentials from Kubernetes Secrets by default, restoring the behavior expected before operator v3.12.0
• add an explicit secretCredentialsEncoding=raw mode for Secrets that contain raw credentials, and reject unsupported values
• expose the selected mode as POSTGRES_CREDENTIALS_ENCODING so Kubernetes rolls affected workloads when the behavior changes
• filter the internal encoding parameter from the final connection URI and document the v3.12.0 / Formance 1.15.0 upgrade behavior
• add regression coverage for raw, pre-encoded, and rollout-signal behavior and regenerate the CRD/settings artifacts

Context

Operator v3.12.0 started URL-encoding every Secret-backed database credential. Deployments that had already encoded special characters for earlier operator versions were therefore double-encoded (%5E became %255E) after upgrading through Formance Helm 1.15.0.

This keeps the legacy URL-encoded contract as the default because auto-detecting encoded credentials is ambiguous for literal %XX passwords. Users who store raw credentials can opt in explicitly with:

postgresql://postgres:5432?secret=postgres&secretCredentialsEncoding=raw

References TS-493. Related to #481.

Validation

• nix --extra-experimental-features "nix-command flakes" develop --impure --command just pre-commit
• nix --extra-experimental-features "nix-command flakes" develop --impure --command just tests

Risk

Deployments created on v3.12.0 that rely on raw credentials containing URI-special characters must add secretCredentialsEncoding=raw. Plain credentials without special characters are unchanged.

[NumaryBot]

✅ Approve — automated review

The credential-encoding fix correctly parses and applies urlEncoded/raw modes for PostgreSQL Secret-backed credentials, filters the internal query parameter from the generated URI, and is covered by tests. The rollout-signal concern raised in prior automated comments (Thread 1 and Thread 2) has been addressed: the reviewer notes that the added env-var change does cause a pod-spec difference when the encoding mode or its default behavior changes, meaning Kubernetes will detect the spec mutation and recreate affected pods automatically. No new blockers or major issues were identified in the latest review pass. The implementation appears ready to merge.

No findings.

[NumaryBot]

NumaryBot posted 1 new inline finding.

Summary: #488 (comment)

[coderabbitai]

Walkthrough

Adds secretCredentialsEncoding support for PostgreSQL credentials, including parsing, conditional escaping, reconciliation wiring, final URI cleanup, tests, and documentation for urlEncoded and raw modes.

Changes

PostgreSQL credential encoding

Layer / File(s)	Summary
Encoding contract and Secret generation api/..., internal/resources/databases/secret.go, internal/resources/databases/secret_test.go, docs/...	Defines urlEncoded and raw modes, validates the parameter, conditionally escapes credentials, and documents the default behavior and raw override.
Reconciliation wiring internal/resources/databases/init.go	Parses the encoding setting during reconciliation and pre-delete remediation, forwarding it to encoded Secret reconciliation.
Connection URI cleanup and validation internal/resources/databases/env.go, internal/resources/databases/env_test.go, internal/resources/databases/secret_test.go	Removes secretCredentialsEncoding from generated PostgreSQL query strings and updates related test cases.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Reconcile
  participant EncodingParser
  participant SecretReconciler
  participant KubernetesSecret
  Reconcile->>EncodingParser: Parse secretCredentialsEncoding
  EncodingParser-->>Reconcile: Return urlEncoded or raw
  Reconcile->>SecretReconciler: Pass credentials encoding
  SecretReconciler->>KubernetesSecret: Write processed credentials

Loading

Possibly related PRs

• formancehq/operator#484: Introduces the PostgreSQL credential Secret encoding infrastructure extended by this change.
• formancehq/operator#487: Adds related PostgreSQL credential Secret handling extended with configurable encoding.

Suggested reviewers: gfyrag, sylr, sofiasimdianova

Poem

I hop through queries, tidy and bright,
Raw or encoded, credentials take flight.
Secrets hold values just as they should,
URLs stay clean in the neighborhood.
Documentation blooms—what a wonderful view!
—A pleased little rabbit 🐇

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 6.25% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly matches the main change: preserving PostgreSQL credentials handling in databases.
Description check	✅ Passed	The description is directly related to the PR and summarizes the encoding behavior change and rollout considerations.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/ts-493-postgres-secret-encoding

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[NumaryBot]

NumaryBot posted 1 new inline finding.

Summary: #488 (comment)

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@internal/resources/databases/env.go`:
- Line 133: Ensure the credential-encoding migration triggers a rollout when
secret data changes: update the relevant pod/job template metadata with a
deterministic hash or equivalent annotation derived from the generated Secret
data, while retaining the delete of postgresCredentialsEncodingQueryParam in the
URI generation.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 517023cf-f4e6-40fc-a987-e8c87c396618

📥 Commits

Reviewing files that changed from the base of the PR and between b217145 and 4118b9d.

⛔ Files ignored due to path filters (3)

• config/crd/bases/formance.com_databases.yaml is excluded by !**/*.yaml
• docs/09-Configuration reference/settings.catalog.json is excluded by !**/*.json
• helm/crds/templates/crds/apiextensions.k8s.io_v1_customresourcedefinition_databases.formance.com.yaml is excluded by !**/*.yaml

📒 Files selected for processing (9)

• api/formance.com/v1beta1/database_types.go
• docs/07-Upgrade/01-Upgrade from the operator.md
• docs/09-Configuration reference/01-Settings.md
• docs/09-Configuration reference/02-Custom Resource Definitions.md
• internal/resources/databases/env.go
• internal/resources/databases/env_test.go
• internal/resources/databases/init.go
• internal/resources/databases/secret.go
• internal/resources/databases/secret_test.go

[NumaryBot]

NumaryBot review complete: no remaining inline findings.

Resolved 1 stale NumaryBot review thread (1 fixed, 0 outdated).

Summary: #488 (comment)