Ability to configure maintenance database name other than postgres - closes #653

[fizyk]

Summary by CodeRabbit

• New Features

  • Added support for configuring a server-level maintenance database.
  • Configure it through pytest settings, the command line, or PostgreSQL fixtures.
  • Synchronous and asynchronous database janitors now use the configured maintenance database by default.
  • Existing behaviour defaults to postgres; explicit database overrides remain supported.

• Documentation

  • Clarified configuration options, prerequisites, and database handling requirements.
  • Added examples for using an alternative maintenance database.

• Tests

  • Added coverage for custom databases, CLI and ini configuration, overrides, and unavailable databases.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds configurable server-level maintenance database support. The setting is available through pytest configuration, CLI options, and factory or janitor arguments. Executors and janitors use the configured database for maintenance operations, with postgres as the default.

Changes

Maintenance database configuration

Layer / File(s)	Summary
Configuration and executor contract pytest_postgresql/config.py, pytest_postgresql/plugin.py, pytest_postgresql/executor.py, pytest_postgresql/executor_noop.py, newsfragments/653.feature.rst	Adds maintenance_dbname configuration and CLI support. Executors expose the setting, which defaults to postgres.
Janitor and factory propagation pytest_postgresql/janitor.py, pytest_postgresql/factories/*	Passes the maintenance database through synchronous and asynchronous janitors. Default cursor connections and no-process version queries use it.
Behaviour validation and documentation tests/test_janitor.py, tests/test_noopexecutor.py, tests/test_postgres_options_plugin.py, tests/examples/test_maintenance_dbname.py, README.rst	Tests cover CLI and ini configuration, cursor selection, explicit database overrides, successful connections, and missing databases. Documentation describes database requirements and factory settings.

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

Possibly related PRs

• dbfixtures/pytest-postgresql#1364: Extends the shared janitor and cursor implementations introduced by this PR.
• dbfixtures/pytest-postgresql#1366: Modifies the janitor classes and cursor behaviour used by this PR.

Suggested reviewers: tboy1337

Sequence Diagram(s)

sequenceDiagram
  participant Pytest
  participant PostgreSQLConfig
  participant NoopExecutor
  participant DatabaseJanitor
  Pytest->>PostgreSQLConfig: read maintenance_dbname
  PostgreSQLConfig->>NoopExecutor: provide configured database
  NoopExecutor->>DatabaseJanitor: pass maintenance_dbname
  DatabaseJanitor->>DatabaseJanitor: open default cursor on maintenance database

Loading

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarises the main change: configuring a maintenance database name other than postgres.
Docstring Coverage	✅ Passed	Docstring coverage is 87.50% which is sufficient. The required threshold is 80.00%.
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.
Newsfragment Check	✅ Passed	newsfragments/653.feature.rst is present, and pyproject.toml defines feature as a valid Towncrier type.

✨ 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 issue-653

---

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.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[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 `@tests/test_postgres_options_plugin.py`:
- Line 4: Update the import statement that currently imports Iterator from
typing to import Iterator from collections.abc instead. This aligns with Ruff
UP035 compliance requirements which prefer the standard library collections.abc
module over the typing module for this import.

🪄 Autofix

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: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 590dbdb1-809d-489e-96ec-0ed3c387de42

📥 Commits

Reviewing files that changed from the base of the PR and between 2b2534e and f01f95c.

📒 Files selected for processing (14)

• README.rst
• newsfragments/653.feature.rst
• pytest_postgresql/config.py
• pytest_postgresql/executor.py
• pytest_postgresql/executor_noop.py
• pytest_postgresql/factories/client.py
• pytest_postgresql/factories/noprocess.py
• pytest_postgresql/factories/process.py
• pytest_postgresql/janitor.py
• pytest_postgresql/plugin.py
• tests/examples/test_maintenance_dbname.py
• tests/test_janitor.py
• tests/test_noopexecutor.py
• tests/test_postgres_options_plugin.py