LCORE-973: PostgreSQL description

[tisnik]

Description

LCORE-973: PostgreSQL description

Type of change

• Refactor
• New feature
• Bug fix
• CVE fix
• Optimization
• Documentation Update
• Configuration Update
• Bump-up service version
• Bump-up dependent library
• Bump-up library or tool used for development (does not change the final image)
• CI configuration change
• Konflux configuration change
• Unit tests improvement
• Integration tests improvement
• End to end tests improvement

Tools used to create PR

Identify any AI code assistants used in this PR (for transparency and review context)

• Assisted-by: N/A
• Generated by: N/A

Related Tickets & Documents

• Related Issue #LCORE-973

Summary by CodeRabbit

• Documentation

  • Added rich, user-facing documentation and descriptive field-level guidance for PostgreSQL configuration, including usage notes and external resources.

• Refactor

  • Enhanced configuration schema with explicit titles, descriptions and metadata for connection fields to improve validation and schema introspection while preserving existing behavior.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Rewrote the PostgreSQL database configuration model to use Pydantic Field(...) for every attribute, adding titles, descriptions and an expanded multiline class docstring; updated documentation pages to reflect those field descriptions; added a pylint directive in a unit test. No functional validation logic changes were introduced.

Changes

Cohort / File(s)	Change Summary
PostgreSQL configuration model src/models/config.py	Replaced plain field declarations with Field(...) wrappers for nine attributes (host, port, db, user, password, namespace, ssl_mode, gss_encmode, ca_cert_path), adding titles and descriptions; expanded the class docstring; updated the check_postgres_configuration docstring.
HTML docs update docs/config.html	Added a PostgreSQLDatabaseConfiguration documentation block with descriptive prose, resource links, table layout and per-field descriptions for the nine fields.
Markdown docs update docs/config.md	Added descriptive prose, external references, and concrete per-field descriptions for the PostgreSQL configuration fields.
PUML/diagram update docs/config.puml	Updated the class/field representations to reflect adjusted field types/optionality and documentation for the PostgreSQL configuration.
Tests: lint directive tests/unit/models/config/test_postgresql_database_configuration.py	Added a pylint disable directive (no-member) to the test file; no runtime/test logic changes.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Verify the password field remains typed as SecretStr and was wrapped with Field(...) as intended (ensure no accidental type downgrade to raw str).
• Confirm docstrings, titles and descriptions match intended constraints and do not contradict validation (e.g., required vs optional).
• Check docs (.html, .md, .puml) for consistency with the model fields and for any stale references.

Possibly related PRs

• LCORE-574: Unit tests for PostgreSQL configuration + removed unused check #423 — Touches PostgreSQLDatabaseConfiguration and its check_postgres_configuration logic; likely related to configuration validation changes.
• LCORE-390: description for SQL storage config #378 — Updates the PostgreSQL configuration schema in docs/OpenAPI; overlaps with documentation/schema edits in this PR.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title describes only a minor aspect of the changeset. The PR updates documentation and code across multiple files, expanding PostgreSQLDatabaseConfiguration with Field-wrapped definitions, metadata, and docstrings, but the title merely refers to 'PostgreSQL description' without capturing the scope or main intent.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

tests/unit/models/config/test_postgresql_database_configuration.py (1)

20-20: Consider adding an explanatory comment.

The pylint directive is appropriate for suppressing false positives when accessing SecretStr.get_secret_value(). However, adding a brief comment would improve maintainability.

Apply this diff to add context:

-    # pylint: disable=no-member
+    # pylint: disable=no-member  # SecretStr.get_secret_value() triggers false positive

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 8977bf5 and 64b2af3.

⛔ Files ignored due to path filters (1)

• docs/config.svg is excluded by !**/*.svg

📒 Files selected for processing (5)

• docs/config.html (2 hunks)
• docs/config.md (1 hunks)
• docs/config.puml (1 hunks)
• src/models/config.py (1 hunks)
• tests/unit/models/config/test_postgresql_database_configuration.py (1 hunks)

🧰 Additional context used

📓 Path-based instructions (5)

tests/{unit,integration}/**/*.py

