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)

[coderabbitai]

🔗 Related PRs

#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]
#1381 - Fix flake in test_postgres_terminate_connection [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!