Skip to content

AUTO: Docs repo sync - ScalarDB #1213

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 21, 2025
Merged

AUTO: Docs repo sync - ScalarDB #1213

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 13 additions & 92 deletions versioned_docs/version-3.12/scalardb-graphql/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,101 +1,22 @@
# ScalarDB GraphQL Server
---
tags:
- Enterprise Premium
---

ScalarDB GraphQL Server is an interface layer that allows client applications to communicate with [ScalarDB](https://github.com/scalar-labs/scalardb) with GraphQL.
# ScalarDB GraphQL Overview

## Build & Install
ScalarDB GraphQL is an interface layer that allows client applications to communicate with ScalarDB Cluster by using GraphQL. It enables you to take advantage the benefits of GraphQL, such as flexible data retrieval and type safety, while benefiting from the transaction management and data access features in ScalarDB.

To build and install the ScalarDB GraphQL Server, use `./gradlew installDist`, which will build the source files and install an executable and required jars:
By using ScalarDB GraphQL, you can create GraphQL schemas automatically based on the ScalarDB schemas, perform CRUD operations, and execute complex transactions across multiple databases. The interface simplifies backend development by providing a unified querying mechanism, making it particularly useful for modern applications expecting advanced and responsive data interactions.

```console
./gradlew installDist
```
## Getting started with GraphQL in ScalarDB Cluster

## Run
ScalarDB GraphQL is designed to be intuitive and user-friendly, enabling developers to easily create GraphQL schemas automatically based on the ScalarDB schemas and interact with the underlying databases.

In addition to the configurations described in [Transaction manager configurations](../configurations.mdx#transaction-manager-configurations) and [Other configurations](../configurations.mdx#other-configurations), the GraphQL server reads the following:
For details on how to set up ScalarDB Cluster with GraphQL support, see [Getting Started with ScalarDB Cluster GraphQL](../scalardb-cluster/getting-started-with-scalardb-cluster-graphql.mdx).

* `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](https://github.com/graphql/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](#creating-or-modifying-the-scalardb-schema-when-the-server-is-running) for more details.
## Transactions with a two-phase commit

To start the ScalarDB GraphQL Server, run the following commands:
ScalarDB GraphQL supports executing transactions with a two-phase commit interface. By using the two-phase commit interface, you can execute a transaction that spans multiple processes/applications (for example, microservices applications).

```console
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 :

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

## Docker

### Build

This builds the ScalarDB GraphQL Server Docker image:

```console
./gradlew docker
```

### Run

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

```console
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:

```console
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

* [Getting Started with ScalarDB GraphQL](getting-started-with-scalardb-graphql.mdx)
* [How to run two-phase commit transaction](how-to-run-two-phase-commit-transaction.mdx)
* [Deployment Guide on AWS](aws-deployment-guide.mdx)
For details on how to execute transactions by using the two-phase commit interface in ScalarDB GraphQL, see [How to Run Two-Phase Commit Transactions](./how-to-run-two-phase-commit-transaction.mdx).
174 changes: 37 additions & 137 deletions versioned_docs/version-3.12/scalardb-sql/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,137 +1,37 @@
# ScalarDB SQL

ScalarDB SQL is an SQL layer for ScalarDB.
Specifically, it parses SQL and converts it to a set of ScalarDB (API) operations.

## Install

The libraries for ScalarDB SQL are available on the [Maven Central Repository](https://mvnrepository.com/artifact/com.scalar-labs/scalardb-sql) and as [packages on GitHub](https://github.com/orgs/scalar-labs/packages?repo_name=scalardb-sql). Since they are available under a commercial license, you need to get a license and permission to access them. For more details, please [contact us](https://scalar-labs.com/contact_us/).

Before you add the dependency, you need to add the Maven repository using your build tool such as Gradle and Maven.

To add the Maven repository using Gradle, add the following repository to your `build.gradle`:
```gradle
repositories {
maven {
url = uri("https://maven.pkg.github.com/scalar-labs/scalardb-sql")
credentials {
username = project.findProperty("gpr.user") ?: System.getenv("USERNAME")
password = project.findProperty("gpr.key") ?: System.getenv("TOKEN")
}
}
}
```

In this case, you need the `gpr.user` property for your GitHub username and the `gpr.key` property for your personal access token.
So you need to have the properties in `~/.gradle/gradle.properties`, or specify the properties with the `-P` option when running the `./gradlew` command as follows:

```console
./gradlew build -Pgpr.user=<your GitHub username> -Pgpr.key=<your personal access token>
```

Or you can also use environment variables, `USERNAME` for your GitHub username and `TOKEN` for your personal access token.

```console
export USERNAME=<your GitHub username>
export TOKEN=<your personal access token>
```

To add the Maven repository using Maven, edit your `~/.m2/settings.xml` file as follows:
```xml
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
http://maven.apache.org/xsd/settings-1.0.0.xsd">

<activeProfiles>
<activeProfile>github</activeProfile>
</activeProfiles>

<profiles>
<profile>
<id>github</id>
<repositories>
<repository>
<id>central</id>
<url>https://repo1.maven.org/maven2</url>
</repository>
<repository>
<id>github</id>
<url>https://maven.pkg.github.com/scalar-labs/scalardb-sql</url>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
</repositories>
</profile>
</profiles>

<servers>
<server>
<id>github</id>
<username>USERNAME</username>
<password>TOKEN</password>
</server>
</servers>
</settings>
```

In the `servers` tag, add a child `server` tag with an `id`, replacing *USERNAME* with your GitHub username, and *TOKEN* with your personal access token.

Please see also the following documents for more details:
- [Working with the Gradle registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-gradle-registry)
- [Working with the Apache Maven registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry)

And then, you can install the library in your application using your build tool such as Gradle and Maven.

To add a dependency on ScalarDB SQL using Gradle, use the following:
```gradle
dependencies {
// For Direct mode
implementation 'com.scalar-labs:scalardb-sql-direct-mode:3.12.5'

// For Server mode
implementation 'com.scalar-labs:scalardb-sql-server-mode:3.12.5'
}
```

To add a dependency using Maven:
```xml
<dependencies>
<!-- For Direct mode -->
<dependency>
<groupId>com.scalar-labs</groupId>
<artifactId>scalardb-sql-direct-mode</artifactId>
<version>3.12.5</version>
</dependency>

<!-- For Server mode -->
<dependency>
<groupId>com.scalar-labs</groupId>
<artifactId>scalardb-sql-server-mode</artifactId>
<version>3.12.5</version>
</dependency>
</dependencies>
```

## Docs

- [Getting Started with ScalarDB SQL](getting-started-with-sql.mdx)
- [Getting Started with ScalarDB JDBC](getting-started-with-jdbc.mdx)
- [ScalarDB SQL API Guide](sql-api-guide.mdx)
- [ScalarDB JDBC Guide](jdbc-guide.mdx)
- [ScalarDB SQL Grammar](grammar.mdx)
- [ScalarDB SQL Command Line interface](../scalardb-cluster/developer-guide-for-scalardb-cluster-with-java-api.mdx#sql-cli)
- [ScalarDB SQL Server](sql-server.mdx)
- [ScalarDB SQL Configurations](configurations.mdx)
- [Guide of Spring Data JDBC for ScalarDB](spring-data-guide.mdx)
- Javadoc
- [scalardb-sql](https://scalar-labs.github.io/scalardb-sql/javadoc/core/index.html) - ScalarDB SQL: A SQL layer for ScalarDB
- [scalardb-direct-mode](https://scalar-labs.github.io/scalardb-sql/javadoc/direct-mode/index.html) - ScalarDB SQL Direct mode
- [scalardb-sql-rpc](https://scalar-labs.github.io/scalardb-sql/javadoc/rpc/index.html) - ScalarDB SQL RPC libraries
- [scalardb-sql-server](https://scalar-labs.github.io/scalardb-sql/javadoc/server/index.html) - ScalarDB SQL Server: A gRPC interface of ScalarDB SQL
- [scalardb-server-mode](https://scalar-labs.github.io/scalardb-sql/javadoc/server-mode/index.html) - ScalarDB SQL Server mode
- [scalardb-sql-jdbc](https://scalar-labs.github.io/scalardb-sql/javadoc/jdbc/index.html) - ScalarDB SQL JDBC: JDBC Driver for ScalarDB SQL
- [scalardb-sql-cli](https://scalar-labs.github.io/scalardb-sql/javadoc/cli/index.html) - ScalarDB SQL CLI: ScalarDB SQL Command Line Interface
- [scalardb-sql-integration-test](https://scalar-labs.github.io/scalardb-sql/javadoc/integration-test/index.html) - ScalarDB SQL Integration test: Integration tests for ScalarDB SQL
- [scalardb-sql-spring-data](https://scalar-labs.github.io/scalardb-sql/javadoc/spring-data/index.html) - Spring Data JDBC for ScalarDB: Spring Data JDBC integration for ScalarDB
---
tags:
- Enterprise Premium
displayed_sidebar: docsEnglish
---

# ScalarDB SQL Overview

ScalarDB SQL is an SQL layer for ScalarDB Cluster. Specifically, it parses SQL and converts it to a set of ScalarDB operations.

:::note

ScalarDB SQL is not fully compatible with standard SQL, but it offers a large subset of the SQL language.

:::

## Types of SQL interfaces

ScalarDB SQL has three types of SQL interfaces.

### JDBC

The JDBC interface lets you connect to ScalarDB Cluster by using the standard JDBC API. This is useful for applications that already use JDBC.

For details on how to set up and use the JDBC interface, see the [ScalarDB JDBC Guide](./jdbc-guide.mdx).

### SQL API

The SQL API lets you connect to ScalarDB Cluster by using the proprietary and modern Java SQL API. This is useful for applications that do not need to rely on the JDBC interface.

For details on how to set up and use the SQL API, see the [ScalarDB SQL API Guide](./sql-api-guide.mdx).

### Spring Data JDBC

The Spring Data JDBC interface lets you interact with ScalarDB Cluster via Spring Data JDBC repositories and entities. This is useful for applications that already use Spring Data or when you want to integrate ScalarDB Cluster into Spring applications.

For details on how to set up and use the Sprign Data JDBC interface, see the [Guide of Spring Data JDBC for ScalarDB](./spring-data-guide.mdx).