📄 CodeRabbit inference engine (CLAUDE.md)

tests/{unit,integration}/**/*.py: Use pytest for all unit and integration tests; do not use unittest framework
Unit tests must achieve 60% code coverage; integration tests must achieve 10% coverage

Files:

• tests/unit/models/config/test_postgresql_database_configuration.py

tests/**/*.py

📄 CodeRabbit inference engine (CLAUDE.md)

Use pytest-mock with AsyncMock objects for mocking in tests

Files:

• tests/unit/models/config/test_postgresql_database_configuration.py

src/**/*.py

📄 CodeRabbit inference engine (CLAUDE.md)

src/**/*.py: Use absolute imports for internal modules in LCS project (e.g., from auth import get_auth_dependency)
All modules must start with descriptive docstrings explaining their purpose
Use logger = logging.getLogger(__name__) pattern for module logging
All functions must include complete type annotations for parameters and return types, using modern syntax (str | int) and Optional[Type] or Type | None
All functions must have docstrings with brief descriptions following Google Python docstring conventions
Function names must use snake_case with descriptive, action-oriented names (get_, validate_, check_)
Avoid in-place parameter modification anti-patterns; return new data structures instead of modifying input parameters
Use async def for I/O operations and external API calls
All classes must include descriptive docstrings explaining their purpose following Google Python docstring conventions
Class names must use PascalCase with descriptive names and standard suffixes: Configuration for config classes, Error/Exception for exceptions, Resolver for strategy patterns, Interface for abstract base classes
Abstract classes must use ABC with @abstractmethod decorators
Include complete type annotations for all class attributes in Python classes
Use import logging and module logger pattern with standard log levels: debug, info, warning, error

Files:

• src/models/config.py

src/models/config.py

📄 CodeRabbit inference engine (CLAUDE.md)

src/models/config.py: All configuration must use Pydantic models extending ConfigurationBase with extra="forbid" to reject unknown fields
Use type hints Optional[FilePath], PositiveInt, SecretStr for Pydantic configuration models

Files:

• src/models/config.py

src/models/**/*.py

📄 CodeRabbit inference engine (CLAUDE.md)

src/models/**/*.py: Use @field_validator and @model_validator for custom validation in Pydantic models
Pydantic configuration classes must extend ConfigurationBase; data models must extend BaseModel

Files:

• src/models/config.py

🧠 Learnings (3)

📓 Common learnings

Learnt from: CR
Repo: lightspeed-core/lightspeed-stack PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-24T16:58:04.410Z
Learning: Applies to src/models/config.py : All configuration must use Pydantic models extending `ConfigurationBase` with `extra="forbid"` to reject unknown fields

Learnt from: CR
Repo: lightspeed-core/lightspeed-stack PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-24T16:58:04.410Z
Learning: Applies to src/models/**/*.py : Pydantic configuration classes must extend `ConfigurationBase`; data models must extend `BaseModel`

📚 Learning: 2025-11-24T16:58:04.410Z

Learnt from: CR
Repo: lightspeed-core/lightspeed-stack PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-24T16:58:04.410Z
Learning: Applies to src/models/config.py : Use type hints `Optional[FilePath]`, `PositiveInt`, `SecretStr` for Pydantic configuration models

Applied to files:

• docs/config.puml

📚 Learning: 2025-11-24T16:58:04.410Z

Learnt from: CR
Repo: lightspeed-core/lightspeed-stack PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-24T16:58:04.410Z
Learning: Applies to src/models/config.py : All configuration must use Pydantic models extending `ConfigurationBase` with `extra="forbid"` to reject unknown fields

Applied to files:

• docs/config.puml

🪛 LanguageTool

docs/config.md

[style] ~292-~292: It’s more common nowadays to write this noun as one word.
Context: ...connect to | | user | string | Database user name used to authenticate | | password | str...

