From 3813b58b8e63a481b4ffa0f4d13f0abe42456212 Mon Sep 17 00:00:00 2001 From: josh-wong Date: Tue, 28 Jan 2025 10:24:10 +0000 Subject: [PATCH] AUTO: Sync ScalarDB docs in English to docs site repo --- versioned_docs/version-3.13/requirements.mdx | 56 +++-- .../getting-started-with-scalardb-graphql.mdx | 235 ++++++++++++++++++ .../version-3.13/scalardb-graphql/index.mdx | 101 ++++++++ .../version-3.13/scalardb-sql/index.mdx | 137 ++++++++++ 4 files changed, 507 insertions(+), 22 deletions(-) create mode 100644 versioned_docs/version-3.13/scalardb-graphql/getting-started-with-scalardb-graphql.mdx create mode 100644 versioned_docs/version-3.13/scalardb-graphql/index.mdx create mode 100644 versioned_docs/version-3.13/scalardb-sql/index.mdx diff --git a/versioned_docs/version-3.13/requirements.mdx b/versioned_docs/version-3.13/requirements.mdx index 7f027786..5a3ceee3 100644 --- a/versioned_docs/version-3.13/requirements.mdx +++ b/versioned_docs/version-3.13/requirements.mdx @@ -51,6 +51,7 @@ ScalarDB is middleware that runs on top of the following databases and their ver | Version | Oracle Database 23ai | Oracle Database 21c | Oracle Database 19c | |:------------------|:--------------------|:------------------|:------------------| +| **ScalarDB 3.15** | ✅ | ✅ | ✅ | | **ScalarDB 3.14** | ✅ | ✅ | ✅ | | **ScalarDB 3.13** | ✅ | ✅ | ✅ | | **ScalarDB 3.12** | ✅ | ✅ | ✅ | @@ -63,36 +64,39 @@ ScalarDB is middleware that runs on top of the following databases and their ver -| Version | MySQL 8.1 | MySQL 8.0 | MySQL 5.7 | -|:------------------|:-----------|:-----------|:-----------| -| **ScalarDB 3.14** | ✅ | ✅ | ✅ | -| **ScalarDB 3.13** | ✅ | ✅ | ✅ | -| **ScalarDB 3.12** | ✅ | ✅ | ✅ | -| **ScalarDB 3.11** | ✅ | ✅ | ✅ | -| **ScalarDB 3.10** | ✅ | ✅ | ✅ | -| **ScalarDB 3.9** | ✅ | ✅ | ✅ | -| **ScalarDB 3.8** | ✅ | ✅ | ✅ | -| **ScalarDB 3.7** | ✅ | ✅ | ✅ | +| Version | MySQL 8.4 | MySQL 8.0 | +|:------------------|:----------|:-----------| +| **ScalarDB 3.15** | ✅ | ✅ | +| **ScalarDB 3.14** | ✅ | ✅ | +| **ScalarDB 3.13** | ✅ | ✅ | +| **ScalarDB 3.12** | ✅ | ✅ | +| **ScalarDB 3.11** | ✅ | ✅ | +| **ScalarDB 3.10** | ✅ | ✅ | +| **ScalarDB 3.9** | ✅ | ✅ | +| **ScalarDB 3.8** | ✅ | ✅ | +| **ScalarDB 3.7** | ✅ | ✅ | -| Version | PostgreSQL 15 | PostgreSQL 14 | PostgreSQL 13 | PostgreSQL 12 | -|:------------------|:---------------|:---------------|:---------------|:---------------| -| **ScalarDB 3.14** | ✅ | ✅ | ✅ | ✅ | -| **ScalarDB 3.13** | ✅ | ✅ | ✅ | ✅ | -| **ScalarDB 3.12** | ✅ | ✅ | ✅ | ✅ | -| **ScalarDB 3.11** | ✅ | ✅ | ✅ | ✅ | -| **ScalarDB 3.10** | ✅ | ✅ | ✅ | ✅ | -| **ScalarDB 3.9** | ✅ | ✅ | ✅ | ✅ | -| **ScalarDB 3.8** | ✅ | ✅ | ✅ | ✅ | -| **ScalarDB 3.7** | ✅ | ✅ | ✅ | ✅ | +| Version | PostgreSQL 17 | PostgreSQL 16 | PostgreSQL 15 | PostgreSQL 14 | PostgreSQL 13 | +|:------------------|:--------------|:--------------|:--------------|:--------------|---------------| +| **ScalarDB 3.15** | ✅ | ✅ | ✅ | ✅ | ✅ | +| **ScalarDB 3.14** | ✅ | ✅ | ✅ | ✅ | ✅ | +| **ScalarDB 3.13** | ✅ | ✅ | ✅ | ✅ | ✅ | +| **ScalarDB 3.12** | ✅ | ✅ | ✅ | ✅ | ✅ | +| **ScalarDB 3.11** | ✅ | ✅ | ✅ | ✅ | ✅ | +| **ScalarDB 3.10** | ✅ | ✅ | ✅ | ✅ | ✅ | +| **ScalarDB 3.9** | ✅ | ✅ | ✅ | ✅ | ✅ | +| **ScalarDB 3.8** | ✅ | ✅ | ✅ | ✅ | ✅ | +| **ScalarDB 3.7** | ✅ | ✅ | ✅ | ✅ | ✅ | | Version | Aurora MySQL 3 | Aurora MySQL 2 | |:------------------|:----------------|:----------------| +| **ScalarDB 3.15** | ✅ | ✅ | | **ScalarDB 3.14** | ✅ | ✅ | | **ScalarDB 3.13** | ✅ | ✅ | | **ScalarDB 3.12** | ✅ | ✅ | @@ -105,8 +109,9 @@ ScalarDB is middleware that runs on top of the following databases and their ver -| Version | Aurora PostgreSQL 15 | Aurora PostgreSQL 14 | Aurora PostgreSQL 13 | Aurora PostgreSQL 12 | -|:------------------|:----------------------|:----------------------|:----------------------|:----------------------| +| Version | Aurora PostgreSQL 16 | Aurora PostgreSQL 15 | Aurora PostgreSQL 14 | Aurora PostgreSQL 13 | +|:------------------|:---------------------|:---------------------|:---------------------|:---------------------| +| **ScalarDB 3.15** | ✅ | ✅ | ✅ | ✅ | | **ScalarDB 3.14** | ✅ | ✅ | ✅ | ✅ | | **ScalarDB 3.13** | ✅ | ✅ | ✅ | ✅ | | **ScalarDB 3.12** | ✅ | ✅ | ✅ | ✅ | @@ -121,6 +126,7 @@ ScalarDB is middleware that runs on top of the following databases and their ver | Version | MariaDB 11.4 | MariaDB 10.11 | |:------------------|:--------------|:--------------| +| **ScalarDB 3.15** | ✅ | ✅ | | **ScalarDB 3.14** | ✅ | ✅ | | **ScalarDB 3.13** | ✅ | ✅ | | **ScalarDB 3.12** | ✅ | ✅ | @@ -135,6 +141,7 @@ ScalarDB is middleware that runs on top of the following databases and their ver | Version | SQL Server 2022 | SQL Server 2019 | SQL Server 2017 | |:------------------|:-----------------|:-----------------|:-----------------| +| **ScalarDB 3.15** | ✅ | ✅ | ✅ | | **ScalarDB 3.14** | ✅ | ✅ | ✅ | | **ScalarDB 3.13** | ✅ | ✅ | ✅ | | **ScalarDB 3.12** | ✅ | ✅ | ✅ | @@ -149,6 +156,7 @@ ScalarDB is middleware that runs on top of the following databases and their ver | Version | SQLite 3 | |:------------------|:----------| +| **ScalarDB 3.15** | ✅ | | **ScalarDB 3.14** | ✅ | | **ScalarDB 3.13** | ✅ | | **ScalarDB 3.12** | ✅ | @@ -163,6 +171,7 @@ ScalarDB is middleware that runs on top of the following databases and their ver | Version | YugabyteDB 2 | |:------------------|:-------------| +| **ScalarDB 3.15** | ✅ | | **ScalarDB 3.14** | ✅ | | **ScalarDB 3.13** | ✅ | | **ScalarDB 3.12** | ❌ | @@ -182,6 +191,7 @@ ScalarDB is middleware that runs on top of the following databases and their ver | Version | DynamoDB | |:------------------|:----------| +| **ScalarDB 3.15** | ✅ | | **ScalarDB 3.14** | ✅ | | **ScalarDB 3.13** | ✅ | | **ScalarDB 3.12** | ✅ | @@ -196,6 +206,7 @@ ScalarDB is middleware that runs on top of the following databases and their ver | Version | Cassandra 4.1 | Cassandra 4.0 | Cassandra 3.11 | Cassandra 3.0 | |:------------------|:---------------|:---------------|:----------------|:---------------| +| **ScalarDB 3.15** | ❌ | ❌ | ✅ | ✅ | | **ScalarDB 3.14** | ❌ | ❌ | ✅ | ✅ | | **ScalarDB 3.13** | ❌ | ❌ | ✅ | ✅ | | **ScalarDB 3.12** | ❌ | ❌ | ✅ | ✅ | @@ -210,6 +221,7 @@ ScalarDB is middleware that runs on top of the following databases and their ver | Version | Cosmos DB for NoSQL | |:------------------|:---------------------| +| **ScalarDB 3.15** | ✅ | | **ScalarDB 3.14** | ✅ | | **ScalarDB 3.13** | ✅ | | **ScalarDB 3.12** | ✅ | diff --git a/versioned_docs/version-3.13/scalardb-graphql/getting-started-with-scalardb-graphql.mdx b/versioned_docs/version-3.13/scalardb-graphql/getting-started-with-scalardb-graphql.mdx new file mode 100644 index 00000000..75984016 --- /dev/null +++ b/versioned_docs/version-3.13/scalardb-graphql/getting-started-with-scalardb-graphql.mdx @@ -0,0 +1,235 @@ +# Getting Started with ScalarDB GraphQL + +ScalarDB GraphQL is an interface layer that allows client applications to communicate with a [ScalarDB](https://github.com/scalar-labs/scalardb) database with GraphQL. + +In this Getting Started guide, you will run a GraphQL server on your local machine. + +## Prerequisites + +We assume you have already installed Docker and have access to a ScalarDB-supported database such as Cassandra. Please configure them first by following [Getting Started with ScalarDB](../getting-started-with-scalardb.mdx) if you have not set them up yet. + +You need a Personal Access Token (PAT) to access the Docker image of ScalarDB GraphQL in GitHub Container registry since the image is private. Ask a person in charge to get your account ready. Please read [the official document](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry) for more detail. + +## Set up a database schema + +We use the following simple example schema. + +`emoney.json` + +```json +{ + "emoney.account": { + "transaction": true, + "partition-key": [ + "id" + ], + "clustering-key": [], + "columns": { + "id": "TEXT", + "balance": "INT" + } + } +} +``` + +To apply the schema to your database, download the Schema Loader that matches the version you use from [scalardb releases](https://github.com/scalar-labs/scalardb/releases), and run the following command to load the schema. + +```console +java -jar scalardb-schema-loader-.jar --config /path/to/database.properties -f emoney.json --coordinator +``` + +## Docker login + +`docker login` is required to start the ScalarDB GraphQL Docker image as described in the Prerequisites section. + +```console +# read:packages scope needs to be selected in a personal access token to login +export CR_PAT=YOUR_PERSONAL_ACCESS_TOKEN +echo $CR_PAT | docker login ghcr.io -u USERNAME --password-stdin +``` + +## Configure the GraphQL Server + +Add the following properties to your `database.properties` file. You can change the values as needed. Especially, make sure to set `namespaces` property. The tables in the specified namespaces (it can be a comma-separated list) will be exposed by the GraphQL server. + +```properties +scalar.db.graphql.port=8080 +scalar.db.graphql.path=/graphql +scalar.db.graphql.namespaces=emoney +scalar.db.graphql.graphiql=true +``` + +## Start up the GraphQL Server + +The following command starts up the ScalarDB GraphQL server. The first time you run the command, it will download the Docker image from GitHub Container Registry. + +```console +docker run -v /path/to/database.properties:/scalardb-graphql/database.properties.tmpl -p 8080:8080 ghcr.io/scalar-labs/scalardb-graphql: +``` + +At this point, the server reads the tables in the specified namespaces and generates a GraphQL schema to perform CRUD operations on the them. + +## Run operations from GraphiQL + +If the server is configured with a property `scalar.db.graphql.graphiql=true` (true by default), GraphiQL IDE will be available. When the above example properties are used, the endpoint URL of GraphiQL IDE is `http://localhost:8080/graphql`. Opening that URL with your web browser will take you to the GraphiQL screen. + +Let's insert the first record. In the left pane, paste the following mutation, then push the triangle-shaped `Execute Query` button at the top of the window. + +```graphql +mutation PutUser1 { + account_put(put: {key: {id: "user1"}, values: {balance: 1000}}) +} +``` + +ScalarDB GraphQL always runs queries with transactions. The above query starts a new transaction, executes a ScalarDB Put command, and commits the transaction at the end of the execution. + +The following response from the GraphQL server will appear in the right pane. + +```json +{ + "data": { + "account_put": true + } +} +``` + +The `"data"` field contains the result of the execution. This response shows the `account_put` field of the mutation was successful. The result type of mutations is `Boolean!`, which indicates whether the operation succeeded or not. + +Next, let's get the record you just inserted. Paste the following query next to the previous mutation in the left pane, and click the `Execute Query` button. Since you don't delete the `mutation PutUser1` above, a pull-down will appear below the button, and you can choose which operation should be executed. Choose `GetUser1`. + +```graphql +query GetUser1 { + account_get(get: {key: {id: "user1"}}) { + account { + id + balance + } + } +} +``` + +You should get the following result in the right pane. + +```json +{ + "data": { + "account_get": { + "account": { + "id": "user1", + "balance": 1000 + } + } + } +} +``` + +## Mappings between GraphQL API and ScalarDB Java API + +The automatically generated GraphQL schema defines queries, mutations, and object types for input/output to allow you to run CRUD operations for all the tables in the target namespaces. These operations are designed to match the ScalarDB APIs defined in the [`DistributedTransaction`](https://javadoc.io/doc/com.scalar-labs/scalardb/3.13.2/com/scalar/db/api/DistributedTransaction.html) interface. + +Assuming you have an `account` table in a namespace, the following queries and mutations will be generated. + +| ScalarDB API | GraphQL root type | GraphQL field | +|--------------------------------------------------------|-------------------|------------------------------------------------------------------------------------| +| `get(Get get)` | `Query` | `account_get(get: account_GetInput!): account_GetPayload` | +| `scan(Scan scan)` | `Query` | `account_scan(scan: account_ScanInput!): account_ScanPayload` | +| `put(Put put)` | `Mutation` | `account_put(put: account_PutInput!): Boolean!` | +| `put(java.util.List puts)` | `Mutation` | `account_bulkPut(put: [account_PutInput!]!): Boolean!` | +| `delete(Delete delete)` | `Mutation` | `account_delete(delete: account_DeleteInput!): Boolean!` | +| `delete(java.util.List deletes)` | `Mutation` | `account_bulkDelete(delete: [account_DeleteInput!]!): Boolean!` | +| `mutate(java.util.List mutations)` | `Mutation` | `account_mutate(put: [account_PutInput!]delete: [account_DeleteInput!]): Boolean!` | + +Note that the `scan` field is not generated for a table with no clustering key. This is the reason why `account_scan` field is not available in our `emoney` example in this document. + +You can see all generated GraphQL types in GraphiQL's Documentation Explorer (the `< Docs` link at the top-right corner). + +## Transaction across multiple requests + +This section describes how to run a transaction that spans multiple GraphQL requests. + +The generated schema provides the `@transaction` directive that allows you to identify transactions. This directive can be used with both queries and mutations. + +### Start a transaction before running an operation + +Adding a `@transaction` directive with no arguments to a query or a mutation directs the execution to start a new transaction. + +```graphql +query GetAccounts @transaction { + user1: account_get(get: {key: {id: "user1"}}) { + account { balance } + } + user2: account_get(get: {key: {id: "user2"}}) { + account { balance } + } +} +``` + +You will get a result with a transaction ID in the `extensions` field. The `id` value in the extensions is the transaction ID in which the operation in the request was run. In this case, this is the new ID of the transaction just started by the request. + +```json +{ + "data": { + "user1": { + "account": { + "balance": 1000 + } + }, + "user2": { + "account": { + "balance": 1000 + } + } + }, + "extensions": { + "transaction": { + "id": "c88da8a6-a13f-4857-82fe-45f1ab4150f9" + } + } +} +``` + +### Run an operation in a continued transaction + +To run the next queries or mutations in the transaction you started, specify the transaction ID as the `id` argument of the `@transaction`. The following example will update two accounts you got in the previous example in the same transaction. This represents a transfer of balance from user1's account to user2's account. + +```graphql +mutation Transfer @transaction(id: "c88da8a6-a13f-4857-82fe-45f1ab4150f9") { + user1: account_put(put: {key: {id: "user1"}, values: {balance: 750}}) + user2: account_put(put: {key: {id: "user2"}, values: {balance: 1250}}) +} +``` + +Note that a transaction started with GraphQL has a timeout of 1 minute and will be aborted automatically when it exceeds the timeout. + +### Commit a transaction + +To commit the continued transaction, specify both the `id` and the `commit: true` flag as arguments of the `@transaction` directive. + +```graphql +query GetAndCommit @transaction(id: "c88da8a6-a13f-4857-82fe-45f1ab4150f9", commit: true) { + user1: account_get(get: {key: {id: "user1"}}) { + account { balance } + } + user2: account_get(get: {key: {id: "user2"}}) { + account { balance } + } +} +``` + +Note: If you specify a `commit: true` flag without an `id` argument like `@transaction(commit: true)`, a new transaction is started and committed just for one operation. This is exactly the same as not specifying the `@transaction` directive, as seen in the above examples using GraphiQL. In other words, you can omit the directive itself when it is `@transaction(commit: true)`. + +### Abort/Rollback a transaction + +When you need to abort/rollback a transaction explicitly, you can use the `abort` or `rollback` mutation fields interchangeably (both have the same effect and usage). Note that you cannot mix it with any other operations, so you must specify it alone. + +```graphql +mutation AbortTx @transaction(id: "c88da8a6-a13f-4857-82fe-45f1ab4150f9") { + abort +} +``` +or +```graphql +mutation RollbackTx @transaction(id: "c88da8a6-a13f-4857-82fe-45f1ab4150f9") { + rollback +} +``` \ No newline at end of file diff --git a/versioned_docs/version-3.13/scalardb-graphql/index.mdx b/versioned_docs/version-3.13/scalardb-graphql/index.mdx new file mode 100644 index 00000000..289b7af0 --- /dev/null +++ b/versioned_docs/version-3.13/scalardb-graphql/index.mdx @@ -0,0 +1,101 @@ +# ScalarDB GraphQL Server + +ScalarDB GraphQL Server is an interface layer that allows client applications to communicate with [ScalarDB](https://github.com/scalar-labs/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: + +```console +./gradlew installDist +``` + +## Run + +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: + +* `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. + +To start the ScalarDB GraphQL Server, run the following commands: + +```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) diff --git a/versioned_docs/version-3.13/scalardb-sql/index.mdx b/versioned_docs/version-3.13/scalardb-sql/index.mdx new file mode 100644 index 00000000..dd5a5837 --- /dev/null +++ b/versioned_docs/version-3.13/scalardb-sql/index.mdx @@ -0,0 +1,137 @@ +# 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.13.2' + + // For Server mode + implementation 'com.scalar-labs:scalardb-sql-server-mode:3.13.2' +} +``` + +To add a dependency using Maven: +```xml + + + + com.scalar-labs + scalardb-sql-direct-mode + 3.13.2 + + + + + com.scalar-labs + scalardb-sql-server-mode + 3.13.2 + + +``` + +## 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](command-line-interface.mdx) +- [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