Skip to content

orm_refinement.md

Latest commit

 

History

History
138 lines (88 loc) · 7.54 KB

orm_refinement.md

File metadata and controls

138 lines (88 loc) · 7.54 KB
Raw

Phase 2 — ORM Refinement and Curation (Manual, Optional but Recommended)

Last updated: 2026-07-19 1:10 AM PDT

Why Phase 2 matters

ORM_Skyway is designed to support JDBC-accessible relational data sources through a common automation pipeline, while accommodating source-specific differences in metadata discovery and runtime behavior. It uses JDBC metadata to generate an initial JDX declarative ORM specification — which becomes the starting point, not the final semantic model, for an AI-ready business domain.

The generated specification can then be curated by domain owners:

  • Cryptic database names can be mapped to meaningful business attributes
  • Sensitive or irrelevant fields can be excluded
  • Logical relationships that are not physically declared in the database can be added explicitly
  • Database-generated columns can be marked so AI agents know not to supply values for them on insert

This creates a stable, governed business-domain abstraction for AI agents, while allowing ORM_Skyway, JDX, and the Gilhari service layer to absorb differences among underlying data sources. The result is a common agent-facing model without requiring every JDBC source to behave identically.

This phase has no script command. It is a manual editing step — open the .jdx file in any text editor and make changes as described below. When you are done, recompile and move on to Phase 3.

Skipping this phase is perfectly fine for getting started. The auto-generated model from Phase 1 is fully functional and will work with Gilhari and ORMCP out of the box. Phase 2 is where domain knowledge goes in — it's an opportunity to elevate the model from a mechanical schema reflection to a meaningful business domain that an AI agent can reason about effectively.

The working file

config/<reverse_eng_template_config>.config.jdx

This is a plain-text file using simple JDX grammar. Open it in any text editor. The .revjdx file is the immutable auto-generated starting point — do not edit it. The .jdx is your working copy.

Common refinements

Rename attributes — production databases often have cryptic column names. Renaming them in the .jdx makes the model readable to both developers and AI agents. Example: pid → productId, emp_nm → employeeName.

Please add/modify a SQLMAP specification in the mapping file for any renamed attribute. For example,

SQLMAP for productId COLUMN_NAME pid

Hide sensitive columns — remove attributes like salary, ssn, or password_hash entirely. The AI agent will never see columns that are not mapped in the .jdx. This is your governance boundary.

Also remove SQLMAP specifications, if any, for the corresponding attributes/columns.

Curate the object graph — expose only the columns your application needs. If a table has 30 columns but only 8 are relevant, remove the rest. This keeps AI responses focused and token-efficient.

Also remove SQLMAP specifications, if any, for the removed attributes/columns.

Add or adjust relationships — define/refine one-to-one, one-to-many, or many-to-many relationships between classes to reflect your actual domain model.

If you add/remove any RELATIONSHIP attribute, please add/remove the corresponding declaration in the associated container class (.java) file.

Update the model overview — if you left model_overview blank during Phase 1, add it directly to the .jdx file:

OBJECT_MODEL_OVERVIEW An e-commerce model with Customers, Orders, and Products

This is read by ORMCP at startup to orient the AI agent before any queries are made.

Mark database-generated attributes — some columns have their values automatically generated by the database. JDX automatically detects and emits RDBMS_GENERATED for two common patterns during reverse engineering:

  • UUID primary keys with a DEFAULT gen_random_uuid() expression (PostgreSQL/CockroachDB) — detected via the column's native uuid type and non-null default value.
  • Auto-increment/identity integer primary keys (PostgreSQL SERIAL, MySQL AUTO_INCREMENT, SQL Server IDENTITY, DB2 GENERATED AS IDENTITY) — detected via the JDBC driver's IS_AUTOINCREMENT metadata flag.

For columns where automatic detection doesn't apply — such as MySQL's DEFAULT (UUID()) on a CHAR(36) column, Oracle sequences, OCC timestamp/version columns, or CockroachDB SERIAL PKs (where the driver doesn't correctly report IS_AUTOINCREMENT) — you can add RDBMS_GENERATED manually during Phase 2.

For example, to manually mark product_id as database-generated:

CLASS .Products TABLE products
    VIRTUAL_ATTRIB product_id ATTRIB_TYPE java.lang.String
    ...
    PRIMARY_KEY product_id
    RDBMS_GENERATED product_id
    ...
;

Once set (automatically or manually), JDX omits that column from INSERT and UPDATE statements, letting the database populate it automatically — while still fetching and returning it on queries. This declaration is also surfaced in getObjectModelSummary, informing AI agents via ORMCP that the attribute should not be supplied on insert.

This is one example of how Phase 2 refinement goes beyond cosmetic changes — it lets a user with knowledge of the underlying schema's semantics shape how the AI agent reasons about and interacts with the data.

If you change the Java source files

Some refinements require changes to both the .jdx and the corresponding .java source files in src/<package path>/ — for example, renaming a class, adding a relationship, or adding a transient (runtime-only) attribute. After any .java changes, recompile:

scripts\compile.bat       :: Windows
./scripts/compile.sh      :: macOS / Linux

The compile script cleans bin/<package path>/ first, removing stale .class files for any classes you removed.

If you plan to re-run Phase 1 later (e.g. to add more tables), the script will warn you before cleaning src/<package path>/. Save copies of any hand-edited .java files before re-running.

Verifying with JDXDemo

JDXDemo is a tool included with the Gilhari SDK that lets you browse your object model and run queries against the live database — using the localhost URL in the .jdx — without spinning up Docker. It is a useful sanity check before building the Docker image, but it is optional.

scripts\JDXDemo.bat       :: Windows
./scripts/JDXDemo.sh      :: macOS / Linux

The three ORM spec files

File URL in connection string Purpose
*.revjdx localhost Auto-generated, immutable record — never edit
*.jdx localhost Your working copy — edit freely; used by JDXDemo and local Java apps
*.docker.jdx host.docker.internal Auto-generated at the start of Phase 3; packaged inside the Docker image

The .docker.jdx does not exist yet at this stage. It is created fresh at the start of Phase 3 by substituting host.docker.internal for localhost in the JDBC URL so the container can reach the host's database.

When you're ready for Phase 3

:: Windows
python C:\tools\orm_skyway_automation\orm_skyway.py -f orm_skyway_config.json --phase 3

# macOS / Linux
python ~/tools/orm_skyway_automation/orm_skyway.py -f orm_skyway_config.json --phase 3

No database connection is needed for Phase 3. It reads only the compiled classes from bin/ and the current .jdx from config/.

→ Phase 3 — Gilhari Packaging

← Phase 1 — Reverse Engineering | Next: Phase 3 — Gilhari Packaging →