Worker & serving

On this page

The worker builder, registration surface, and supported process transports.

class `Worker`

public sealed class Worker

Description

Fluent builder for a VGI worker process — ports vgi-java's Worker builder pattern. Serves over stdio (the default, and what DuckDB's bare-command LOCATION subprocess transport uses) or over an AF_UNIX socket (RunUnixSocketAsync, the LOCATION 'launch:<argv>' pooled-launcher transport). RunTcp / RunHttp and the rest of RunFromArgs 's flag surface land in later milestones. CRITICAL: stdout is the wire channel (stdio mode) or the launcher's discovery-line channel (unix-socket mode) — never write to Console.Out from a registered function or from a worker's own Main ; use Console.Error for any diagnostics.

Public members

public Task RunFromArgsAsync(string[] args, CancellationToken cancellationToken = default) ;

The canonical CLI entry point every worker's Main calls. Understands the launcher transport ( –unix <path> [–idle-timeout <seconds>] ) and defaults to stdio when no flags are given — –http / –tcp / –access-log are parsed by later milestones.

public Task RunStdioAsync(CancellationToken cancellationToken = default) ;

Serves over stdin/stdout until the client disconnects.

public Worker CatalogName(string name) ;

public Worker DatabaseComment(string comment) ;

Declares this worker's database-level comment, surfaced via duckdb_databases().comment (see CatalogRegistry.DatabaseComment).

public Worker DatabaseTags(Dictionary<string, string> tags) ;

Declares this worker's database-level tags, surfaced via duckdb_databases().tags (see CatalogRegistry.DatabaseTags).

public Worker DefaultSchema(string name) ;

public Worker GlobalFunctionPrefix(string prefix) ;

Sets the prefix ( <prefix>_<name> ) every RegisterGlobal* function is published under catalog-wide — see Protocol.CatalogAttachResult.GlobalFunctionPrefix. Leave unset ( "" ) to publish bare names.

public Worker ProtocolVersion(string version) ;

Overrides the declared VGI protocol version — for test fixtures ONLY (e.g. protocol_version/version_mismatch.test 's deliberately-incompatible worker). Every real worker should leave this at DefaultProtocolVersion.

public Worker RegisterAggregate(IAggregateFunction function, string identity = CatalogRegistry.DefaultIdentity) ;

Registers an aggregate function — see RegisterScalar's doc comment for the identity parameter's meaning.

public Worker RegisterCatalog(Protocol.CatalogInfo info, bool exclusive = false) ;

Declares a catalog this worker process serves, visible via the pre- ATTACH discovery table function vgi_catalogs('<location>') — see CatalogRegistry.RegisterCatalog's doc comment (including the exclusive parameter's meaning). Optional: a worker with none declared is still perfectly attachable (this only affects PRE-attach discovery); most single-logical-catalog fixtures never call this.

public Worker RegisterCatalogTable(CatalogTable table, string identity = CatalogRegistry.DefaultIdentity) ;

Registers a real catalog table (queryable as a plain table, e.g. SELECT * FROM catalog.schema.table_name — not just as schema.function_name(…) ) — see CatalogTable's doc comment.

public Worker RegisterCopyFromFormat( Table.ITableFunction handler, string formatName, string? description = null, string? comment = null, Dictionary<string, string>? tags = null, string identity = CatalogRegistry.DefaultIdentity) ;

Registers a COPY … FROM (FORMAT '<formatName>', …) reader — handler is an ordinary Table.ITableFunction (also registered under its own name, exactly as RegisterTable would) whose Table.TableBindParams.CopyFrom/Table.TableInitParams.CopyFrom carry the destination path and DuckDB-required output schema. formatName is the bare (unqualified) name FORMAT '<alias>.<formatName>' will use — see Protocol.CopyFromFormatInfo.FormatName's doc comment.

public Worker RegisterCopyToFormat( Buffering.ITableBufferingFunction handler, string formatName, string? description = null, string? comment = null, Dictionary<string, string>? tags = null, string identity = CatalogRegistry.DefaultIdentity) ;

Registers a COPY … TO (FORMAT '<formatName>', …) writer — handler is an ordinary Buffering.ITableBufferingFunction (also registered under its own name, exactly as RegisterTableBuffering would) whose TableInOut.TableInOutBindParams.CopyTo/ Buffering.TableBufferingProcessParams.CopyTo/ Buffering.TableBufferingCombineParams.CopyTo carry the destination path. formatName — see RegisterCopyFromFormat's doc comment. Buffering.ITableBufferingFunction.SinkOrderDependent is advertised as this format's ordered flag automatically.

public Worker RegisterGlobalAggregate(IAggregateFunction function, string identity = CatalogRegistry.DefaultIdentity) ;

Registers an aggregate function BOTH at its normal schema-qualified name AND catalog-wide — see RegisterGlobalScalar's doc comment.

public Worker RegisterGlobalScalar(IScalarFunction function, string identity = CatalogRegistry.DefaultIdentity) ;

Registers a scalar function BOTH at its normal schema-qualified name AND catalog-wide (callable unqualified, or with GlobalFunctionPrefix) — see CatalogRegistry.GlobalFunctions's doc comment.

public Worker RegisterGlobalTable(ITableFunction function, string identity = CatalogRegistry.DefaultIdentity) ;

Registers a table function BOTH at its normal schema-qualified name AND catalog-wide — see RegisterGlobalScalar's doc comment.

