Review keyword-only optional arguments in public factory and client APIs

[coderabbitai]

Summary

Review the public API signatures to determine where optional configuration should be keyword-only. This should cover more than postgresql_proc and postgresql_noproc; include the public client API as well.

DatabaseJanitor already uses keyword-only arguments and can serve as an established precedent.

Rationale

Public factory signatures currently allow a growing number of optional positional arguments. Adding options such as load_autocommit can either rebind an existing positional argument or make calls hard to read. A consistent keyword-only boundary would preserve clearly positional connection identity inputs while preventing future ambiguity.

This is intentionally a broader API-design and backwards-compatibility decision, not an incidental follow-up to the autocommit implementation.

Affected areas

• Public postgresql_proc factory API
• Public postgresql_noproc factory API
• Public client API
• Related documentation, type signatures, and compatibility/newsfragment policy

Acceptance criteria

• Inventory the relevant public factory and client call signatures and current positional usage expectations.
• Decide and document an API policy for which parameters remain positional and where keyword-only boundaries should be introduced.
• Keep DatabaseJanitor's existing keyword-only design in mind for consistency.
• If a change is adopted, apply it consistently across the chosen public APIs, update documentation and tests, and include the appropriate breaking-change newsfragment.
• Do not make the change as an unreviewed side effect of Pass autocomit to the janitor's load methods - closes #902 #1383.

Context

Requested by @fizyk in review discussion for #1383.

• Pull request: Pass autocomit to the janitor's load methods - closes #902 #1383
• Review discussion: Pass autocomit to the janitor's load methods - closes #902 #1383 (comment)

Ruff FBT001 follow-up

Consider enabling Ruff’s FBT001 (“Boolean-typed positional argument in function definition”) for the project.

Before enabling the rule, inventory existing violations and decide whether they should be remediated in the same change, explicitly suppressed where positional booleans remain intentional, or addressed through a staged rollout. If enabled, document the policy and ensure CI enforces it.

This rule-configuration decision is related to, but independent from, the public API keyword-only boundary decision above.

Requested by @fizyk in review discussion for #1383:

• Pass autocomit to the janitor's load methods - closes #902 #1383 (comment)

[coderabbitai]

🔗 Related PRs

#1182 - Refactor PostgreSQLExecutor to support Windows compatibility for process management [merged]
#1241 - Convert config kept in TypedDict into a dataclass - closes #1225 [merged]
#1271 - Adjust diagrams to use same wording [merged]
#1295 - feat: add async PostgreSQL fixture support [merged]
#1383 - Pass autocomit to the janitor's load methods - closes #902 [open]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!