db_query()

Run a query and return the rows as a DataFrame.

Pass values in params, never by formatting them into the SQL. The placeholder style is the driver's: ? for sqlite, duckdb, and sqlserver, and %s for postgres and mysql.

Usage

db_query(
    query: str,
    connection_name: str,
    params: Sequence[Any] | Mapping[str, Any] | None = None,
) -> pd.DataFrame

Arguments

Name	Type	Default	Description
query required	str		The SQL query.
connection_name required	str		The connection's name in the settings. The connection is opened for this query and closed afterward.
params	Sequence[Any] \| Mapping[str, Any] \| None	None	Values for the query's placeholders, as a sequence or a mapping.

Value

The result rows, with the query's column names.

Raises

FrameworkError: When the connection cannot be opened or the query fails.