Support TablePathPrefix and namespaced tables

[asmyasnikov]

Queries and schema files using PRAGMA TablePathPrefix previously failed analysis, and tables with the same basename in different directories could not be represented consistently. This change resolves their physical paths during analysis and preserves the authored SQL, so generated queries can address independent tables in separate directories.

Closes #29.

Behavior

• Support a static, nonempty absolute PRAGMA TablePathPrefix per named query or schema file. Resolve relative table references consistently in schema DDL, reads, writes, index views, and connected DescribeTable discovery; absolute references bypass the prefix.
• Preserve relational aliases and source SQL, including wildcard expansion. Reject dynamic, relative, empty, late, or conflicting prefix declarations with actionable diagnostics. Identical normalized declarations are accepted.
• An explicit source alias now hides the original table qualifier, including without a prefix: SELECT records.id FROM records AS r, accepted by v0.2.4, must use r.id to match YDB. Column bindings preserve case-sensitive aliases such as r and R; the compatibility guide and changelog document the migration.
• Generate distinct Java/Kotlin table names from full paths and detect naming collisions. Preserve jOOQ prefix semantics for both typed DSL and declared SQL, including relative and absolute RenderMapping replacements.
• Add a two-directory example with independent users, an index view, and a cross-directory join for all 18 target profiles. Include its generated code in the existing SDK build checks and document the supported contract.

Validation

• make generate and make check passed, with focused analyzer/model/generator regressions and SDK-backed jOOQ tests.
• Sequential live tests passed against ydbplatform/local-ydb:26.3.1.16: offline/connected schema parity and drift checks, generated Go native/database/sql and jOOQ execution, index views, absolute-path bypass, SELECT-backed writes, and namespace examples.
• Local SDK compilation/import checks covered Go (2), Java (3), Kotlin (3), Python (3), TypeScript, and Rust. CI also passed the C++ (2), C# (2), and PHP checks, covering all 18 generated profiles.
• The live prefix suite is included in CI, with its coverage profile uploaded alongside the other integration profiles.
• Negative generator-contract tests verify that missing resolved table metadata for declared SELECT and DELETE produces an actionable error and no generated files. The supported prefix contract is documented independently of server-version-specific behavior.
• Regression tests cover case-distinct JOIN source bindings, DECLARE versus local-assignment ordering, authored aliases in Java collision diagnostics, and quoted question marks in pragma text rendered by the pinned jOOQ SDK.
• All nine CI jobs passed on 339835cd, including stable/nightly YDB and the SDK checks. The combined Codecov report covers every modified coverable line and reports 88.69% project coverage.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.69%. Comparing base (1be28e5) to head (339835c).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #43      +/-   ##
==========================================
+ Coverage   88.44%   88.69%   +0.25%     
==========================================
  Files          58       59       +1     
  Lines       10115    10237     +122     
==========================================
+ Hits         8946     9080     +134     
+ Misses        668      662       -6     
+ Partials      501      495       -6     

Flag	Coverage Δ
integration	38.03% <64.02%> (+4.39%)	⬆️
unit	88.55% <100.00%> (+0.23%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
internal/analyzer/analyzer.go	93.88% <ø> (ø)
internal/analyzer/catalog.go	78.42% <100.00%> (+0.84%)	⬆️
internal/analyzer/database.go	88.54% <100.00%> (+0.45%)	⬆️
internal/analyzer/member.go	97.10% <100.00%> (ø)
internal/analyzer/select_semantic.go	87.03% <100.00%> (ø)
internal/analyzer/semantic.go	89.32% <100.00%> (+0.09%)	⬆️
internal/analyzer/table_paths.go	100.00% <100.00%> (ø)
internal/codegen/java/generator.go	93.09% <100.00%> (+0.10%)	⬆️
internal/codegen/java/jooq.go	78.50% <100.00%> (+2.26%)	⬆️
internal/codegen/java/jooq_declared.go	88.09% <100.00%> (+4.06%)	⬆️
... and 2 more

---

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update e7408ed...339835c. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[robot-vibe-db]

AI Review Summary

Verdict: ✅ No critical issues found

Critical issues

No critical issues found.

Other findings

• Major | High: Qualifier matching now accepts only the authored alias, so SELECT records.id FROM records AS r — which compiled on v0.2.4 — now fails with unknown column; the change is intentional (asserted by TestTableAliasIsTheOnlyQualifier) but is not recorded in CHANGELOG.md or docs/compatibility.md — internal/analyzer/member.go:62 (same matching change at internal/analyzer/semantic.go:751 and internal/analyzer/select_semantic.go:212)
• Minor | Low: recordColumnBindings still matches qualifiers case-insensitively with strings.EqualFold, inconsistent with the exact == alias matching introduced at resolveColumn/resolvedColumnKey; a future path reaching binding without prior resolveColumn validation would apply looser rules — internal/analyzer/semantic.go:1035
• Minor | Medium: The inline PRAGMA text is embedded in jOOQ plain SQL through sql(...) inside {0} of dsl.query("{0};\n{1}", ...), where ? is a bind-value placeholder; a TablePathPrefix value containing ? would be misrendered instead of kept as a literal path character — internal/codegen/java/jooq.go:261
• Minor | High: The diagnostic "PRAGMA TablePathPrefix must precede local bindings and data or schema statements" is stricter than the enforced rule, which still accepts the pragma after DECLARE statements (only data/schema statements set the ordering flag) — internal/analyzer/table_paths.go:38
• Nit | Low: The Java alias-collision error prints the /→_ substituted Java identifier rather than the authored alias, obscuring which authored aliases clashed — internal/codegen/java/jooq.go:243

---

This review was generated automatically. Critical issues require attention; other findings are advisory.
If this comment was useful, please give it a 👍 — it helps us improve the review bot.