gRPC clients PREVIEW

Kubling’s client gRPC transport lets applications open a session, execute SQL and manage transactions without depending on JDBC or the PostgreSQL wire protocol. It is the recommended client interface for new services, agents and multi-language applications.

Use a released protocol tag or SDK version for production clients instead of generating them from a moving branch. After login, use GetServerInfo to negotiate the capabilities available to that session.

Client gRPC and Provider gRPC are different interfaces. A client connects to the Kubling Engine to consume a Virtual Database. Kubling connects to a provider to access a physical source. They do not share protobuf services or lifecycle semantics.

Interface	Server	Client	Configuration	Default port
Client gRPC	Kubling Engine	Application or SDK	`transports.grpc`	`50051`
Provider gRPC	External provider	Kubling Engine	VDB data source with `dataSourceType: PROVIDER_GRPC`	`50051`

The same default port is not a conflict when the Engine and provider run on different hosts or containers. Assign distinct ports when both listeners share the same network namespace. The Quickstart sample uses 50061 for the client transport and 50051 for its provider to make the boundary explicit.

What the client API provides v26.5+

The public contract exposes three services:

SessionService authenticates a client, validates a session and logs it out.
QueryService executes SQL, streams typed result events, manages transactions and reports session-bound capabilities.
LobService reads, writes and releases negotiated large-object references.

Execute reports the actual result shape without replaying SQL through a second RPC. Query results, update counts and generated keys share one ordered event stream. The complete RPC, value and lifecycle model is covered in the protocol reference.

Enable the transport

Configure the listener in Kubling’s main application configuration:


transports:
  grpc:
    enable: true
    bindAddress: "0.0.0.0"
    portNumber: 50051
    secure: false

secure: false is appropriate only for local development or an isolated test network. For a production listener, enable TLS, configure its server key store and restrict inbound networks. See Communication security.

When Kubling runs in a container, publish the configured port or attach the client to the same private container network. Enabling a listener inside the container does not expose it automatically on the host.

Use the Quickstart sample

The Quickstart sample disables direct client transports and publishes only Studio’s HTTP endpoint. This keeps its default surface small. You can reuse its deterministic provider-backed VDB for the client examples by enabling and publishing the existing 50061 listener.

Enable client gRPC

In quickstart/app-config.yaml, change the existing gRPC transport to:


transports:
  grpc:
    enable: true
    bindAddress: "0.0.0.0"
    portNumber: 50061
    secure: false

The provider continues listening independently at provider:50051.

Publish the client port

Add the gRPC port to the kubling service in quickstart/compose.yaml:


services:
  kubling:
    ports:
      - "8282:8282"
      - "50061:50061"

If the client runs as another service on the Compose network, it can instead connect to kubling:50061 without publishing the port.

Start or recreate the stack


docker compose up --wait --force-recreate

The client examples use these values:

Setting	Value
Address	`localhost:50061`
Virtual Database	`ProviderQuickstartVDB`
Username	`quickstart`
Password	`quickstart`

The username and password are local placeholders. The sample VDB has no authentication delegate and does not persist them.

Connect a client

Continue with the official Go SDK guide, or use the protobuf contract to build a client in another supported language.

Connect with an official client v26.5+

The official Go SDK wraps channel creation and login. The Java and Python packages provide generated messages, service stubs and shared feature constants, leaving channel policy to the application.

Each example authenticates against the Quickstart VDB and obtains the effective capabilities for that session:

Go


ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
 
cli, err := client.NewClient(client.Options{
    Address:  "localhost:50061",
    Username: "quickstart",
    Password: "quickstart",
    VDBName:  "ProviderQuickstartVDB",
})
if err != nil {
    log.Fatal(err)
}
defer cli.Close()
defer cli.Logout()
 
info, err := cli.QueryService().GetServerInfo(
    ctx,
    &kublingv1.GetServerInfoRequest{
        ExpiringToken: cli.Token(),
    },
)
if err != nil {
    log.Fatal(err)
}
if info.GetCapabilities() == nil {
    log.Fatal("authenticated capabilities are unavailable")
}

Java


var channel = ManagedChannelBuilder
    .forAddress("localhost", 50061)
    .usePlaintext()
    .build();
 
var sessions = SessionServiceGrpc.newBlockingStub(channel);
var login = sessions.login(LoginRequest.newBuilder()
    .setVdbName("ProviderQuickstartVDB")
    .setUsername("quickstart")
    .setPassword("quickstart")
    .build());
 
var query = QueryServiceGrpc.newBlockingStub(channel);
var info = query.getServerInfo(GetServerInfoRequest.newBuilder()
    .setExpiringToken(login.getExpiringToken())
    .build());
 
if (!info.hasCapabilities()) {
    throw new IllegalStateException("authenticated capabilities are unavailable");
}
 
sessions.logout(LogoutRequest.newBuilder()
    .setExpiringToken(login.getExpiringToken())
    .build());
channel.shutdown();

Python


import grpc
 
from kubling.v1 import command_pb2, command_pb2_grpc
 
with grpc.insecure_channel("localhost:50061") as channel:
    sessions = command_pb2_grpc.SessionServiceStub(channel)
    login = sessions.Login(command_pb2.LoginRequest(
        vdb_name="ProviderQuickstartVDB",
        username="quickstart",
        password="quickstart",
    ))
 
    query = command_pb2_grpc.QueryServiceStub(channel)
    info = query.GetServerInfo(command_pb2.GetServerInfoRequest(
        expiring_token=login.expiring_token,
    ))
 
    if not info.HasField("capabilities"):
        raise RuntimeError("authenticated capabilities are unavailable")
 
    sessions.Logout(command_pb2.LogoutRequest(
        expiring_token=login.expiring_token,
    ))

The capability snapshot is scoped to the authenticated session, selected VDB and serving node. Keep the expiring token private, use the returned capability_id for negotiated requests, log out when the session is finished and always close the channel. The plaintext channels above are only for the local Quickstart.