Skip to content

Run GraphQL requests from CLI

Run a single GraphQL script from a file using the built-in CLI in CloudBeaver

Prerequisites

  • make sure the server container is running
  • have an API access token
  • prepare a file with exactly one GraphQL operation, save it in any format (such as.json or .txt), and make sure the content is valid JSON

Tip

with Docker Compose, either mount the script file or a folder of scripts into the service container at startup, or copy the file into the running container.

Write a GraphQL script file

Create a JSON file with query, variables, and operationName. For schema details and more operations, see GraphQL API overview.

Example

{
  "query": "mutation createConnection($projectId: ID!, $config: ConnectionConfig!) { connection: createConnection(projectId: $projectId, config: $config) { ...DatabaseConnection } } fragment DatabaseConnection on ConnectionInfo { id projectId name }",
  "variables": {
    "projectId": "g_GlobalConfiguration",
    "config": {
      "configurationType": "MANUAL",
      "credentials": { "userPassword": "qwe", "userName": "qwe" },
      "mainPropertyValues": { "host": "localhost", "port": "3306" },
      "networkHandlersConfig": [],
      "providerProperties": {},
      "driverId": "mysql-ee:mysql8",
      "name": "MySQL@localhost",
      "host": "localhost",
      "port": "3306",
      "databaseName": null,
      "authModelId": "native",
      "properties": {}
    }
  },
  "operationName": "createConnection"
}

For more ready-to-run examples, see the CloudBeaver graphql examples repository.

Enter the running container

Open a shell in the Compose service container:

docker compose exec <service_name> bash

List services, and get the container id for a service:

docker compose ps
docker compose ps -q <service_name>

Copy your script from the host into the service container:

docker cp /path/on/host/create-connection.json $(docker compose ps -q <service_name>):/<your_custom_directory>/create-connection.json

Tip

if you use the older v1 CLI, replace docker compose with docker-compose.

Execute the script

Run the command:

docker compose exec <service_name> ./cbvr.sh -gql \
  -input-file /<your_custom_directory>/create-connection.json \
  --access-token <api_token>

The command prints the GraphQL response to stdout in JSON, including data, and, if present, errors. If errors occur, the command returns a non-zero exit code.

Save output to a file

To save the GraphQL response to a file:

docker compose exec <service_name> ./cbvr.sh -gql \
  -input-file /<your_custom_directory>/create-connection.json \
  -output-file /opt/cloudbeaver/workspace/out.txt \
  --access-token <api_token>

Command line parameters

Option / Command Applies to Description
-gql GraphQL Runs a GraphQL request from a file
import-license License import Imports a license file into CloudBeaver. Learn more
--access-token <token> / -token <token> GraphQL API access token for authentication
-input-file <path> Both Path to the input file inside the container (.json, .txt, or license file)
-output-file <path> GraphQL Path to the file where the response is saved (optional). A safe writable path inside the container is /opt/cloudbeaver/workspace/.

Use in AWS

If you run CloudBeaver on AWS, do the same steps inside the instance: place the JSON file on the instance, then run the CLI there.

Info

For connection and file transfer basics, see AWS documentation:

Exit codes

When CloudBeaver finishes executing a command, it returns an exit code to indicate the result.

Code Name Description
-1 EXIT_CODE_CONTINUE Indicates that the process continues running. You won’t normally see this code when running commands.
0 EXIT_CODE_OK Command executed successfully.
1 EXIT_CODE_ERROR A general error occurred during execution.
2 EXIT_CODE_ILLEGAL_ARGUMENTS Invalid command line arguments were provided.