Skip to content

Commit ebcbb09

Browse files
github-actions[bot]josh-wong
github-actions[bot]
and
josh-wong
authored
AUTO: Sync ScalarDB docs in English to docs site repo (#1212)
Co-authored-by: josh-wong <[email protected]>
1 parent 526b00a commit ebcbb09

File tree

2 files changed

+51
-229
lines changed

2 files changed

+51
-229
lines changed

‎versioned_docs/version-3.13/scalardb-graphql/index.mdx‎

Lines changed: 14 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -1,101 +1,23 @@
1-
# ScalarDB GraphQL Server
1+
---
2+
tags:
3+
- Enterprise Premium
4+
displayed_sidebar: docsEnglish
5+
---
26

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

5-
## Build & Install
9+
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.
610

7-
To build and install the ScalarDB GraphQL Server, use `./gradlew installDist`, which will build the source files and install an executable and required jars:
11+
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.
812

9-
```console
10-
./gradlew installDist
11-
```
13+
## Getting started with GraphQL in ScalarDB Cluster
1214

13-
## Run
15+
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.
1416

15-
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:
17+
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).
1618

17-
* `scalar.db.graphql.port` ... Port number for GraphQL server. The default is `8080`.
18-
* `scalar.db.graphql.path` ... Path component of the URL of the GraphQL endpoint. The default is `/graphql`.
19-
* `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.
20-
* `scalar.db.graphql.graphiql` ... Whether the GraphQL server serves [GraphiQL](https://github.com/graphql/graphiql) IDE. The default is `true`.
21-
* `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.
22-
The default interval value is `30000` (30 seconds). Besides, this automatic schema rebuild can be disabled by setting the property value to `-1`.
23-
Refer to the [following section](#creating-or-modifying-the-scalardb-schema-when-the-server-is-running) for more details.
19+
## Transactions with a two-phase commit
2420

25-
To start the ScalarDB GraphQL Server, run the following commands:
21+
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).
2622

27-
```console
28-
cd build/install/graphql
29-
export JAVA_OPTS="<your JVM options>"
30-
bin/scalardb-graphql-server --config <ScalarDB properties file path>
31-
```
32-
33-
### Creating or modifying the ScalarDB schema when the server is running
34-
35-
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
36-
won't reflect the changes unless it is rebuilt. To address this, the GraphQL server provides the following two mechanisms:
37-
38-
#### Periodic check
39-
40-
The server periodically checks if changes in the ScalarDB schema occur and rebuilds the corresponding GraphQL schema
41-
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.
42-
Besides, this periodic check can be disabled by setting the property value to `-1`.
43-
44-
#### On-demand check
45-
46-
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.
47-
48-
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 :
49-
50-
```console
51-
curl -X POST http://localhost:8080/graphql/update-graphql-schema
52-
```
53-
54-
## Docker
55-
56-
### Build
57-
58-
This builds the ScalarDB GraphQL Server Docker image:
59-
60-
```console
61-
./gradlew docker
62-
```
63-
64-
### Run
65-
66-
This runs the ScalarDB GraphQL Server (you need to specify your local configuration file path with `-v` flag):
67-
68-
```console
69-
docker run -d -p 8080:8080 \
70-
-v <ScalarDB properties file path>:/scalardb-graphql/database.properties.tmpl \
71-
ghcr.io/scalar-labs/scalardb-graphql:<version>
72-
73-
# For DEBUG logging
74-
docker run -d -p 8080:8080 \
75-
-v <ScalarDB properties file path>:/scalardb-graphql/database.properties.tmpl \
76-
-e SCALAR_DB_GRAPHQL_LOG_LEVEL=DEBUG \
77-
ghcr.io/scalar-labs/scalardb-graphql:<version>
78-
```
79-
80-
You can also pass the database settings via environment variables:
81-
82-
```console
83-
docker run -d -p 8080:8080 \
84-
-e SCALAR_DB_CONTACT_POINTS=cassandra \
85-
-e SCALAR_DB_CONTACT_PORT=9042 \
86-
-e SCALAR_DB_USERNAME=cassandra \
87-
-e SCALAR_DB_PASSWORD=cassandra \
88-
-e SCALAR_DB_STORAGE=cassandra \
89-
-e SCALAR_DB_TRANSACTION_MANAGER=consensus-commit \
90-
-e SCALAR_DB_GRAPHQL_PATH=/graphql \
91-
-e SCALAR_DB_GRAPHQL_NAMESPACES=namespace1,namespace2 \
92-
-e SCALAR_DB_GRAPHQL_GRAPHIQL=true \
93-
-e SCALAR_DB_GRAPHQL_LOG_LEVEL=INFO \
94-
ghcr.io/scalar-labs/scalardb-graphql:<version>
95-
```
96-
97-
## Docs
98-
99-
* [Getting Started with ScalarDB GraphQL](getting-started-with-scalardb-graphql.mdx)
100-
* [How to run two-phase commit transaction](how-to-run-two-phase-commit-transaction.mdx)
101-
* [Deployment Guide on AWS](aws-deployment-guide.mdx)
23+
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).

