Update code snippets for Java SDK & JDBC (ydb-platform#14068)

azevaykin · Feb 3, 2025 · ec53355 · ec53355
1 parent c5cd3b8
commit ec53355
Show file tree

Hide file tree

Showing 19 changed files with 454 additions and 48 deletions.
diff --git a/ydb/docs/en/core/recipes/ydb-sdk/auth-access-token.md b/ydb/docs/en/core/recipes/ydb-sdk/auth-access-token.md
@@ -100,22 +100,42 @@ Below are examples of the code for authentication using a token in different {{
 - Java
 
   ```java
-  public void work(String connectionString, String accessToken) {
+  public void work(String accessToken) {
       AuthProvider authProvider = new TokenAuthProvider(accessToken);
 
-      GrpcTransport transport = GrpcTransport.forConnectionString(connectionString)
+      GrpcTransport transport = GrpcTransport.forConnectionString("grpcs://localohost:2135/local")
               .withAuthProvider(authProvider)
-              .build();
+              .build());
 
-      TableClient tableClient = TableClient.newClient(transport).build();
+      QueryClient queryClient = QueryClient.newClient(transport).build();
 
-      doWork(tableClient);
+      doWork(queryClient);
 
-      tableClient.close();
+      queryClient.close();
       transport.close();
   }
   ```
 
+- JDBC
+
+  ```java
+  public void work() {
+      // Connect with the specified token value
+      Properties props1 = new Properties();
+      props1.setProperty("token", "AQAD-XXXXXXXXXXXXXXXXXXXX");
+      try (Connection connection = DriverManager.getConnection("jdbc:ydb:grpc://localhost:2136/local", props1)) {
+        doWork(connection);
+      }
+
+      // Connect with the token value read from the specified file path
+      Properties props2 = new Properties();
+      props2.setProperty("tokenFile", "~/.ydb_token");
+      try (Connection connection = DriverManager.getConnection("jdbc:ydb:grpc://localhost:2136/local", props2)) {
+        doWork(connection);
+      }
+  }
+  ```
+
 - Node.js
 
   {% include [auth-access-token](../../_includes/nodejs/auth-access-token.md) %}

diff --git a/ydb/docs/en/core/recipes/ydb-sdk/auth-anonymous.md b/ydb/docs/en/core/recipes/ydb-sdk/auth-anonymous.md
@@ -82,15 +82,26 @@ Below are examples of the code for anonymous authentication in different {{ ydb-
               .withAuthProvider(authProvider)
               .build());
 
-      TableClient tableClient = TableClient.newClient(transport).build();
+      QueryClient queryClient = QueryClient.newClient(transport).build();
 
-      doWork(tableClient);
+      doWork(queryClient);
 
-      tableClient.close();
+      queryClient.close();
       transport.close();
   }
   ```
 
+- JDBC
+
+  ```java
+  public void work() {
+      // Without additional properties, the driver uses anonymous authentication
+      try (Connection connection = DriverManager.getConnection("jdbc:ydb:grpc://localhost:2136/local")) {
+        doWork(connection);
+      }
+  }
+  ```
+
 - Node.js
 
   {% include [auth-anonymous](../../_includes/nodejs/auth-anonymous.md) %}

diff --git a/ydb/docs/en/core/recipes/ydb-sdk/auth-env.md b/ydb/docs/en/core/recipes/ydb-sdk/auth-env.md
@@ -78,17 +78,17 @@ Below are examples of the code for authentication using environment variables in
 
   ```java
   public void work(String connectionString) {
-      AuthProvider authProvider = CloudAuthHelper.getAuthProviderFromEnviron();
+      AuthProvider authProvider = new EnvironAuthProvider();
 
       GrpcTransport transport = GrpcTransport.forConnectionString(connectionString)
               .withAuthProvider(authProvider)
               .build());
 
-      TableClient tableClient = TableClient.newClient(transport).build();
+      QueryClient queryClient = QueryClient.newClient(transport).build();
 
-      doWork(tableClient);
+      doWork(queryClient);
 
-      tableClient.close();
+      queryClient.close();
       transport.close();
   }
   ```

diff --git a/ydb/docs/en/core/recipes/ydb-sdk/auth-metadata.md b/ydb/docs/en/core/recipes/ydb-sdk/auth-metadata.md
@@ -81,15 +81,32 @@ Below are examples of the code for authentication using environment variables in
               .withAuthProvider(authProvider)
               .build());
 
-      TableClient tableClient = TableClient.newClient(transport).build();
+      QueryClient queryClient = QueryClient.newClient(transport).build();
 
-      doWork(tableClient);
+      doWork(queryClient);
 
-      tableClient.close();
+      queryClient.close();
       transport.close();
   }
   ```
 
+- JDBC
+
+  ```java
+  public void work() {
+      Properties props = new Properties();
+      props.setProperty("useMetadata", "true");
+      try (Connection connection = DriverManager.getConnection("jdbc:ydb:grpc://localhost:2136/local", props)) {
+        doWork(connection);
+      }
+
+      // Option useMetadata can be added to a JDBC URL directly
+      try (Connection connection = DriverManager.getConnection("jdbc:ydb:grpc://localhost:2136/local?useMetadata=true")) {
+        doWork(connection);
+      }
+  }
+  ```
+
 - Node.js
 
   {% include [auth-metadata](../../_includes/nodejs/auth-metadata.md) %}

diff --git a/ydb/docs/en/core/recipes/ydb-sdk/auth-service-account.md b/ydb/docs/en/core/recipes/ydb-sdk/auth-service-account.md
@@ -85,15 +85,32 @@ Below are examples of the code for authentication using a service account file i
               .withAuthProvider(authProvider)
               .build());
 
-      TableClient tableClient = TableClient.newClient(transport).build();
+      QueryClient queryClient = QueryClient.newClient(transport).build();
 
-      doWork(tableClient);
+      doWork(queryClient);
 
-      tableClient.close();
+      queryClient.close();
       transport.close();
   }
   ```
 
+- JDBC
+
+  ```java
+  public void work() {
+      Properties props = new Properties();
+      props.setProperty("saKeyFile", "~/keys/sa_key.json");
+      try (Connection connection = DriverManager.getConnection("jdbc:ydb:grpc://localhost:2136/local", props)) {
+        doWork(connection);
+      }
+
+      // Option saKeyFile can be added to a JDBC URL directly
+      try (Connection connection = DriverManager.getConnection("jdbc:ydb:grpc://localhost:2136/local?saKeyFile=~/keys/sa_key.json")) {
+        doWork(connection);
+      }
+  }
+  ```
+
 - Node.js
 
   Loading service account data from a file:

diff --git a/ydb/docs/en/core/recipes/ydb-sdk/auth-static.md b/ydb/docs/en/core/recipes/ydb-sdk/auth-static.md
@@ -52,15 +52,33 @@ Below are examples of the code for authentication based on a username and token
               .withAuthProvider(authProvider)
               .build());
 
-      TableClient tableClient = TableClient.newClient(transport).build();
+      QueryClient queryClient = QueryClient.newClient(transport).build();
 
-      doWork(tableClient);
+      doWork(queryClient);
 
-      tableClient.close();
+      queryClient.close();
       transport.close();
   }
   ```
 
