graphql-hive / graphql-hive/console
Support stable graph release identity and tag-based schema promotion
- Dominant language
- TypeScript
- Stars
- 483
- Forks
- 145
- Avg merge
- 2d 5h
- Merged PRs (30d)
- 65
Description
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 \
--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.
Contributor guide
Research direction
Start by tracing the existing schema_versions model and the publish, composition, tagging, and promotion entry points, including `hive schema:tag`. Inspect the tests covering schema publication and promotion before defining coverage for stable release identity, immutable tags, source resolution, and artifact-preserving promotion across targets.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- graphql, typescript
- Domain
- api, backend-api-design, cli, release
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100