‎versioned_docs/version-3.13/scalardb-sql/index.mdx‎

Lines changed: 37 additions & 137 deletions
Original file line numberDiff line numberDiff line change
@@ -1,137 +1,37 @@
1-
# ScalarDB SQL
2-
3-
ScalarDB SQL is an SQL layer for ScalarDB.
4-
Specifically, it parses SQL and converts it to a set of ScalarDB (API) operations.
5-
6-
## Install
7-
8-
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/).
9-
10-
Before you add the dependency, you need to add the Maven repository using your build tool such as Gradle and Maven.
11-
12-
To add the Maven repository using Gradle, add the following repository to your `build.gradle`:
13-
```gradle
14-
repositories {
15-
maven {
16-
url = uri("https://maven.pkg.github.com/scalar-labs/scalardb-sql")
17-
credentials {
18-
username = project.findProperty("gpr.user") ?: System.getenv("USERNAME")
19-
password = project.findProperty("gpr.key") ?: System.getenv("TOKEN")
20-
}
21-
}
22-
}
23-
```
24-
25-
In this case, you need the `gpr.user` property for your GitHub username and the `gpr.key` property for your personal access token.
26-
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:
27-
28-
```console
29-
./gradlew build -Pgpr.user=<your GitHub username> -Pgpr.key=<your personal access token>
30-
```
31-
32-
Or you can also use environment variables, `USERNAME` for your GitHub username and `TOKEN` for your personal access token.
33-
34-
```console
35-
export USERNAME=<your GitHub username>
36-
export TOKEN=<your personal access token>
37-
```
38-
39-
To add the Maven repository using Maven, edit your `~/.m2/settings.xml` file as follows:
40-
```xml
41-
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
42-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
43-
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
44-
http://maven.apache.org/xsd/settings-1.0.0.xsd">
45-
46-
<activeProfiles>
47-
<activeProfile>github</activeProfile>
48-
</activeProfiles>
49-
50-
<profiles>
51-
<profile>
52-
<id>github</id>
53-
<repositories>
54-
<repository>
55-
<id>central</id>
56-
<url>https://repo1.maven.org/maven2</url>
57-
</repository>
58-
<repository>
59-
<id>github</id>
60-
<url>https://maven.pkg.github.com/scalar-labs/scalardb-sql</url>
61-
<snapshots>
62-
<enabled>true</enabled>
63-
</snapshots>
64-
</repository>
65-
</repositories>
66-
</profile>
67-
</profiles>
68-
69-
<servers>
70-
<server>
71-
<id>github</id>
72-
<username>USERNAME</username>
73-
<password>TOKEN</password>
74-
</server>
75-
</servers>
76-
</settings>
77-
```
78-
79-
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.
80-
81-
Please see also the following documents for more details:
82-
- [Working with the Gradle registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-gradle-registry)
83-
- [Working with the Apache Maven registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry)
84-
85-
And then, you can install the library in your application using your build tool such as Gradle and Maven.
86-
87-
To add a dependency on ScalarDB SQL using Gradle, use the following:
88-
```gradle
89-
dependencies {
90-
// For Direct mode
91-
implementation 'com.scalar-labs:scalardb-sql-direct-mode:3.13.2'
92-
93-
// For Server mode
94-
implementation 'com.scalar-labs:scalardb-sql-server-mode:3.13.2'
95-
}
96-
```
97-
98-
To add a dependency using Maven:
99-
```xml
100-
<dependencies>
101-
<!-- For Direct mode -->
102-
<dependency>
103-
<groupId>com.scalar-labs</groupId>
104-
<artifactId>scalardb-sql-direct-mode</artifactId>
105-
<version>3.13.2</version>
106-
</dependency>
107-
108-
<!-- For Server mode -->
109-
<dependency>
110-
<groupId>com.scalar-labs</groupId>
111-
<artifactId>scalardb-sql-server-mode</artifactId>
112-
<version>3.13.2</version>
113-
</dependency>
114-
</dependencies>
115-
```
116-
117-
## Docs
118-
119-
- [Getting Started with ScalarDB SQL](getting-started-with-sql.mdx)
120-
- [Getting Started with ScalarDB JDBC](getting-started-with-jdbc.mdx)
121-
- [ScalarDB SQL API Guide](sql-api-guide.mdx)
122-
- [ScalarDB JDBC Guide](jdbc-guide.mdx)
123-
- [ScalarDB SQL Grammar](grammar.mdx)
124-
- [ScalarDB SQL Command Line interface](../scalardb-cluster/developer-guide-for-scalardb-cluster-with-java-api.mdx#sql-cli)
125-
- [ScalarDB SQL Server](sql-server.mdx)
126-
- [ScalarDB SQL Configurations](configurations.mdx)
127-
- [Guide of Spring Data JDBC for ScalarDB](spring-data-guide.mdx)
128-
- Javadoc
129-
- [scalardb-sql](https://scalar-labs.github.io/scalardb-sql/javadoc/core/index.html) - ScalarDB SQL: A SQL layer for ScalarDB
130-
- [scalardb-direct-mode](https://scalar-labs.github.io/scalardb-sql/javadoc/direct-mode/index.html) - ScalarDB SQL Direct mode
131-
- [scalardb-sql-rpc](https://scalar-labs.github.io/scalardb-sql/javadoc/rpc/index.html) - ScalarDB SQL RPC libraries
132-
- [scalardb-sql-server](https://scalar-labs.github.io/scalardb-sql/javadoc/server/index.html) - ScalarDB SQL Server: A gRPC interface of ScalarDB SQL
133-
- [scalardb-server-mode](https://scalar-labs.github.io/scalardb-sql/javadoc/server-mode/index.html) - ScalarDB SQL Server mode
134-
- [scalardb-sql-jdbc](https://scalar-labs.github.io/scalardb-sql/javadoc/jdbc/index.html) - ScalarDB SQL JDBC: JDBC Driver for ScalarDB SQL
135-
- [scalardb-sql-cli](https://scalar-labs.github.io/scalardb-sql/javadoc/cli/index.html) - ScalarDB SQL CLI: ScalarDB SQL Command Line Interface
136-
- [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
137-
- [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
1+
---
2+
tags:
3+
- Enterprise Premium
4+
displayed_sidebar: docsEnglish
5+
---
6+
7+
# ScalarDB SQL Overview
8+
9+
ScalarDB SQL is an SQL layer for ScalarDB Cluster. Specifically, it parses SQL and converts it to a set of ScalarDB operations.
10+
11+
:::note
12+
13+
ScalarDB SQL is not fully compatible with standard SQL, but it offers a large subset of the SQL language.
14+
15+
:::
16+
17+
## Types of SQL interfaces
18+
19+
ScalarDB SQL has three types of SQL interfaces.
20+
21+
### JDBC
22+
23+
The JDBC interface lets you connect to ScalarDB Cluster by using the standard JDBC API. This is useful for applications that already use JDBC.
24+
25+
For details on how to set up and use the JDBC interface, see the [ScalarDB JDBC Guide](./jdbc-guide.mdx).
26+
27+
### SQL API
28+
29+
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.
30+
31+
For details on how to set up and use the SQL API, see the [ScalarDB SQL API Guide](./sql-api-guide.mdx).
32+
33+
### Spring Data JDBC
34+
35+
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.
36+
37+
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).

0 commit comments

Comments
 (0)