Skip to content

Commit 69730cd

Browse files
anton-bobkovblinkov
anton-bobkov
and
blinkov
authored
Added a section about the JDBC driver (#10147)
Co-authored-by: Ivan Blinkov <ivan@ydb.tech>
1 parent 0d12e54 commit 69730cd

File tree

22 files changed

+283
-3
lines changed

22 files changed

+283
-3
lines changed

‎ydb/docs/en/core/reference/languages-and-apis/index.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Languages and APIs
2+
3+
- [{#T}](jdbc-driver/index.md)

‎ydb/docs/en/core/reference/languages-and-apis/jdbc-driver/_includes/jdbc-url-examples.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# JDBC URL examples
2+
3+
- Local Docker container with anonymous authentication and without TLS:<br/>`jdbc:ydb:grpc://localhost:2136/local`
4+
- Remote self-hosted cluster:<br/>`jdbc:ydb:grpcs://<host>:2135/Root/<testdb>?secureConnectionCertificate=file:~/<myca>.cer`
5+
- A cloud database instance with a token:<br/>`jdbc:ydb:grpcs://<host>:2135/<path/to/database>?token=file:~/my_token`
6+
- A cloud database instance with a service account:<br/>`jdbc:ydb:grpcs://<host>:2135/<path/to/database>?saFile=file:~/sa_key.json`

‎ydb/docs/en/core/reference/languages-and-apis/jdbc-driver/authentication.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Authentication modes
2+
3+
The JDBC Driver for {{ ydb-short-name }} supports the following [authentication modes](../../ydb-sdk/auth.md):
4+
5+
* **Anonymous** is used when a username and password are not specified and no other authentication properties are configured. No authentication credentials are provided.
6+
7+
* **Static credentials** are used when a username and password are specified.
8+
9+
* **Access token** is used when the [`token`](properties.md#token) property is configured. This authentication method requires a {{ ydb-short-name }} authentication token, which can be obtained by executing the following {{ ydb-short-name }} CLI command: `ydb auth get-token`.
10+
11+
* **Metadata** is used when the [`useMetadata`](properties.md#useMetadata) property is set to `true`. This method extracts the authentication data from the metadata of a virtual machine, serverless container, or serverless function running in a cloud environment.
12+
13+
* **Service Account Key** is used when the [`saFile`](properties.md#saFile) property is configured. This method extracts the service account key from a file and uses it for authentication.

‎ydb/docs/en/core/reference/languages-and-apis/jdbc-driver/building.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Building the JDBC driver for {{ ydb-short-name }}
2+
3+
To execute all tests in the project, run the `mvn test` command.
4+
5+
By default, all tests are run using a local {{ ydb-short-name }} instance in Docker (if the host has Docker or Docker Machine installed).
6+
7+
To disable these tests, run: `mvn test -DYDB_DISABLE_INTEGRATION_TESTS=true`

‎ydb/docs/en/core/reference/languages-and-apis/jdbc-driver/index.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# JDBC driver for {{ ydb-short-name }}
2+
3+
The JDBC driver for {{ ydb-short-name }} provides database connectivity for applications written in Java or other programming languages running on JVM, like Kotlin, Scala, etc.
4+
5+
## Download
6+
7+
Download the JDBC driver for {{ ydb-short-name }} from the [latest releases page on GitHub](https://github.com/ydb-platform/ydb-jdbc-driver/releases).
8+
9+
## Documentation
10+
11+
- [{#T}](quickstart.md)
12+
- [{#T}](maven.md)
13+
- [{#T}](authentication.md)
14+
- [{#T}](properties.md)
15+
- [{#T}](building.md)

‎ydb/docs/en/core/reference/languages-and-apis/jdbc-driver/maven.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Using the JDBC driver with Maven
2+
3+
The recommended way to use the {{ ydb-short-name }} JDBC driver in a project is to include it as a Maven dependency. Specify the {{ ydb-short-name }} JDBC driver in the `dependencies` section of `pom.xml`:
4+
5+
```xml
6+
<dependencies>
7+
<dependency>
8+
<groupId>tech.ydb.jdbc</groupId>
9+
<artifactId>ydb-jdbc-driver</artifactId>
10+
<version><!-- actual version --></version>
11+
</dependency>
12+
</dependencies>
13+
```

‎ydb/docs/en/core/reference/languages-and-apis/jdbc-driver/properties.md

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# JDBC driver properties
2+
3+
The JDBC driver for {{ ydb-short-name }} supports the following configuration properties, which can be specified in the [JDBC URL](#jdbc-url-examples) or passed via additional properties:
4+
5+
* `saFile` — service account key for authentication. The valid value is either the content of the JSON file or a file reference. {#saFile}
6+
7+
* `iamEndpoint` — custom IAM endpoint for authentication using a service account key.
8+
9+
* `token` — token value for authentication. The valid value is either the token content or a token file reference. {#token}
10+
11+
* `useMetadata` — indicates whether to use metadata authentication. Valid values are: {#useMetadata}
12+
13+
- `true` — use metadata authentication.
14+
- `false` — do not use metadata authentication.
15+
16+
Default value: `false`.
17+
18+
* `metadataURL` — custom metadata endpoint.
19+
20+
* `localDatacenter` — the name of the data center local to the application being connected.
21+
22+
* `secureConnection` — indicates whether to use TLS. Valid values are:
23+
24+
- `true` — enforce TLS.
25+
- `false` — do not enforce TLS.
26+
27+
The primary way to indicate whether a connection is secure or not is by using the `grpcs://` scheme for secure connections and `grpc://` for insecure connections in the JDBC URL. This property allows overriding it.
28+
29+
* `secureConnectionCertificate` — custom CA certificate for TLS connections. The valid value is either the certificate content or a certificate file reference.
30+
31+
{% note info %}
32+
33+
File references for `saFile`, `token`, or `secureConnectionCertificate` must be prefixed with the `file:` URL scheme, for example:
34+
35+
* `saFile=file:~/mysakey1.json`
36+
* `token=file:/opt/secret/token-file`
37+
* `secureConnectionCertificate=file:/etc/ssl/cacert.cer`
38+
39+
{% endnote %}
40+
41+
## Using the QueryService mode
42+
43+
By default, the JDBC driver currently uses a legacy API for running queries to be compatible with a broader range of {{ ydb-short-name }} versions. However, that API has some extra [limitations](../../../concepts/limits-ydb.md#query). To turn off this behavior and use a modern API called "Query Service", add the `useQueryService=true` property to the JDBC URL.
44+
45+
## JDBC URL examples {#jdbc-url-examples}
46+
47+
{% include notitle [examples](_includes/jdbc-url-examples.md) %}

‎ydb/docs/en/core/reference/languages-and-apis/jdbc-driver/quickstart.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Quick start with JDBC driver
2+
3+
1. Download the [JDBC driver for {{ ydb-short-name }}](https://github.com/ydb-platform/ydb-jdbc-driver/releases).
4+
5+
1. Copy the `.jar` file to the directory specified in the `CLASSPATH` environment variable or load the `.jar` file in your IDE.
6+
7+
1. Connect to {{ ydb-short-name }}. JDBC URL examples:
8+
9+
{% include notitle [examples](_includes/jdbc-url-examples.md) %}
10+
11+
1. Execute queries, for example, [YdbDriverExampleTest.java](https://github.com/ydb-platform/ydb-jdbc-driver/blob/master/jdbc/src/test/java/tech/ydb/jdbc/YdbDriverExampleTest.java).

‎ydb/docs/en/core/reference/languages-and-apis/jdbc-driver/toc_p.yaml

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
items:
2+
- name: Quick start
3+
href: quickstart.md
4+
- name: Using with Maven
5+
href: maven.md
6+
- name: Authentication modes
7+
href: authentication.md
8+
- name: Properties
9+
href: properties.md
10+
- name: Building
11+
href: building.md
12+

‎ydb/docs/en/core/reference/languages-and-apis/toc_p.yaml

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
items:
2+
- name: JDBC driver
3+
href: jdbc-driver/index.md
4+
include:
5+
mode: link
6+
path: jdbc-driver/toc_p.yaml
7+

‎ydb/docs/en/core/reference/toc_p.yaml

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,11 +24,16 @@ items:
2424
include:
2525
mode: link
2626
path: ydb-cli/toc_p.yaml
27-
- name: YDB SDK
27+
- name: YDB Native SDK
2828
href: ydb-sdk/index.md
2929
include:
3030
mode: link
3131
path: ydb-sdk/toc_p.yaml
32+
- name: Languages and APIs
33+
href: languages-and-apis/index.md
34+
include:
35+
mode: link
36+
path: languages-and-apis/toc_p.yaml
3237
- name: Kafka API
3338
href: kafka-api/index.md
3439
include:

‎ydb/docs/ru/core/reference/languages-and-apis/index.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Языки и API
2+
3+
- [{#T}](jdbc-driver/index.md)

‎ydb/docs/ru/core/reference/languages-and-apis/jdbc-driver/_includes/jdbc-url-examples.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Примеры JDBC URL
2+
3+
- Локальный Docker контейнер с анонимной аутентификацией и без TLS:<br/>`jdbc:ydb:grpc://localhost:2136/local`
4+
- Удаленный кластер, размещенный на собственном сервере:<br/>`jdbc:ydb:grpcs://<host>:2135/Root/<testdb>?secureConnectionCertificate=file:~/<myca>.cer`
5+
- Экземпляр облачной базы данных с токеном:<br/>`jdbc:ydb:grpcs://<host>:2135/<path/to/database>?token=file:~/my_token`
6+
- Экземпляр облачной базы данных с файлом сервисного аккаунта:<br/>`jdbc:ydb:grpcs://<host>:2135/<path/to/database>?saFile=file:~/sa_key.json`

‎ydb/docs/ru/core/reference/languages-and-apis/jdbc-driver/authentication.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Режимы аутентификации
2+
3+
JDBC-драйвер для {{ ydb-short-name }} поддерживает следующие [режимы аутентификации](../../ydb-sdk/auth.md):
4+
5+
* **Anonymous** — без аутентификации. Этот режим используется, если не указаны имя пользователя и пароль и не настроены другие методы аутентификации.
6+
7+
* **Static credentials** — используется, если указаны имя пользователя и пароль.
8+
9+
* **Access token** — используется, если указано свойство [`token`](properties.md#token). Требуется {{ ydb-short-name }} токен, который можно получить, выполнив команду `ydb auth get-token` в YDB CLI.
10+
11+
* **Metadata** — используется, если в свойстве [`useMetadata`](properties.md#metadata) указано значение `true`. В этом режиме данные для аутентификации получаются из метаданных виртуальной машины, контейнера serverless или функции serverless, выполненной в облаке.
12+
13+
* **Service account key** — используется, если указано свойство [`saFile`](properties.md#saFile). В этом режиме для аутентификации применяется ключ сервисной учётной записи.

‎ydb/docs/ru/core/reference/languages-and-apis/jdbc-driver/building.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Сборка JDBC-драйвера для {{ ydb-short-name }}
2+
3+
Для запуска всех тестов проекта используется команда `mvn test`.
4+
5+
По умолчанию все тесты выполняются на локальном экземпляре {{ ydb-short-name }} в Docker (при условии, что на хосте установлен Docker или Docker Machine).
6+
7+
Чтобы отключить эти тесты, выполните команду: `mvn test -DYDB_DISABLE_INTEGRATION_TESTS=true`.

‎ydb/docs/ru/core/reference/languages-and-apis/jdbc-driver/index.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# JDBC-драйвер для {{ ydb-short-name }}
2+
3+
JDBC-драйвер для {{ ydb-short-name }} обеспечивает взаимодействие между {{ ydb-short-name }} и приложениями, написанными на Java или других языках программирования, байт-код которых выполняется на JVM. Примеры таких языков — Kotlin и Scala.
4+
5+
## Загрузка
6+
7+
Скачайте JDBC-драйвер для {{ ydb-short-name }} с [страницы Releases на GitHub](https://github.com/ydb-platform/ydb-jdbc-driver/releases).
8+
9+
## Документация
10+
11+
- [{#T}](quickstart.md)
12+
- [{#T}](maven.md)
13+
- [{#T}](authentication.md)
14+
- [{#T}](properties.md)
15+
- [{#T}](building.md)

‎ydb/docs/ru/core/reference/languages-and-apis/jdbc-driver/maven.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Использование JDBC-драйвера с Maven
2+
3+
Рекомендованный способ использования JDBC-драйвера для {{ ydb-short-name }} в проекте — это добавить драйвер как зависимость в Maven. Укажите JDBC-драйвер для {{ ydb-short-name }} в секции `dependencies` файла `pom.xml`:
4+
5+
```xml
6+
<dependencies>
7+
<dependency>
8+
<groupId>tech.ydb.jdbc</groupId>
9+
<artifactId>ydb-jdbc-driver</artifactId>
10+
<version><!-- актуальная версия --></version>
11+
</dependency>
12+
</dependencies>
13+
```

‎ydb/docs/ru/core/reference/languages-and-apis/jdbc-driver/properties.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Свойства JDBC-драйвера
2+
3+
JDBC-драйвер для {{ ydb-short-name }} поддерживает следующие конфигурационные свойства, которые можно указать в [JDBC URL](#jdbc-url) или передать через дополнительные свойства:
4+
5+
* `saFile` — ключ сервисной учётной записи (Service Account Key). Значением свойства может быть содержимое ключа или путь к файлу с ключом. {#saFile}
6+
7+
* `iamEndpoint` — IAM-эндпойнт для аутентификации с помощью ключа сервисной учётной записи (Service Account Key).
8+
9+
* `token` — токен для аутентификации. Значением свойства может быть содержимое токена или путь к файлу с токеном. {#token}
10+
11+
* `useMetadata` — использование режима аутентификации **Metadata**. Возможные значения: {#metadata}
12+
13+
- `true` — использовать режим аутентификации **Metadata**;
14+
- `false` — не использовать режим аутентификации **Metadata**.
15+
16+
Значение по умолчанию: `false`.
17+
18+
* `metadataURL` — эндпойнт для получения токена в режиме аутентификации **Metadata**.
19+
20+
* `localDatacenter` — название локального датацентра, в котором выполняется приложение.
21+
22+
* `secureConnection` — использование TLS. Возможные значения:
23+
24+
- `true` — принудительно использовать TLS;
25+
- `false` — не использовать TLS.
26+
27+
Обычно безопасное соединение указывается с помощью протокола `grpcs://` в строке JDBC URL. Небезопасное соединение указывается с помощью протокола `grpc://`.
28+
29+
* `secureConnectionCertificate` — сертификат CA для TLS-соединения. Значением свойства может быть содержимое сертификата или путь к файлу с сертификатом.
30+
31+
{% note info %}
32+
33+
Ссылки на файлы в свойствах `saFile`, `token` или `secureConnectionCertificate` должны содержать префикс `file:`. Примеры:
34+
35+
* `saFile=file:~/mysakey1.json`
36+
37+
* `token=file:/opt/secret/token-file`
38+
39+
* `secureConnectionCertificate=file:/etc/ssl/cacert.cer`
40+
41+
{% endnote %}
42+
43+
## Использование режима QueryService
44+
45+
По умолчанию JDBC-драйвер для {{ ydb-short-name }} использует старый API для обработки запросов, обеспечивая совместимость с предыдущими версиями {{ ydb-short-name }}. Однако у этого API есть [дополнительные ограничения](../../../concepts/limits-ydb.md#query). Чтобы отключить это поведение и использовать новый API QueryService, укажите свойство `useQueryService=true` в строке JDBC URL.
46+
47+
## Примеры JDBC URL {#jdbc-url}
48+
49+
{% include notitle [примеры](_includes/jdbc-url-examples.md) %}

‎ydb/docs/ru/core/reference/languages-and-apis/jdbc-driver/quickstart.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Быстрый старт
2+
3+
1. Скачайте [JDBC-драйвер для {{ ydb-short-name }}](https://github.com/ydb-platform/ydb-jdbc-driver/releases).
4+
5+
1. Скопируйте JAR-файл в директорию, указанную в переменной окружения `CLASSPATH`, или загрузите JAR-файл в интегрированной среде разработки (IDE).
6+
7+
1. Установите соединение с {{ ydb-short-name }}. Примеры JDBC URL:
8+
9+
{% include notitle [примеры](_includes/jdbc-url-examples.md) %}
10+
11+
1. Выполните проверочный запрос к базе данных {{ ydb-short-name }}. См. пример [YdbDriverExampleTest.java](https://github.com/ydb-platform/ydb-jdbc-driver/blob/master/jdbc/src/test/java/tech/ydb/jdbc/YdbDriverExampleTest.java).

‎ydb/docs/ru/core/reference/languages-and-apis/jdbc-driver/toc_p.yaml

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
items:
2+
- name: Быстрый старт
3+
href: quickstart.md
4+
- name: Использование с Maven
5+
href: maven.md
6+
- name: Режимы аутентификации
7+
href: authentication.md
8+
- name: Свойства
9+
href: properties.md
10+
- name: Сборка
11+
href: building.md
12+

‎ydb/docs/ru/core/reference/languages-and-apis/toc_p.yaml

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
items:
2+
- name: JDBC-драйвер
3+
href: jdbc-driver/index.md
4+
include:
5+
mode: link
6+
path: jdbc-driver/toc_p.yaml
7+

‎ydb/docs/ru/core/reference/toc_p.yaml

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,19 +14,24 @@ items:
1414
path: embedded-ui/toc_p.yaml
1515
- name: Интеграции
1616
href: ../integrations/index.md
17-
include:
17+
include:
1818
mode: link
1919
path: ../integrations/toc_p.yaml
2020
- name: YDB CLI
2121
href: ydb-cli/index.md
2222
include:
2323
mode: link
2424
path: ydb-cli/toc_p.yaml
25-
- name: YDB SDK
25+
- name: YDB Native SDK
2626
href: ydb-sdk/index.md
2727
include:
2828
mode: link
2929
path: ydb-sdk/toc_p.yaml
30+
- name: Языки и API
31+
href: languages-and-apis/index.md
32+
include:
33+
mode: link
34+
path: languages-and-apis/toc_p.yaml
3035
- name: Kafka API
3136
href: kafka-api/index.md
3237
include:

0 commit comments

Comments
 (0)