public Worker RegisterGlobalTableBuffering(ITableBufferingFunction function, string identity = CatalogRegistry.DefaultIdentity) ;

Registers a table-buffering function BOTH at its normal schema-qualified name AND catalog-wide — see RegisterGlobalScalar's doc comment.

public Worker RegisterGlobalTableInOut(ITableInOutFunction function, string identity = CatalogRegistry.DefaultIdentity) ;

Registers a table-in-out function BOTH at its normal schema-qualified name AND catalog-wide — see RegisterGlobalScalar's doc comment.

public Worker RegisterMacro(CatalogMacro macro, string identity = CatalogRegistry.DefaultIdentity) ;

Registers a real catalog macro (scalar or table).

public Worker RegisterScalar(IScalarFunction function, string identity = CatalogRegistry.DefaultIdentity) ;

Registers a scalar function. identity is the attach-identity bucket it lives under (see CatalogRegistry's doc comment) — leave it at the default for an ordinary single-logical-catalog worker; set it to a specific attach name (the first argument of ATTACH '<name>' AS … ) only for a fixture that deliberately serves different function sets depending on which name the SAME worker binary was attached under ( same_name_catalogs.test ).

public Worker RegisterSchema(string schemaName, string? comment = null, Dictionary<string, string>? tags = null, string identity = CatalogRegistry.DefaultIdentity) ;

Declares a schema's comment/tags explicitly — optional, see CatalogRegistry.RegisterSchema.

public Worker RegisterSecretType(string name, string description, Apache.Arrow.Schema parametersSchema) ;

Declares a custom DuckDB secret TYPE ( CREATE SECRET (TYPE <name>, …) ) this worker exposes via catalog_attach — a secret type must be declared here at least once for duckdb_secret_types() / CREATE SECRET to know it exists at all. parametersSchema describes the secret's key/value parameters; mark a sensitive field's metadata "redact":"true" so DuckDB masks it in duckdb_secrets() . A function reads a resolved secret of this type via Attributes.SecretAttribute (scalar) or ITableFunction.RequiredSecrets /Internal.SecretsAccessor (table/table-in-out, including dynamic scope-based lookups).

public Worker RegisterSetting(string name, string description, Apache.Arrow.Types.IArrowType type, Apache.Arrow.IArrowArray? defaultValue = null) ;

Declares a global/session DuckDB setting ( SET <name> = … ) this worker exposes via catalog_attach — a setting must be declared here at least once for duckdb_settings() to know it exists at all; a function's own Attributes.SettingAttribute/ RequiredSettings only reads an already-declared setting's current value at bind time. defaultValue is a single-element Arrow array (e.g. new BooleanArray.Builder().Append(false).Build() ) holding the setting's default; pass null for a setting with no default (e.g. a struct-typed setting with no meaningful all-fields default).

public Worker RegisterTable(ITableFunction function, string identity = CatalogRegistry.DefaultIdentity) ;

Registers a table ("producer") function — see RegisterScalar's doc comment for the identity parameter's meaning.

public Worker RegisterTableBuffering(ITableBufferingFunction function, string identity = CatalogRegistry.DefaultIdentity) ;

Registers a table-buffering (Sink+Source) function — see RegisterScalar's doc comment for the identity parameter's meaning.

public Worker RegisterTableInOut(ITableInOutFunction function, string identity = CatalogRegistry.DefaultIdentity) ;

Registers a streaming table-in-out function — see RegisterScalar's doc comment for the identity parameter's meaning.

public Worker RegisterView(CatalogView view, string identity = CatalogRegistry.DefaultIdentity) ;

Registers a real catalog view.

public async Task RunUnixSocketAsync(string path, double idleTimeoutSeconds = 300, CancellationToken cancellationToken = default) ;

Serves over an AF_UNIX domain socket at path — the launcher transport ( LOCATION 'launch:<argv>' ), letting a single worker process amortize its own startup cost across every DuckDB connection/process pointed at the same worker tuple. Follows the worker-side contract in ~/Development/vgi/docs/launcher-protocol.md exactly: binds, emits exactly one UNIX:<abs path> line on stdout (flushed, and nothing else on stdout ever again — logging MUST go to Console.Error), serves each connection on its own task, and self-shuts-down once idleTimeoutSeconds have elapsed with zero connected clients (0 = never times out). Returns once the socket has been closed and every in-flight connection has drained — whether from an idle timeout or cancellationToken being cancelled by the caller (e.g. on SIGTERM/SIGINT).

public const string DefaultProtocolVersion = "1.4.0";

VGI application protocol surface version this worker declares — emitted as the vgi_rpc.protocol_version per-request metadata key and enforced by QueryFarm.VgiRpc.Server.RpcServer (exact major+minor match; patch ignored) at the dispatch boundary, before any method-specific handling runs. Mirrors vgi-python's VgiProtocol.protocol_version /vgi-java's Worker.VGI_PROTOCOL_VERSION — bump rules: MAJOR = backward-incompatible surface change, MINOR = additive, PATCH = worker bug fixes. 1.1.0 added the nullable schema_name field to the bind request. 1.3.0 added global_functions / global_function_prefix to the catalog_attach result (see Protocol.CatalogAttachResult). 1.4.0 added table_function_plan (split-based scan planning) plus split_tokens / row_limit on the init request.