Tasks

StubberDB Run SQL

Executes arbitrary SQL commands against a configured StubberDB connection

# Basic usage

# Parameters

# branch

optional

string

The StubberDB branch to run the SQL query against.

Supported values:

• live
• draft

Default: {{stub.program.branch}}

# role

optional

string

The role to run the SQL query with.

Supported values:

• readonly
• readwrite

Default: readonly

# sql

required

string

The SQL query to execute.

# sql_args

optional

array

Positional values interpolated into sql using pg-format placeholders such as %I for identifiers and %L for literals.

This should be used instead of manual interpolation to ensure proper escaping of values.

sql_args also supports resolver objects for pgvector-enabled queries.
If an argument is an object with a _resolver key, Stubber resolves it before substituting the final value into the SQL query.
If the object only contains _, Stubber uses the openai resolver automatically.

You can also select a named _resolver and specify input explicitly:

Stubber passes arg._ or arg.input to the resolver.

Built-in resolver names:

• openai: OpenAI embedding with model text-embedding-3-small
• voyage: Voyage embedding with model voyage-4-lite
• voyage_multimodal: Voyage multimodal embedding with model voyage-multimodal-3.5

If your task.params.resolvers defines custom resolver settings, those are merged with the built-in defaults before execution.

# stubberdbuuid

optional

string

The stubberdbuuid of the StubberDB configuration to use. If this is omitted, the task uses the default StubberDB configured for the organization.

# Result

# Properties

# command

string

The SQL command that was executed, for example SELECT, INSERT, UPDATE, or DELETE.

# row_count

number

The number of rows returned or affected by the query.

# rows

array

The rows returned by the query. For write operations such as UPDATE or DELETE, this is usually an empty array unless the query explicitly returns rows.

# Examples

# Update data with the readwrite role

Use the readwrite role for statements that modify data.

# Insert data and return the created row

# Use sql_args with pg-format placeholders

Use %I for SQL identifiers such as table or column names, and %L for escaped literal values.

# Use embedding sql_args with pgvector

For pgvector queries, pass a resolver object in sql_args and cast the placeholder to vector in SQL.

If you are new to pgvector itself, see the pgvector getting started guide for extension setup and basic usage.

This is effectively executed with a vector literal in place of the resolver object, for example:

Use _resolver when you want a non-default resolver:

# Bulk insert rows and vectors

You can also use %L with nested arrays to bulk insert rows.
Resolver objects inside each row are resolved before the final SQL is executed.