+- JDBC
+
+  ```java
+  public void work(String username, String password) {
+      Properties props = new Properties();
+      props.setProperty("username", username);
+      props.setProperty("password", password);
+      try (Connection connection = DriverManager.getConnection("jdbc:ydb:grpc://localhost:2136/local", props)) {
+        doWork(connection);
+      }
+
+      // Username and password can be passed via the special method of DriverManager
+      try (Connection connection = DriverManager.getConnection("jdbc:ydb:grpc://localhost:2136/local", username, password)) {
+        doWork(connection);
+      }
+  }
+  ```
+
 - Node.js
 
   {% include [auth-static](../../_includes/nodejs/auth-static.md) %}

diff --git a/ydb/docs/en/core/recipes/ydb-sdk/bulk-upsert.md b/ydb/docs/en/core/recipes/ydb-sdk/bulk-upsert.md
@@ -84,4 +84,87 @@ Below are code examples showing the {{ ydb-short-name }} SDK built-in tools for
 
   For bulk upsert, use [transactional upsert](./upsert.md).
 
+- Java
+
+  ```java
+    private static final String TABLE_NAME = "bulk_upsert";
+    private static final int BATCH_SIZE = 1000;
+
+    public static void main(String[] args) {
+        String connectionString = args[0];
+
+        try (GrpcTransport transport = GrpcTransport.forConnectionString(connectionString)
+                .withAuthProvider(NopAuthProvider.INSTANCE) // use anonymous credentials
+                .build()) {
+
+            // For bulk upsert, the full table path needs to be specified
+            String tablePath = transport.getDatabase() + "/" + TABLE_NAME;
+            try (TableClient tableClient = TableClient.newClient(transport).build()) {
+                SessionRetryContext retryCtx = SessionRetryContext.create(tableClient).build();
+                execute(retryCtx, tablePath);
+            }
+        }
+    }
+
+    public static void execute(SessionRetryContext retryCtx, String tablePath) {
+        // table description
+        StructType structType = StructType.of(
+            "app", PrimitiveType.Text,
+            "timestamp", PrimitiveType.Timestamp,
+            "host", PrimitiveType.Text,
+            "http_code", PrimitiveType.Uint32,
+            "message", PrimitiveType.Text
+        );
+
+        // generate batch of records
+        List<Value<?>> list = new ArrayList<>(50);
+        for (int i = 0; i < BATCH_SIZE; i += 1) {
+            // add a new row as a struct value
+            list.add(structType.newValue(
+                "app", PrimitiveValue.newText("App_" + String.valueOf(i / 256)),
+                "timestamp", PrimitiveValue.newTimestamp(Instant.now().plusSeconds(i)),
+                "host", PrimitiveValue.newText("192.168.0." + i % 256),
+                "http_code", PrimitiveValue.newUint32(i % 113 == 0 ? 404 : 200),
+                "message", PrimitiveValue.newText(i % 3 == 0 ? "GET / HTTP/1.1" : "GET /images/logo.png HTTP/1.1")
+            ));
+        }
+
+        // Create list of structs
+        ListValue rows = ListType.of(structType).newValue(list);
+        // Do retry operation on errors with best effort
+        retryCtx.supplyStatus(
+            session -> session.executeBulkUpsert(tablePath, rows, new BulkUpsertSettings())
+        ).join().expectSuccess("bulk upsert problem");
+    }
+  ```
+
+- JDBC
+
+  ```java
+    private static final int BATCH_SIZE = 1000;
+
+    public static void main(String[] args) {
+        String connectionUrl = args[0];
+
+        try (Connection conn = DriverManager.getConnection(connectionUrl)) {
+            try (PreparedStatement ps = conn.prepareStatement(
+                    "BULK UPSERT INTO bulk_upsert (app, timestamp, host, http_code, message) VALUES (?, ?, ?, ?, ?);"
+            )) {
+                for (int i = 0; i < BATCH_SIZE; i += 1) {
+                    ps.setString(1, "App_" + String.valueOf(i / 256));
+                    ps.setTimestamp(2, Timestamp.from(Instant.now().plusSeconds(i)));
+                    ps.setString(3, "192.168.0." + i % 256);
+                    ps.setLong(4,i % 113 == 0 ? 404 : 200);
+                    ps.setString(5, i % 3 == 0 ? "GET / HTTP/1.1" : "GET /images/logo.png HTTP/1.1");
+                    ps.addBatch();
+                }
+
+                ps.executeBatch();
+            }
+        } catch (SQLException e) {
+            e.printStackTrace();
+        }
+    }
+  ```
+
 {% endlist %}
