Business Need
Hive currently tracks schema versions as target-specific history records. This works for publishing and promoting schemas, but it makes it difficult to identify the same composed graph as it moves through environments.
For example, a graph published in dev and promoted to test and prod receives a different schema_versions.id in each target. Users therefore cannot easily answer:
Which exact graph release is running in each environment?
Has the graph in prod been promoted from the graph tested in dev?
Which target versions correspond to release v1.0.0?
Can a known, approved graph be promoted without recomposing it?
This creates ambiguity for release management, auditability, rollback, and operational troubleshooting. Users need a stable release identity and an optional human-readable tag for the complete composed graph artifact.
Proposed Design
Extend the existing schema_versions model with:
graph_release_id Stable identity for the composed graph across targets
graph_release_tag Optional user-facing label, such as v1.0.0
The existing schema_versions.id remains unchanged and continues to represent a target-local history row.
This keeps the current target-history model intact while allowing the same graph release to be represented across dev, test, and prod without introducing new graph_versions or graph_tags tables initially.
Example
Target history ID Target Graph release ID Tag
dev-row-uuid dev release-uuid-123 v1.0.0
test-row-uuid test release-uuid-123 v1.0.0
prod-row-uuid prod release-uuid-123 v1.0.0
The target history IDs are different because they represent separate history records. The graph_release_id is shared because all three targets contain the same released graph.
Lifecycle
Publish
When a graph is published and composed:
Generate a new graph_release_id.
Leave graph_release_tag empty.
Continue creating the normal target history record.
Tag
Allow users to tag an existing valid composed graph version:
hive schema:tag v1.0.0 <schema-version-id> \
--target org/project/dev
The tag applies to the complete composed graph/supergraph artifact, not to an individual subgraph.
A tag should:
Be scoped to a project.
Resolve to exactly one graph release identity.
Be immutable by default.
Reject reuse for a different graph release.
Require an explicit elevated operation if moving an existing tag is supported later.
Promote
Promotion should preserve the source release identity and exact composed artifacts:
Copy graph_release_id.
Copy graph_release_tag.
Copy the existing composite_schema_sdl and supergraph_sdl.
Do not recompose the graph during promotion.
Continue creating a new destination-specific schema_versions history row.
Promotion should support resolving the source by:
Source target.
Schema-version ID.
Graph release ID.
Graph release tag.
The source and destination targets must belong to the same project.
Business Need
Hive currently tracks schema versions as target-specific history records. This works for publishing and promoting schemas, but it makes it difficult to identify the same composed graph as it moves through environments.
For example, a graph published in dev and promoted to test and prod receives a different schema_versions.id in each target. Users therefore cannot easily answer:
Which exact graph release is running in each environment?
Has the graph in prod been promoted from the graph tested in dev?
Which target versions correspond to release v1.0.0?
Can a known, approved graph be promoted without recomposing it?
This creates ambiguity for release management, auditability, rollback, and operational troubleshooting. Users need a stable release identity and an optional human-readable tag for the complete composed graph artifact.
Proposed Design
Extend the existing schema_versions model with:
The existing schema_versions.id remains unchanged and continues to represent a target-local history row.
This keeps the current target-history model intact while allowing the same graph release to be represented across dev, test, and prod without introducing new graph_versions or graph_tags tables initially.
Example
The target history IDs are different because they represent separate history records. The graph_release_id is shared because all three targets contain the same released graph.
Lifecycle
Publish
When a graph is published and composed:
Generate a new graph_release_id.
Leave graph_release_tag empty.
Continue creating the normal target history record.
Tag
The tag applies to the complete composed graph/supergraph artifact, not to an individual subgraph.
A tag should:
Be scoped to a project.
Resolve to exactly one graph release identity.
Be immutable by default.
Reject reuse for a different graph release.
Require an explicit elevated operation if moving an existing tag is supported later.
Promote
Promotion should preserve the source release identity and exact composed artifacts:
Copy graph_release_id.
Copy graph_release_tag.
Copy the existing composite_schema_sdl and supergraph_sdl.
Do not recompose the graph during promotion.
Continue creating a new destination-specific schema_versions history row.
Promotion should support resolving the source by:
Source target.
Schema-version ID.
Graph release ID.
Graph release tag.
The source and destination targets must belong to the same project.