Skip to content

YDB Java v2 Migration Guide

Jump to bottom
Alexandr Gorshenin edited this page Nov 21, 2022 · 2 revisions

YDB Java SDK V2 has some major changed compared to YDB Java SDK v1.
This guide contains summary of changes and a set of instructions to apply the to your V1 application.

New structure of SDK modules

Usage in maven projects

Before After 
<!-- YDB Java SDK v1 -->
<dependency>
    <groupId>com.yandex.ydb</groupId>
    <artifactId>ydb-sdk-core</artifactId>
    <version>1.14.8</version>
</dependency>
<dependency>
    <groupId>com.yandex.ydb</groupId>
    <artifactId>ydb-sdk-table</artifactId>
    <version>1.14.8</version>
</dependency>

<!-- If you want to use Yandex Cloud authentication provider -->
<dependency>
    <groupId>com.yandex.ydb</groupId>
    <artifactId>ydb-sdk-auth-iam</artifactId>
    <version>1.14.8</version>
</dependency>
 
<!-- YDB Java SDK v2 -->
<dependency>
   <groupId>tech.ydb</groupId>
   <artifactId>ydb-sdk-core</artifactId>
   <version>2.0.1</version>
</dependency>
<dependency>
   <groupId>tech.ydb</groupId>
   <artifactId>ydb-sdk-table</artifactId>
   <version>2.0.1</version>
</dependency>

<!-- If you want to use Yandex Cloud authentication provider -->
<dependency>
   <groupId>tech.ydb.auth</groupId>
   <artifactId>yc-auth-provider</artifactId>
   <version>2.0.1</version>
</dependency>

List of key changes

1. All SDK classes have been moved from package com.yandex.ydb to tech.ydb

As part of the migration, you can simply run the autocorrect script (be careful if you are using package com.yandex.ydb for your own classes)

$ find . -type f \( -name '*.java' -or -name '*.xml' -or -name '*.proto' \) -exec sed -i 's#com.yandex.ydb#tech.ydb#g' {} + ;

2. SDK initialization has been changed

  • The RpcTransport class has been removed, use GrpcTransport instead
  • The GrpcTableRpc class has been removed, no longer needed
  • The TableClient::newClient(GrpcTableRpc) method has been changed to TableClient::newClient(GrpcTransport)
    Note that since there is no ownTransport method, you must manually close GrpcTransport
Before After 
// Creating of transport
GrpcTransport transport = ...;
// Creating of table client
TableClient tableClient = TableClient
    .newClient(GrpcTableRpc.ownTransport(transport))
    .build());
...

// We don't need to close transport
// because client owns it and closes it
tableClient.close();
 
// Creating of transport
GrpcTransport transport = ...;
// Creating of table client
TableClient tableClient = TableClient
    .newClient(transport)
    .build());
...

tableClient.close();
// We must close transport because table
// client uses it but doesn't own it
transport.close();

3. Client-side query cache has been removed, server-side query cache is enabled by default

  • The TableClient.Builder::queryCacheSize(int size) method has been removed, just remove all its calls
  • Similarly, method invalidateQueryCache() has been removed from %%Session%%
  • In turn, in the ExecuteDataQuerySettings class, caching on the server is enabled by default, and there is no need for the enableQueryCache() method. If you still need to disable caching, you can use the disableQueryCache() method

4. Session pool is now required when using TableClient

  • Method of manually creating a session TableClient.createSession(CreateSessionSettings) has been removed
  • Method of getting a session from a pool has been renamed from TableClient.getOrCreateSession(Duration) to TableClient.createSession(Duration)
  • In the Session class, instead of three methods close(), close(CloseSessionSettings) and release(), only one close() has been left, which returns the session to pool for further use, and it has been changed to comply with the AutoCloseable interface - without return value
  • The getDisconnectedCount() method has been removed from the SessionPoolStats session pool statistics class - the new session pool doesn't store disconnected sessions, but immediately closes them on the server
  • If for some reason you do not need to use a session pool, you can use the SimpleTableClient class, compatible with TableClient . Its method createSession(Duration) creates a session on server and method Session.close() removes the session from server.

5. Base classes Result, Status and UnexpectedResultException have been updated

  • The Status class now contains three members - a code of operation, an optional issue list and an optional cost of the request consumedRu
  • The Status.expect(String) method has been renamed to Status.expectSuccess(String)
  • The UnexpectedResultException exception instead of storing the code of operation and the issue list - now contains status. Accordingly, instead of the methods getStatusCode() and getIssues() you should use getStatus().getCode() and getStatus().getIssues()
  • Similarly, in Result, the methods getCode() and toStatus() have been replaced with the method getStatus(), and the method expect(String) has been replaced with the method getValue()
  • The Result class hasn't method cast() anymore. You can use the map(null) method to cast one error result to another.

6. YDB types and values have been updated

  • Some types have been renamed: String -> Bytes, Utf8 -> Text, Float32 -> Float, Float64 -> Double
  • Primitive types have become enum constants instead of static methods
    PrimitiveType.uint64() -> PrimitiveType.Uint64
    PrimitiveType.timestamp() -> PrimitiveType.Timestamp
    PrimitiveType.string() -> PrimitiveType.Bytes
    PrimitiveType.utf8() -> PrimitiveType.Text
    PrimitiveType.float64() -> PrimitiveType.Double
  • Methods of creating values are now prefixed with 'new'
    PrimitiveValue.int32(value) -> PrimitiveValue.newInt32(value)
    PrimitiveValue.timestamp(value) -> PrimitiveValue.newTimestamp(value)
    PrimitiveValue.string(value) -> PrimitiveValue.newBytes(value)
    PrimitiveValue.utf8(value) -> PrimitiveValue.newText(value)
    PrimitiveValue.float64(value) -> PrimitiveValue.newDouble(value)

7. The Decimal type has been fixed

Now it works correctly with scaled numbers. When migrating, make sure that you work correctly with values ​​of this type.

8. Partitioning settings have been moved from CreateTableSettings to TableDescription

The current partitioning settings can be found in TableDescription obtained from describeTable

9. The setDeadlineAfter method has been removed from the RequestSettings class and its inheritors

We recommend to use the setTimeout method instead.

Clone this wiki locally