graphql-hive / graphql-hive/console

Support stable graph release identity and tag-based schema promotion

Open
#8,470 2 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.