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, which is especially useful for pgvector queries.

If an argument is an object with a _resolver key, Stubber resolves it before substituting the final value into the SQL query.

If an argument only contains _, Stubber resolves it with the default resolver.

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

Stubber passes arg._ or arg.input to the resolver.
See Resolvers for the built-in resolver names and defaults.

# 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.

# Resolvers

Resolvers let sql_args values be computed before the final SQL string is generated. The most common use case is turning text or multimodal input into embeddings for pgvector queries.

For each sql_args value, Stubber looks for resolver objects and resolves them before building the final SQL.
Use _resolver to select a named resolver, or use an object with only _ to use the default resolver.
Stubber passes either arg._ or arg.input to the resolver function.

# Built-in resolvers

# Customizing resolvers

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

That means you can keep the built-in provider and type, while overriding details such as model parameters when needed.

For example, you might define a custom named resolver and then reference it from sql_args:

The "default" resolver can also be customized/overridden in this way.
The resolver's params are passed on to the provider API as-is, so you can adjust things like model or outputDimension as needed.

# 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.