db_query

Execute a SQL SELECT query against a database and return the result rows.

Parameters

Context Output

On successful execution:

• {output_key} -- Array of row objects. Each row is a key-value object mapping column names to values.
• {output_key}_count -- Number of rows returned.
• {output_key}_success -- Boolean true.

With the default output_key of "rows", the keys are: rows, rows_count, rows_success.

Example

local flow = Flow.new("query_users")

local db = "sqlite:/tmp/app.db?mode=rwc"

flow:step("query_users", nodes.db_query({
    connection = db,
    query = "SELECT * FROM users WHERE active = ? ORDER BY id LIMIT ? OFFSET ?",
    params = { true },
    max_rows = 100,
    output_key = "users"
}))

flow:step("log_count", nodes.log({
    message = "Found ${ctx.users_count} active users"
})):depends_on("query_users")

return flow

Notes

• The connection string follows the sqlx URL format. For SQLite, use sqlite:/path/to/file?mode=rwc.
• Query parameters use positional ? placeholders. The params array values are bound in order.
• String parameters support context interpolation (${ctx.key}), so you can dynamically construct queries based on upstream step outputs.
• Null values in params are bound as SQL NULL.
• Boolean values are bound as their native SQL type (e.g., INTEGER 0/1 for SQLite).
• Results are streamed from the database, but returned rows are still accumulated into workflow context. Use SQL pagination (LIMIT/OFFSET or keyset pagination) for large datasets.
• IRONFLOW_DB_MAX_ROWS=0 and IRONFLOW_DB_MAX_RESULT_BYTES=0 disable the corresponding global caps. Per-node caps must be greater than zero.

See Also

• db_exec -- Execute INSERT/UPDATE/DELETE statements.