How to Run ScalarDB GraphQL Server

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

Configure

In addition to the properties in the ScalarDB database.properties file, the GraphQL server reads the following:

• scalar.db.graphql.port ... Port number for the 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 the 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.

Run

We provide a Docker container that contains ScalarDB GraphQL Server (only to enterprise license users). With the container, You can run ScalarDB GraphQL Server as follows (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 \
  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 \
  -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>

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