More ways to manage graphs from the CLI

Today we introduce new commands to the Grafbase CLI for graph management. The focus is to enable CI based workflows to define branches and environment variables.

Additionally the deploy command gained a feature to define the branch for the deployment. The command outputs the deployment process directly to the terminal, and returns a non-zero exit code if the deployment was not successful.

The commands for modifying branches should not be used together with a graphs which follow changes from a GitHub repository. For users who like the GitHub workflow, the old ways of deploying and managing branches still exist.

Traditionally the grafbase deploy command was meant to deploy a new version of the graph from the developer's command line; to try out the graph on production without pushing code to GitHub. A typical workflow so far is to link the new graph to a GitHub project, and trigger a new deployment when code is merged to the branch. This is not always feasible for a graph, sometimes it is better to have more control when to deploy a new graph.

A grafbase deploy command could not be executed if the current project was not linked to a Grafbase graph. This could be quite tedious on CI, so we added a new parameter --graph-ref, which can be used to define the graph and branch for the deployment. If the parameter is given, the CLI will not expect to be on a linked project, and the deployment can be triggered for example from a GitHub Action.

It would also be beneficial to fail a CI workflow if a deployment is not successful. Previously, the grafbase deploy would just return immediately after a successful API call. The deployment would run asynchronously in the Grafbase platform, and it could lead to a failure. We changed this, and now when deploying a graph, the deploy command will display the log output from the platform and exit with a non-zero code which can be used to fail the CI action.

Previously, a branch was always created or removed automatically based on branches in the repository. For graphs without git integration, a branch can be created from the Grafbase dashboard. Again, none of these work really well for CI based workflows.

In the latest version of Grafbase CLI, we introduce new commands to list and modify branches. The first one allows listing branches with their latest deployment and the status of that deployment:

❯ grafbase branch ls
Grafbase CLI 0.71.0

BRANCH    GRAPH                ACCOUNT               LATEST DEPLOY    STATUS
main*     test-project         julius-grafbasecom    4d 1h ago        succeeded

We see one branch (main), the graph and account, and how latest deployment happened four days ago successfully.

A new branch can be created using the grafbase deploy command:

❯ grafbase deploy --graph-ref julius-grafbasecom/test-project@test
Grafbase CLI 0.71.0

🕒 Your graph is being deployed...
18:01:05.293  INFO Installing dependencies...
18:01:15.530  INFO Dependency installation finished: 1.49s
18:01:18.472  INFO GraphQL schema generation finished: 2.57s
18:01:31.567  INFO Deployment completed

✨ Your graph was successfully deployed!

Now we see a new branch in our listing:

❯ grafbase branch ls
Grafbase CLI 0.71.0

BRANCH    GRAPH                ACCOUNT               LATEST DEPLOY    STATUS
main*     test-project         julius-grafbasecom    4d 1h ago        succeeded
test      cors-test-project    julius-grafbasecom    3m 7s ago        succeeded

If the branch is no longer needed, the branch remove command removes it from the Grafbase platform:

❯ grafbase branch rm julius-grafbasecom/test-project@test
Grafbase CLI 0.71.0

🕒 Branch is being deleted...

✨ The branch was successfully deleted!

The production branch is restricted, and cannot be removed from the CLI. In the listing, the production branch is marked with a * after its name.

Very often a graph deployed to the Grafbase platform needs environment variables before it can be deployed successfully. So far the workflow has been first a failed deployment for missing environment variables, making the user to add them in the dashboard and retrying the deployment.

This can be very cumbersome if automating deployments from the CI. The CLI now provides commands which can be used to automate the creation of these variables.

Listing variables can be done with the environment list command:

❯ grafbase env ls
Grafbase CLI 0.71.0

NAME                 VALUE                                                    LAST UPDATED    ENVIRONMENT
CONNECTION_STRING    postgresql://user:password@ep-babboon-cake-69...         8m 56s ago      preview,production

The graph has one environment variable CONNECTION_STRING, last update date and in which environments the variable is available. Grafbase has two possible environments for the variables: production for the production branch and preview for all the other branches. If a user wants to deploy a new branch for the graph, but the branch should not connect to the production database, they need to define a version of the variable for the preview environment.

A new variable can be created with the environment create command:

❯ grafbase env create CONNECTION_STRING "postgresql://postgres:password@staging-db.example.com:5432/postgres" --environment preview --graph-ref julius-grafbasecom/test-project@test
Grafbase CLI 0.71.0

✨ The environment variable was successfully created!

If we list the variables again, we now see two variables being available: one for production and the other for preview:

❯ grafbase env ls
Grafbase CLI 0.71.0

NAME                 VALUE                                                    LAST UPDATED    ENVIRONMENT
CONNECTION_STRING    postgresql://user:password@ep-babboon-cake-69...         1m 18s ago      production
CONNECTION_STRING    postgresql://postgres:password@staging-db.example....    1m 18s ago      preview

Finally, if an environment variable is not needed anymore, it can be deleted with the environment remove command:

❯ grafbase env rm CONNECTION_STRING --graph-ref julius-grafbasecom/test-project --environment preview
Grafbase CLI 0.71.0


✨ The environment variable was successfully deleted!

The new commands will make it easier to manage graphs directly from the CI, and make it much simpler to enroll secrets from the CI directly to the Grafbase platform. The documentation for the new CLI commands can be read from the documentation website, and the source code for the CLI is available in our GitHub repository.