pluginsdk/abi/proto/v1/db.proto

// db.proto — DB driver messages (WO-WZ-001).
//
// The guest SDK ships a database/sql driver that marshals query text + args
// out through these messages and rows back, so sqlc-generated plugin code
// works unchanged. The host executes on a connection under the per-plugin
// Postgres role. Transactions map to a host-side handle held per guest call
// chain, with a hard deadline so a guest can never pin a connection.

syntax = "proto3";

package abi.v1;

import "google/protobuf/timestamp.proto";

option go_package = "git.dev.alexdunmow.com/block/pluginsdk/abi/v1;abiv1";

// DbValue is one pgx-mappable parameter or column value.
message DbValue {
  oneof kind {
    // SQL NULL (the bool carries no information; true by convention).
    bool null = 1;
    bool bool_value = 2;
    int64 int64_value = 3;
    double float64_value = 4;
    string string_value = 5;
    bytes bytes_value = 6;
    google.protobuf.Timestamp timestamp_value = 7;
    // UUID in canonical string form.
    string uuid_value = 8;
    // JSON/JSONB payload bytes.
    bytes jsonb_value = 9;
    // NUMERIC in decimal string form (lossless).
    string numeric_value = 10;
    // text[] array.
    TextArray text_array_value = 11;
    // uuid[] array (each element canonical string form). Distinct from
    // text_array so the host binds a native uuid[] parameter (letting a query
    // keep `ANY($1::uuid[])` with no text[]-cast workaround) and scans a uuid[]
    // column straight into []uuid.UUID.
    UuidArray uuid_array_value = 12;
  }
}

// TextArray is a Postgres text[] value.
message TextArray {
  repeated string values = 1;
}

// UuidArray is a Postgres uuid[] value; each element is a canonical UUID
// string (matching DbValue.uuid_value's single-UUID encoding).
message UuidArray {
  repeated string values = 1;
}

// DbRow is one result row; values align with DbRowsResponse.columns.
message DbRow {
  repeated DbValue values = 1;
}

// DbError carries a database failure back to the guest driver.
message DbError {
  // Postgres SQLSTATE when available (e.g. "23505"); empty otherwise.
  string code = 1;
  string message = 2;
}

// DbQueryRequest executes a rows-returning statement.
message DbQueryRequest {
  string sql = 1;
  repeated DbValue args = 2;
  // Transaction handle from DbTxBeginResponse; 0 = no transaction
  // (autocommit).
  uint64 tx_handle = 3;
}

// DbRowsResponse returns the full buffered result set.
message DbRowsResponse {
  repeated string columns = 1;
  repeated DbRow rows = 2;
  DbError error = 3;
}

// DbExecRequest executes a statement without returning rows.
message DbExecRequest {
  string sql = 1;
  repeated DbValue args = 2;
  // Transaction handle from DbTxBeginResponse; 0 = no transaction.
  uint64 tx_handle = 3;
}

message DbExecResponse {
  int64 rows_affected = 1;
  DbError error = 2;
}

// DbTxBeginRequest opens a host-side transaction for this call chain.
message DbTxBeginRequest {}

message DbTxBeginResponse {
  // Opaque handle referencing the host-side transaction; never 0 on success.
  uint64 tx_handle = 1;
  DbError error = 2;
}

message DbTxCommitRequest {
  uint64 tx_handle = 1;
}

message DbTxCommitResponse {
  DbError error = 1;
}

message DbTxRollbackRequest {
  uint64 tx_handle = 1;
}

message DbTxRollbackResponse {
  DbError error = 1;
}