execute_scalar_async

execute_scalar_async executes the query, and returns the first column of the first row in the result set returned by the query. The additional columns or rows are ignored.

Parameters

All command methods also accept keyword-only options=; see Command options.

name	type	description	optional	default
sql	str	the sql query str to execute
params	ParamType	params to substitute in the query		None

param= remains accepted as a 1.x compatibility alias for params=. Pass only one of the two names.

Parameter Shapes

params accepts one parameter record: a mapping, mapping subclass, mutable mapping, or object/dataclass with attributes matching the placeholder names. Top-level list params are only for execute and execute_async; read and scalar methods raise InvalidParameterShapeException for top-level lists before opening a cursor.

params=None, param=None, or omitting both names means there is no parameter object. If the SQL contains pydapper placeholders such as ?id?, every referenced placeholder must be supplied or pydapper raises MissingParameterException before calling the DBAPI. An empty mapping is a real parameter record with no keys. A list inside one parameter record, such as {"ids": []} or {"ids": [1, 2, 3]}, is one value and is reserved for future IN list expansion support.

Tuple-query APIs (query_multiple and query_multiple_async) apply this validation to the complete tuple: the placeholders of every query are scanned and every referenced value is resolved before a cursor is acquired or the first query executes, so a missing parameter in any query means no query reaches the database. This is client-side prevalidation, not transaction atomicity; after validation succeeds, a later query can still fail at runtime after earlier queries have executed.

One Statement Per Call

A pydapper command executes exactly one SQL statement. SQL containing more than one statement raises MultipleStatementsError before a cursor is acquired, so nothing reaches the driver — the refusal is the same on every adapter regardless of what that adapter's DBAPI would have done with the text.

A single trailing ; followed only by whitespace and comments terminates one statement and is accepted. Anything else after a top-level ; — including a second ; — is more than one statement and is refused.

Detection is the same lexical scan pydapper already uses to find ?name? placeholders, so a ; inside single-quoted text, double-quoted text, a -- line comment, or a /* ... */ block comment is ordinary text and does not trip the guard. It is not a SQL parser and has no dialect awareness: a top-level ; inside a PostgreSQL dollar-quoted body (DO $$ ... ; ... $$) or an Oracle anonymous PL/SQL block (BEGIN ... ; ... END;) is refused too.

Known limits

Because it is a lexer and not a parser, the guard is not a security boundary on its own — it is a guard rail. It keys on a top-level ;, and its notion of "literal" and "comment" is one fixed ANSI-flavored set rather than each server's own grammar. Two consequences worth knowing:

• A backslash before a closing quote currently hides a separator. The scanner treats \ as a string escape, which is MySQL's rule but not PostgreSQL's, SQLite's, Oracle's, or SQL Server's. On those, select 'a\'; drop table t is genuinely two statements and the guard does not catch it. This is the most important of the known gaps and is the headline item of #590.
• SQL Server does not need a ; at all. select 1 as a insert into t values (1) is two statements in one T-SQL batch with no separator, and nothing lexical can see that. Detecting it needs a real parser, which pydapper deliberately does not have.
• Dialect-specific literal forms are not recognized yet, so a ; inside a MySQL backtick identifier, a T-SQL bracket identifier, a MySQL # comment, or some BigQuery triple-quoted strings is currently misread — in either direction. Also tracked in #590.

Parameter binding, not this guard, is what actually protects you from injection: pydapper never formats a value into the SQL string.

Run scripts, PL/SQL blocks, and anything else that genuinely needs more than one statement against the DBAPI connection directly:

with pydapper.connect(dsn) as commands:
    cursor = commands.connection.cursor()
    cursor.execute(plsql_block)

Cardinality

• 0 rows: raises NoResultException.
• 1+ rows: returns the first column of the first row.
• SQL NULL in the first column is returned as Python None.

Example

Get the name of the first task owner in the database.

import asyncio

from pydapper import connect_async


async def main():
    async with connect_async() as commands:
        owner_name = await commands.execute_scalar_async("select name from owner")

    print(owner_name)
    # Zach Schumacher


asyncio.run(main())

(This script is complete, it should run "as is")