How ydb-platform/ydb-cpp-sdk works
Purpose and consumption
This repository builds the YDB C++ SDK: a C++ client library for connecting applications to YDB over gRPC. It is not a standalone server or web application. Consumer entry points are the installed public headers and CMake targets, notably include/ydb-cpp-sdk/client/driver/driver.h, include/ydb-cpp-sdk/client/table/table.h, and include/ydb-cpp-sdk/client/topic/client.h. Runnable sample entry points live under examples/, e.g. examples/basic_example/main.cpp.
Build, packaging, and API generation
CMake is the composition boundary for SDK libraries, generated protobuf/grpc code, examples, and installable artifacts: CMakeLists.txt, src/CMakeLists.txt, and cmake/protobuf.cmake. Protocol contracts originate in YDB protobuf definitions such as src/api/protos/ydb_table.proto and gRPC service definitions such as src/api/grpc/ydb_table_v1.proto. Debian packaging publishes the core SDK plus optional IAM and OpenTelemetry plugins through cmake/PackSDK.cmake and scripts/build_cpack_deb_packages.sh.
Driver, discovery, and transport core
TDriver is the principal runtime root: applications configure it with endpoint/database/credentials, then construct service-specific clients. Its implementation is src/client/driver/driver.cpp, backed by shared client abstractions in src/client/common_client/impl/client.cpp. Driver state owns authentication, endpoint selection, and connection lifecycle in src/client/impl/internal/db_driver_state/state.cpp, src/client/impl/internal/db_driver_state/endpoint_pool.cpp, and src/client/impl/internal/grpc_connections/grpc_connections.cpp. This layer separates public client APIs from gRPC channels and discovered YDB endpoints.
Request execution, resilience, and concurrency
Service calls pass through common request construction and status conversion before reaching generated gRPC stubs: src/client/impl/internal/make_request/make.cpp and src/client/impl/internal/plain_status/status.cpp. Retry policy and retry state are centralized rather than embedded per service in src/client/impl/internal/retry/retry.cpp and src/library/retry/retry.cpp. Async execution and background work are provided through the SDK executor/thread-pool layers, including src/client/impl/executor/executor_impl.cpp and src/client/impl/internal/thread_pool/pool.cpp; public APIs expose futures, sessions, callbacks, or event streams as appropriate.
Data APIs: table/query and value boundaries
The table and query clients translate C++ values, parameters, transactions, sessions, and result rows to/from YDB protobuf payloads. Key boundaries are public value/result types in include/ydb-cpp-sdk/client/value/value.h and include/ydb-cpp-sdk/client/result/result.h, with implementations in src/client/value/value.cpp and src/client/result/result.cpp. Stateful table sessions, pooling, request migration, and transactions reside in src/client/table/impl/table_client.cpp, src/client/table/impl/transaction.cpp, and src/client/impl/session/session_pool.cpp. The newer query-service path has analogous session and execution handling in src/client/query/impl/client_session.cpp and src/client/query/impl/exec_query.cpp.
Streaming and control-plane clients
The SDK exposes separate clients for YDB services including scheme, coordination, discovery, import/export, monitoring, secrets, and rate limiting; representative implementations are src/client/scheme/scheme.cpp, src/client/coordination/coordination.cpp, and src/client/discovery/discovery.cpp. Topic messaging is a major asynchronous subsystem: read/write sessions, producer logic, event handling, offsets, deferred commits, and transactions are implemented under src/client/topic/impl/read_session.cpp, src/client/topic/impl/write_session.cpp, and src/client/topic/impl/producer.cpp. Federated Topic adds cross-endpoint observation and federated read/write coordination in src/client/federated_topic/impl/federation_observer.cpp and src/client/federated_topic/impl/federated_topic_impl.cpp.
Security and observability extensions
Credentials support is a pluggable boundary spanning standard credentials, login, IAM, and OAuth2/JWT token exchange: src/client/types/credentials/credentials.cpp, src/client/iam/iam.cpp, and src/client/types/credentials/oauth2_token_exchange/credentials.cpp. TLS trust resources ship with the SDK in src/client/resources/ydb_root_ca.pem. Core metrics/tracing abstractions are implemented in src/client/impl/observability/metrics.cpp and src/client/impl/observability/span.cpp; optional OpenTelemetry adapters are separately built plugins in plugins/metrics/otel/metrics.cpp and plugins/trace/otel/trace.cpp, using vendored OpenTelemetry sources.
Runtime and external dependencies
The material runtime stack is C++17 with gRPC/protobuf for YDB RPCs, OpenSSL for TLS/crypto, and compression libraries used by streaming/codecs. Build dependency discovery and compatibility logic is concentrated in cmake/external_libs.cmake and cmake/FindBrotli.cmake. YDB is the primary external service; IAM/OAuth endpoints may be contacted by credential providers, and optional observability can export through OpenTelemetry integrations.
Main entry points: driver.h Public SDK APIs · client.cpp Common client layer · driver.cpp TDriver · CMakeLists.txt CMake composition
Components 22
Build & distribution
- Runnable examples
examples/basic_example/main.cpp - CMake composition · Builds libraries, generated code, examples, and install artifacts.
CMakeLists.txt - YDB protocol contracts
src/api/protos/ydb_table.proto - Generated RPC code
cmake/protobuf.cmake - Debian SDK packages · Packages core SDK and optional IAM and OpenTelemetry plugins.
cmake/PackSDK.cmake
SDK runtime core
- TDriver · Configures credentials, endpoint, database, and service clients.
src/client/driver/driver.cpp - Common client layer
src/client/common_client/impl/client.cpp - Driver state & endpoints · Owns authentication, discovery, endpoint selection, and lifecycle.
src/client/impl/internal/db_driver_state/state.cpp - gRPC connections
src/client/impl/internal/grpc_connections/grpc_connections.cpp - Request & status pipeline · Constructs requests, invokes stubs, and converts status.
src/client/impl/internal/make_request/make.cpp - Retry & async executor · Central retry policy, futures, and background work.
src/client/impl/executor/executor_impl.cpp
Public APIs
- Public SDK APIs · Driver, table, topic, value, and result interfaces.
include/ydb-cpp-sdk/client/driver/driver.h - Table & query clients · Sessions, transactions, request migration, and query execution.
src/client/table/impl/table_client.cpp - Value & result mapping · Maps C++ values and result rows to protobuf payloads.
include/ydb-cpp-sdk/client/value/value.h - Topic client · Async read/write sessions, producers, offsets, commits, and transactions.
src/client/topic/impl/read_session.cpp - Control-plane clients · Scheme, coordination, discovery, import/export, monitoring, secrets, and rate limits.
src/client/scheme/scheme.cpp
Extensions
- Credential providers · Standard, login, IAM, OAuth2, and JWT token exchange providers.
src/client/types/credentials/credentials.cpp - Observability core
src/client/impl/observability/metrics.cpp - OpenTelemetry plugins
plugins/metrics/otel/metrics.cpp
Other components
- C++ applications · Consume installed SDK headers and CMake targets.
- YDB service · Primary RPC endpoint for SDK clients.
- IAM / OAuth endpoints
Connections 24
- C++ applications → Public SDK APIs: uses
- Runnable examples → Public SDK APIs: demonstrates
- CMake composition → Generated RPC code: runs
- YDB protocol contracts → Generated RPC code: generates from
- Generated RPC code → CMake composition: compiled into SDK
- CMake composition → Debian SDK packages: produces
- Public SDK APIs → TDriver: initializes
- Public SDK APIs → Table & query clients: exposes
- Public SDK APIs → Topic client: exposes
- TDriver → Common client layer: backs clients
- TDriver → Driver state & endpoints: owns
- Driver state & endpoints → Credential providers: authenticates with
- Driver state & endpoints → gRPC connections: selects channels
- Common client layer → Request & status pipeline: executes calls
- Table & query clients → Value & result mapping: maps payloads through
- Table & query clients → Common client layer: uses
- Topic client → Common client layer: uses
- Control-plane clients → Common client layer: uses
- Request & status pipeline → Retry & async executor: schedules and retries
- Request & status pipeline → gRPC connections: calls generated stubs
- gRPC connections → YDB service: gRPC/TLS
- Credential providers → IAM / OAuth endpoints: obtains tokens
- Observability core → OpenTelemetry plugins: optional adapters
- TDriver → Observability core: emits telemetry