Skip to main content
Version: 3.10

ScalarDB GraphQL Server

ScalarDB GraphQL Server is an interface layer that allows client applications to communicate with ScalarDB with GraphQL.

Build & Install​

To build and install the ScalarDB GraphQL Server, use ./gradlew installDist, which will build the source files and install an executable and required jars:

./gradlew installDist

Run​

In addition to the configurations described in Transaction manager configurations and Other configurations, the GraphQL server reads the following:

  • scalar.db.graphql.port ... Port number for GraphQL server. The default is 8080.
  • scalar.db.graphql.path ... Path component of the URL of the GraphQL endpoint. The default is /graphql.
  • scalar.db.graphql.namespaces ... Comma-separated list of namespaces of tables for which the GraphQL server generates a schema. Note that at least one namespace is required.
  • scalar.db.graphql.graphiql ... Whether the GraphQL server serves GraphiQL IDE. The default is true.
  • scalar.db.graphql.schema_checking_interval_millis ... The interval at which GraphQL server will rebuild the GraphQL schema if any change is detected in the ScalarDB schema. The default interval value is 30000 (30 seconds). Besides, this automatic schema rebuild can be disabled by setting the property value to -1. Refer to the following section for more details.

To start the ScalarDB GraphQL Server, run the following commands:

cd build/install/graphql
export JAVA_OPTS="<your JVM options>"
bin/scalardb-graphql-server --config <ScalarDB properties file path>

Creating or modifying the ScalarDB schema when the server is running​

Since the GraphQL schema is statically built at server startup, if the ScalarDB schema is modified (e.g., a table is added, altered or deleted) then the corresponding GraphQL schema won't reflect the changes unless it is rebuilt. To address this, the GraphQL server provides the following two mechanisms:

Periodic check​

The server periodically checks if changes in the ScalarDB schema occur and rebuilds the corresponding GraphQL schema if necessary. By default, the checking occurs every 30 seconds, but the interval can be configured with the scalar.db.graphql.schema_checking_interval_millis property. Besides, this periodic check can be disabled by setting the property value to -1.

On-demand check​

We can also request the server to check changes in the ScalarDB schema and rebuild the corresponding GraphQL schema if necessary by performing a POST request to the /update-graphql-schema endpoint of the HTTP API.

For example, if the HTTP API is running on localhost on port 8080 and the scalar.db.graphql.path property is set to /graphql. This endpoint can be called with :

 curl -X POST http://localhost:8080/graphql/update-graphql-schema

Docker​

Build​

This builds the ScalarDB GraphQL Server Docker image:

./gradlew docker

Run​

This runs the ScalarDB GraphQL Server (you need to specify your local configuration file path with -v flag):

docker run -d -p 8080:8080 \
  -v <ScalarDB properties file path>:/scalardb-graphql/database.properties.tmpl \
  ghcr.io/scalar-labs/scalardb-graphql:<version>

# For DEBUG logging
docker run -d -p 8080:8080 \
  -v <ScalarDB properties file path>:/scalardb-graphql/database.properties.tmpl \
  -e SCALAR_DB_GRAPHQL_LOG_LEVEL=DEBUG \
  ghcr.io/scalar-labs/scalardb-graphql:<version>

You can also pass the database settings via environment variables:

docker run -d -p 8080:8080 \
  -e SCALAR_DB_CONTACT_POINTS=cassandra \
  -e SCALAR_DB_CONTACT_PORT=9042 \
  -e SCALAR_DB_USERNAME=cassandra \
  -e SCALAR_DB_PASSWORD=cassandra \
  -e SCALAR_DB_STORAGE=cassandra \
  -e SCALAR_DB_TRANSACTION_MANAGER=consensus-commit \
  -e SCALAR_DB_GRAPHQL_PATH=/graphql \
  -e SCALAR_DB_GRAPHQL_NAMESPACES=namespace1,namespace2 \
  -e SCALAR_DB_GRAPHQL_GRAPHIQL=true \
  -e SCALAR_DB_GRAPHQL_LOG_LEVEL=INFO \
  ghcr.io/scalar-labs/scalardb-graphql:<version>

Docs​