KDV SQL terminal KDV v26.5+

kdv sql opens an interactive SQL session through Kubling’s client gRPC transport. Use it to inspect a Virtual Database, run ad hoc queries or execute one statement from a script without installing a JDBC or PostgreSQL client.

For application integration, use an official gRPC client instead of invoking the terminal as a subprocess.

Before you connect

You need:

• KDV 26.5 or later
• an enabled client gRPC transport
• the transport endpoint and Virtual Database name
• credentials accepted by that Virtual Database

TLS is enabled by default. Use --plaintext only for an isolated local runtime whose gRPC listener is configured without TLS.

Open an interactive session

For a local project, obtain its dynamically assigned gRPC endpoint from project status, then connect with the host-installed CLI:

kdv project status
kdv sql \
  --endpoint 127.0.0.1:<grpc-port> \
  --plaintext \
  --vdb ProviderQuickstartVDB

When the command runs from a generated project’s directory, KDV reads the administrator username and password from local.properties. If credentials are still missing in an interactive terminal, it prompts for the username and reads the password without echo.

For a TLS-enabled remote endpoint, omit --plaintext and identify the user:

kdv sql \
  --endpoint kubling.example.com:50051 \
  --vdb OperationsVDB \
  --username alice

Work in the terminal

End each SQL statement with a semicolon. A statement can span multiple lines. The terminal keeps complete statements in history and supports Ctrl-R search.

Up and Down move within recalled multiline SQL. Shift+Up and Shift+Down move between complete history entries. KDV stores up to 1,000 completed statements in the user’s XDG state directory; the generated container launcher preserves that state across runs.

Execute one statement

Use --execute for a non-interactive command:

kdv sql \
  --endpoint 127.0.0.1:<grpc-port> \
  --plaintext \
  --vdb ProviderQuickstartVDB \
  --execute 'SELECT * FROM planning.PROJECT'

For automation, supply credentials through the execution environment or its secret manager rather than placing a password in shell history.

Connection and display options

Automatic display uses a table for compact results and switches wide results to expanded records without truncating values. --max-rows bounds only what the terminal retains for display: the query still runs normally and the client consumes the complete server stream. When the server provides structured diagnostics, the terminal preserves the stable Kubling error identifier.

Environment variables

The terminal accepts:

• KUBLING_GRPC_TARGET
• KUBLING_GRPC_PLAINTEXT
• KUBLING_GRPC_VDB
• KUBLING_GRPC_VDB_VERSION
• KUBLING_GRPC_USERNAME
• KUBLING_GRPC_PASSWORD

Explicit command options take precedence over environment variables. Environment credentials take precedence over the properties file, and the interactive prompts are the final fallback. The VDB name is never inferred or prompted.