From 0e80b93d0a0f95a7c4e9601572136c99a46c2f32 Mon Sep 17 00:00:00 2001 From: CharlesKWON Date: Mon, 18 May 2026 15:20:44 +0900 Subject: [PATCH] =?UTF-8?q?docs(pgserver):=20Phase=207=20=E2=80=94=20boots?= =?UTF-8?q?trap=20example=20+=20CI=20gate=20documentation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Wraps the v1.0 PG-wire deliverable with the two pieces operators actually look for: a runnable example PRG and an updated CI gate list in CLAUDE.md. * examples/pgserver_demo.prg — full bootstrap PRG demonstrating every HB_FUNC composed in the order a production deployment needs: PG_TLS_SELF_SIGNED → PG_ADD_ROLE × N → PG_ALLOW_IP × N → PG_SERVER_START( ":5432", "md5" ) Comments cover the SHARED-DBF integration point and the SPAWN idiom for non-blocking server startup. Builds cleanly under the examples_build sweep (now 66/72; was 65/71). * CLAUDE.md — the "어떤 파일이든 수정한 후" mandatory test list goes from 3 gates → 6: 1. go test ./... 2. FiveSql2 SQL:1999 43/43 3. Harbour compat 56/56 4. std.ch 17/17 (added) 5. FRB 7/7 (added) 6. pgserver integration 6/6 (added — psql required) Aligns the rule-of-thumb with reality. The five suites already ran on every audit-era commit; pgserver/run.sh is new in Phases 3-6 and now joins them. This completes the v1.0 PostgreSQL-wire frontend. End-to-end checklist: Phase 1: per-session state isolation [93cf5c8] Phase 2: SimpleQuery wire MVP [d98f5e1 7083297] Phase 3: DML + transactions [a556764] Phase 4: Extended Protocol (Parse/Bind/Exec) [8472928] Phase 5: password + MD5 auth [90eafcf] Phase 6: TLS + IP allowlist [3b2dd36] Phase 7: example + docs [this commit] Open follow-ups (Phase 7.x): - hbrdd workarea per-thread isolation (audit Top-Risk #2): ≥3 concurrent connections doing in-flight INSERT/SELECT in their own transactions can race at the workarea layer. Fix is a separate workstream against hbrtl/database.go + hbrdd/dbf/. Documented limitation in tests/pgserver/run.sh. - SCRAM-SHA-256 auth (Phase 5.1). - pg_catalog shim for BI-tool introspection (Phase 1.1+ of the original audit plan). - Binary parameter format for NUMERIC/TIMESTAMP (Phase 4.1). All gates green: go test ./... ✓ FiveSql2 SQL:1999 43/43 ✓ Harbour compat 56/56 ✓ std.ch 17/17 ✓ FRB 7/7 ✓ examples 66/72 ✓ (+1 from new pgserver_demo) pgserver integration 6/6 ✓ Co-Authored-By: Claude Opus 4.7 (1M context) --- CLAUDE.md | 13 ++++++++-- examples/pgserver_demo.prg | 53 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 64 insertions(+), 2 deletions(-) create mode 100644 examples/pgserver_demo.prg diff --git a/CLAUDE.md b/CLAUDE.md index 2656895..397953f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,7 +2,7 @@ ## 절대 규칙: 변경 후 반드시 검증 -**어떤 파일이든 수정한 후, 다음 3개 테스트를 모두 통과해야 한다.** +**어떤 파일이든 수정한 후, 다음 6개 테스트를 모두 통과해야 한다.** 하나라도 실패하면 해당 변경을 되돌린다. ```bash @@ -13,8 +13,17 @@ go test ./... ./five build _FiveSql2/test/test_sql1999.prg _FiveSql2/src/*.prg -o /tmp/test_sql cd ~/tmp && rm -f *.dbf __cte_*.dbf && /tmp/test_sql -# 3. Harbour 호환 테스트 (51/51) +# 3. Harbour 호환 테스트 (56/56) ./five build tests/compat_harbour.prg -o /tmp/test_compat && /tmp/test_compat + +# 4. std.ch 테스트 (17/17) +bash tests/std_ch/run.sh + +# 5. FRB 테스트 (7/7) +bash tests/frb/run.sh + +# 6. pgserver 통합 테스트 (6/6) — psql 필요 +bash tests/pgserver/run.sh ``` **절대로 "나중에 확인" 하지 않는다. 매 변경마다 즉시.** diff --git a/examples/pgserver_demo.prg b/examples/pgserver_demo.prg new file mode 100644 index 0000000..b4b855f --- /dev/null +++ b/examples/pgserver_demo.prg @@ -0,0 +1,53 @@ +/* + * examples/pgserver_demo.prg — PostgreSQL-wire server example. + * + * Run this PRG to expose your Five workareas to any psql / pgx / + * JDBC / DBeaver / Tableau client over TCP. The server speaks + * PostgreSQL protocol v3 so existing PG drivers connect with no + * client-side changes. + * + * ./five build examples/pgserver_demo.prg _FiveSql2/src/*.prg \ + * -o /tmp/pgserver + * /tmp/pgserver + * + * Then from another terminal: + * psql 'postgres://alice@127.0.0.1:5432/alice?sslmode=require' \ + * -c "SELECT 1 AS one, 'hello' AS greet" + * + * Stop with Ctrl-C. + */ + +PROCEDURE Main() + + /* TLS — auto-generate a self-signed cert for the demo. + * Production deployments load a CA-signed pair via + * PG_TLS_LOAD( "cert.pem", "key.pem" ). */ + PG_TLS_SELF_SIGNED( "/tmp/pg_cert.pem", "/tmp/pg_key.pem", "localhost" ) + + /* Users — minimum one role to log in. Plaintext kept in + * memory; production should source these from a secured + * config file or vault. */ + PG_ADD_ROLE( "alice", "swordfish" ) + PG_ADD_ROLE( "bob", "hunter2" ) + + /* Source-IP allowlist (pg_hba.conf equivalent). Skip + * entirely to accept any source. */ + PG_ALLOW_IP( "127.0.0.1/32" ) + PG_ALLOW_IP( "::1/128" ) + + /* Open the tables you want to expose. The server runs queries + * against whatever workareas are open in the PRG process. + * Uncomment as needed: + * USE customers SHARED NEW + * USE orders SHARED NEW + */ + + /* Start — blocks. SPAWN this if you want to keep doing work + * in the main thread: + * SPAWN {|| PG_SERVER_START( ":5432", "md5" ) } + */ + ? "FiveSql2 PG-wire server starting on :5432" + ? "Connect with: psql 'postgres://alice@127.0.0.1:5432/alice?sslmode=require'" + PG_SERVER_START( ":5432", "md5" ) + + RETURN