feat(postgres): define driver-neutral migration port - #323
Draft
seonghobae wants to merge 241 commits into
Draft
Conversation
|
Important Draft PR not reviewedDraft PRs are not automatically reviewed by default.
To automatically review draft PRs, update your CodeRabbit configuration: reviews:
auto_review:
drafts: true📝 WalkthroughWalkthroughPostgreSQL 접근을 ChangesPostgreSQL 드라이버 계약과 어댑터
애플리케이션 데이터베이스 경로
CLI, Compose, 헬스 및 후보 런타임
Estimated code review effort: 5 (Critical) | ~120 minutes Merge Risk: 🔵 Low · up to The candidate-only dependency safeguard can be bypassed by a case-variant package name, allowing future runtime dependency drift to escape this check. Normalize package names before comparing them. Sequence Diagram(s)sequenceDiagram
participant CLI
participant PostgresDriverPort
participant PostgresBatchOrchestrator
participant PostgresConnectionPort
participant PostgresCursorPort
CLI->>PostgresDriverPort: parse_conninfo(dsn)
CLI->>PostgresBatchOrchestrator: create with postgres_driver
PostgresBatchOrchestrator->>PostgresDriverPort: connect(dsn)
PostgresDriverPort->>PostgresConnectionPort: return connection
PostgresBatchOrchestrator->>PostgresConnectionPort: set_autocommit(False)
PostgresConnectionPort->>PostgresCursorPort: execute(query, params)
PostgresBatchOrchestrator->>PostgresDriverPort: jsonb(payload)
PostgresConnectionPort->>PostgresConnectionPort: commit()
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
Full details: Docstring CoverageExplanation Docstring coverage is 48.78% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 449 functions across 35 files. (1 skipped: 1 unsupported.) ✨ Finishing Touches 💡 1📝 Generate docstrings 💡
🧪 Generate unit tests (beta)
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. Comment |
seonghobae
added
enhancement
ChatGPT Codex Connector
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Addresses #322 through the existing PostgreSQL-driver migration stack without claiming commercial-license completion.
Exact current boundary
main:5913c4bad79d6bc29d7cc1c624abb7db2ea6a77c(ci(actions): consolidate pull request workflows #335 merged);fix/python-support-matrix-b84f0c9@8de00aee07cf5a0a32d091f6b4819de2e5849bbd;8cfba1d920f8079ea252e4a013be22e8d2aecd43;pyproject.toml/uv.lockstill retain Psycopg as the production default, so this branch is not commercial-license clean.No force push, destructive rebase, protected-main direct write, predecessor-evidence transfer, mutable production dependency, self-approval, or gate weakening is used.
Driver-neutral migration boundary
This lane establishes
PostgresDriverPortplus the retainedPsycopgDriverAdapterso a permissively licensed replacement can be verified against the repository's real PostgreSQL contract before runtime promotion. Candidate-only pg8000 1.31.5 evidence covers parameter binding, tuple-row normalization, finite fetch budgets, exact/unknown row counts, transaction/context ownership, terminal connection state, thread-affine use, PostgreSQL RLS/session behavior, UUID/timestamp round-trip, SQLSTATE 42883 classification, recovery cleanup, JSONB adaptation, exact candidate dependency hashes, license/vulnerability pre-admission, strict single-host URI/keyword conninfo parsing, explicit service-file resolution without ambientPGSERVICEFILEdiscovery, and the packaged restore-catalog acceptance query. Unsupported multi-host/socket/query/LDAP/ambient service semantics remain fail closed rather than approximated.The centralized runtime selector still constructs
PsycopgDriverAdapteruntil the replacement is fully admitted. This is migration architecture, not final license replacement.Service-file authority RED → GREEN lineage
Fresh source review first found that the caller-selected candidate
pg_service.confpath usedPath.open("rb")before proving file type. A FIFO or device could therefore block before the 64 KiB read budget applied, or supply bytes through a non-regular filesystem capability while being treated as service-file authority.857b0923bc510aaa14607348d587985bfea85e72requires a nonblocking descriptor open where supported and rejection of a non-regular retained descriptor.c88a36f7c43bd58e487a032903d88cb0f927f9aeopens the explicit path with read-only/nonblocking/close-on-exec/binary flags where available, proves the retained descriptor is regular before consuming bytes, and keeps the strict finite read/UTF-8/content-free error contract.8a816deb407c23dff3c0c84726656acf68491741covers descriptor read failure, close-only failure, and preservation of a primary descriptor failure when cleanup also fails.A second exact-source review then found a TOCTOU boundary: proving regular-file identity only before the bounded read did not reject in-place mutation while connection-selector bytes were being retained.
e33d622664fcc1b584be3b08915a978d860efdf0deterministically changes retained descriptor metadata between inspection points and requires fail-closed rejection.5cf3c5778c06a275ee232f10eb864f281463a4f2snapshots device/inode/mode/size/mtime/ctime before the read, re-observes the same retained descriptor afterward, requires exact metadata stability and byte-count agreement, and only then permits parsing. Path replacement cannot redirect the retained descriptor, and in-place mutation observed across the bounded read does not become connection-selector authority.The repairs do not add ambient service lookup, LDAP/network lookup, production pg8000 dependency authority, or new service precedence semantics.
Restore-catalog candidate parity
Current head
8cfba1d920f8079ea252e4a013be22e8d2aecd43adds a real-PostgreSQL candidate probe for the productioninspect_postgres_restore_catalog()boundary. The exact pg8000 artifact must execute the packaged catalog query that binds finite Python lists throughANY(%s)and return the required catalog tuple/boolean semantics, two authenticated lifecycle indexes, and forced-RLS evidence. This closes a candidate-parity gap that adapter unit tests could not prove; it does not promote pg8000 into the production dependency graph or claim logical-restore completion by itself.Exact-current validation / central owner path
Fresh exact-head workflows are non-passing:
33914978050: queued;33914978044: queued.CI materialized seven jobs for exact
8cfba1d9...; all are pre-checkout withsteps=[],labels=[ubuntu-latest],runner_id=0, and no assigned runner/group. Representative jobs are PostgreSQL/container101159943718, coverage/package101159943903, and Python 3.14101159944009. The superseding exact-current specimen was advanced to the existing central runner owner.github#712as comment5545939374. Earlier runner evidence is predecessor-only now.No remote GREEN is claimed until exact-current jobs acquire runners, prove checkout identity, and execute required repository/security/release gates. The leaf source must not be churned merely to retrigger allocation.
Descendant convergence
Documentation child #321 was non-force converged after this parent moved. Current child
docs/public-surface-metadata@efa2b1206789a97548a8af151e2b47e5ceb75418has merge base exactly8cfba1d920f8079ea252e4a013be22e8d2aecd43, is behind 0, and retains onlyREADME.mdplusdocs/index.mdas its relative semantic delta. No predecessor checks/reviews transfer.Context Fabric / release boundary
Fresh GitHub release inventories remain empty for
ContextualWisdomLab/context-graph-contracts,ContextualWisdomLab/enterprise-architecture-core, andContextualWisdomLab/pg-llm-batch. Mutable producer PR heads remain candidate/test-only evidence and are never production dependency authority. Context Fabric consumer readiness remains owned by #319 while immutable upstream publication is absent.Merge boundary
Keep Draft. Merge only after dependency ancestry is current, a commercially compatible replacement is fully admitted, the final unchanged head removes the disallowed runtime graph, package/lock/SBOM/license/provenance evidence is regenerated, exact-head CI/security/SAST/coverage/docstrings/release plus realistic PostgreSQL behavior pass, every valid current finding is resolved, and then-live protected governance is satisfied. No predecessor GREEN, routine bypass, or mutable dependency is accepted.