From 9899dab3490e98478e03538e01da17664a23c64d Mon Sep 17 00:00:00 2001 From: josh-wong Date: Wed, 21 May 2025 04:14:39 +0000 Subject: [PATCH] AUTO: Sync ScalarDB docs in English to docs site repo --- .../version-3.12/scalardb-graphql/index.mdx | 105 ++--------- .../version-3.12/scalardb-sql/index.mdx | 174 ++++-------------- 2 files changed, 50 insertions(+), 229 deletions(-) diff --git a/versioned_docs/version-3.12/scalardb-graphql/index.mdx b/versioned_docs/version-3.12/scalardb-graphql/index.mdx index 289b7af0..5fda61c5 100644 --- a/versioned_docs/version-3.12/scalardb-graphql/index.mdx +++ b/versioned_docs/version-3.12/scalardb-graphql/index.mdx @@ -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="" -bin/scalardb-graphql-server --config -``` - -### 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-graphql/database.properties.tmpl \ - ghcr.io/scalar-labs/scalardb-graphql: - -# For DEBUG logging -docker run -d -p 8080:8080 \ - -v :/scalardb-graphql/database.properties.tmpl \ - -e SCALAR_DB_GRAPHQL_LOG_LEVEL=DEBUG \ - ghcr.io/scalar-labs/scalardb-graphql: -``` - -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: -``` - -## 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). diff --git a/versioned_docs/version-3.12/scalardb-sql/index.mdx b/versioned_docs/version-3.12/scalardb-sql/index.mdx index e73c2bd8..58ca6a94 100644 --- a/versioned_docs/version-3.12/scalardb-sql/index.mdx +++ b/versioned_docs/version-3.12/scalardb-sql/index.mdx @@ -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= -Pgpr.key= -``` - -Or you can also use environment variables, `USERNAME` for your GitHub username and `TOKEN` for your personal access token. - -```console -export USERNAME= -export TOKEN= -``` - -To add the Maven repository using Maven, edit your `~/.m2/settings.xml` file as follows: -```xml - - - - github - - - - - github - - - central - https://repo1.maven.org/maven2 - - - github - https://maven.pkg.github.com/scalar-labs/scalardb-sql - - true - - - - - - - - - github - USERNAME - TOKEN - - - -``` - -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 - - - - com.scalar-labs - scalardb-sql-direct-mode - 3.12.5 - - - - - com.scalar-labs - scalardb-sql-server-mode - 3.12.5 - - -``` - -## 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).