(RECOMMENDED_COMPOUNDS)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

• GitHub Check: build-pr
• GitHub Check: e2e_tests (azure)
• GitHub Check: e2e_tests (ci)
• GitHub Check: Konflux kflux-prd-rh02 / lightspeed-stack-on-pull-request

🔇 Additional comments (4)

docs/config.html (1)

759-832: LGTM! Well-structured documentation.

The PostgreSQL configuration documentation is well-organized with helpful descriptions and external resources that align with the Field metadata in the source code.

src/models/config.py (2)

156-167: LGTM! Excellent documentation.

The expanded class docstring provides clear context about PostgreSQL usage in Lightspeed Core Stack and includes helpful external resources.

---

169-222: LGTM! Proper Pydantic Field usage.

The Field definitions follow coding guidelines with appropriate type hints (SecretStr, PositiveInt, Optional[FilePath]), clear titles, and helpful descriptions. Required fields correctly use Field(...) while optional fields are properly typed.

Based on coding guidelines, this aligns with Pydantic configuration model best practices.

docs/config.md (1)

276-297: LGTM! Comprehensive documentation.

The PostgreSQL configuration documentation is well-structured with helpful descriptions and resources that match the implementation.

Note: Static analysis suggests "username" (one word) on line 292, but "user name" (two words) is also acceptable.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical

Critical inconsistency: Field types don't match the actual implementation.

The PlantUML diagram shows several fields as Optional that are NOT optional in the actual PostgreSQLDatabaseConfiguration class in src/models/config.py:

Incorrectly marked as Optional:

• db (line 130): Should be str (required field with Field(...))
• gss_encmode (line 131): Should be str (has default value)
• host (line 132): Should be str (has default value "localhost")
• password (line 134): Should be SecretStr (required field with Field(...))
• port (line 135): Should be PositiveInt (has default value 5432)
• ssl_mode (line 136): Should be str (has default value)
• user (line 137): Should be str (required field with Field(...))

Correctly marked as Optional:

• ca_cert_path (line 129): Optional[FilePath] ✓
• namespace (line 133): Optional[str] ✓

Apply this diff to correct the field types:

 class "PostgreSQLDatabaseConfiguration" as src.models.config.PostgreSQLDatabaseConfiguration {
   ca_cert_path : Optional[FilePath]
-  db : Optional[str]
-  gss_encmode : Optional[str]
-  host : Optional[str]
+  db : str
+  gss_encmode : str
+  host : str
   namespace : Optional[str]
-  password : Optional[SecretStr]
-  port : Optional[PositiveInt]
-  ssl_mode : Optional[str]
-  user : Optional[str]
+  password : SecretStr
+  port : PositiveInt
+  ssl_mode : str
+  user : str
   check_postgres_configuration() -> Self
 }

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	db : Optional[str]
	gss_encmode : Optional[str]
	host : Optional[str]
	namespace : Optional[str]
	password : SecretStr
	port : Annotated
	ssl_mode : str
	user : str
	password : Optional[SecretStr]
	port : Optional[PositiveInt]
	ssl_mode : Optional[str]
	user : Optional[str]
	ca_cert_path : Optional[FilePath]
	db : str
	gss_encmode : str
	host : str
	namespace : Optional[str]
	password : SecretStr
	port : PositiveInt
	ssl_mode : str
	user : str

🤖 Prompt for AI Agents

In docs/config.puml around lines 130 to 137, the PlantUML types for several
PostgreSQLDatabaseConfiguration fields are incorrect: update the types to match
src/models/config.py by changing db from Optional[str] to str, gss_encmode from
Optional[str] to str, host from Optional[str] to str, password from
Optional[SecretStr] to SecretStr, port from Optional[PositiveInt] to
PositiveInt, ssl_mode from Optional[str] to str, and user from Optional[str] to
str; keep ca_cert_path as Optional[FilePath] and namespace as Optional[str]
unchanged.