diff --git a/ydb/docs/en/core/recipes/ydb-sdk/init.md b/ydb/docs/en/core/recipes/ydb-sdk/init.md
@@ -99,6 +99,30 @@ Below are examples of the code for connecting to {{ ydb-short-name }} (driver cr
 
   {% endcut %}
 
+- Java
+
+  ```java
+  public void work() {
+      GrpcTransport transport = GrpcTransport.forConnectionString("grpc://localhost:2136/local")
+              .build());
+      // Do work with the transport
+      doWork(transport);
+      transport.close();
+  }
+  ```
+
+- JDBC Driver
+
+  ```java
+  public void work() {
+      // JDBC Driver must be in the classpath for automatic detection
+      Connection connection = DriverManager.getConnection("jdbc:ydb:grpc://localhost:2136/local");
+      // Do work with the connection
+      doWork(connection);
+      connection.close();
+  }
+  ```
+
 - C# (.NET)
 
   ```C#

diff --git a/ydb/docs/en/core/recipes/ydb-sdk/session-pool-limit.md b/ydb/docs/en/core/recipes/ydb-sdk/session-pool-limit.md
@@ -70,11 +70,24 @@ Below are examples of the code for setting the session pool limit in different {
 - Java
 
   ```java
-  this.tableClient = TableClient.newClient(transport)
+  this.queryClient = QueryClient.newClient(transport)
           // 10 - minimum number of active sessions to keep in the pool during the cleanup
           // 500 - maximum number of sessions in the pool
-          .sessionPoolSize(10, 500)
+          .sessionPoolMinSize(10)
+          .sessionPoolMaxSize(500)
           .build();
   ```
 
+- JDBC Driver
+
+  Usually working with JDBC applications use the different connections pools, such as [HikariCP](https://github.com/brettwooldridge/HikariCP) or [C3p0](https://github.com/swaldman/c3p0). By default the {{ ydb-short-name }} JDBC driver detects current count of opened connections and tunes the session pool size itself. So if the application has correct configured `HikariCP` или `C3p0`, it may not configure the session pool.
+
+  Example of HikariCP configuration in `String` application.properties:
+
+  ```properties
+    spring.datasource.url=jdbc:ydb:grpc://localhost:2136/local
+    spring.datasource.driver-class-name=tech.ydb.jdbc.YdbDriver
+    spring.datasource.hikari.maximum-pool-size=100 # maximum size of JDBC connections
+  ```
+
 {% endlist %}