graphql-hive / graphql-hive/console

subgraph schema push/registration

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.