graphql-hive / graphql-hive/console
subgraph schema push/registration
- Dominant language
- TypeScript
- Stars
- 483
- Forks
- 145
- Avg merge
- 2d 5h
- Merged PRs (30d)
- 65
Description
## Goal
Allow users to check or push a named subgraph version once and later publish that exact version without locating and uploading the SDL again.
The intended workflow is:
```bash
# Check the SDL and make products@$GIT_SHA available for publication.
hive schema:push schema.graphql \
--service "products@$GIT_SHA" \
--project my-org/my-project
# Publish the exact checked SDL later without passing the file again.
hive schema:publish \
--service "products@$GIT_SHA" \
--target my-org/my-project/production
```
This separates producing a subgraph schema from publishing it into a target. The registry guarantees that a version always identifies the same SDL, while the normal publish pipeline still performs composition, policy, contract, and artifact processing against the destination target's current state.
## User-Facing Changes
### Push subgraph without checking/publishing
Users can explicitly push/register SDL to the schema registry:
```bash
hive schema:push schema.graphql \
--service products@1.4.0 \
--project my-org/my-project
```
Registration stores the SDL for later use but does not change any target's published schema.
### Publish a version
Users publish a registered version by omitting the schema file and including the version in the
service reference:
```bash
hive schema:publish \
--service products@1.4.0 \
--target my-org/my-project/production
```
The existing file-based publish remains supported:
```bash
hive schema:publish schema.graphql \
--service products \
--url https://products.example.com/graphql
```
Supplying both a schema file and `service@version` is ambiguous and rejected.
### Handle an existing version
Versions are immutable from the user's perspective:
- Registering the same service, version, and SDL again succeeds idempotently.
- Registering the same service and version with different SDL fails with a conflict.
- Correcting a version normally requires choosing a new version name.
- Mutable names such as `candidate` or `latest` are out of scope of this task
An example conflict is:
```text
Version products@1.4.0 already exists with a different schema.
Existing digest: hive-sdl-v1:sha256:abc...
Submitted digest: hive-sdl-v1:sha256:def...
```
## Design Guarantees
- The registry assigns an immutable digest based on canonical SDL.
- A user-provided version is an immutable alias for one digest.
- Versions can be reused across targets in the same project.
- Registration does not modify published target state.
- Publishing by reference executes the existing publish pipeline.
- Published history records the resolved SDL revision and service URL.
Contributor guide
Research direction
Start by tracing the existing schema:publish CLI entry point and its file-based publish pipeline, then identify how schema registry versions are represented. Done means schema:push registers an immutable SDL version, schema:publish can resolve it without a file, conflicts are rejected, and the existing file-based workflow remains supported.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- nodejs, typescript
- Domain
- api, backend-api-design, cli
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100