execute

execute can execute a command one or multiple times and return the number of affected rows. This method is usually used to execute insert, update or delete operations.

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	ListParamType, 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=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.

For one execution, pass one parameter record: a mapping, mapping subclass, mutable mapping, or object/dataclass with attributes matching the placeholder names. Falsey values such as 0, False, "", and [] are bound normally.

For multiple executions, pass a top-level list to execute or execute_async. Each list item is one parameter record. An empty top-level list runs zero commands and returns 0. A list inside one parameter record, such as {"ids": []} or {"ids": [1, 2, 3]}, is one value, not executemany input. List expansion for IN clauses is reserved for future support.

Example - Execute Insert

Single

Execute the INSERT statement a single time.

import datetime

from pydapper import connect

with connect() as commands:
    rowcount = commands.execute(
        "insert into task (description, due_date, owner_id) values (?description?, ?due_date?, ?owner_id?)",
        params={"description": "An insert example", "due_date": datetime.date.today(), "owner_id": 1},
    )

print(rowcount)
# 1

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

Multiple

Execute the INSERT statement multiple times, one for each object in the params list.

import datetime

from pydapper import connect

with connect() as commands:
    rowcount = commands.execute(
        "insert into task (description, due_date, owner_id) values (?description?, ?due_date?, ?owner_id?)",
        params=[
            {"description": "An insert example", "due_date": datetime.date.today(), "owner_id": 1},
            {"description": "With multiple inserts!", "due_date": datetime.date.today(), "owner_id": 1},
        ],
    )

print(rowcount)
# 2

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

Example - Execute Update

Single

Execute the UPDATE statement a single time.

from pydapper import connect

with connect() as commands:
    rowcount = commands.execute(
        "update task set description = ?desc? where id = ?id?", params={"desc": "A single update!", "id": 1}
    )

print(rowcount)
# 1

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

Multiple

Execute the UPDATE statement multiple times, one for each object in the params list.

from pydapper import connect

with connect() as commands:
    rowcount = commands.execute(
        "update task set description = ?desc? where id = ?id?",
        params=[{"desc": "A single update!", "id": 1}, {"desc": "No wait, multiple updates!", "id": 2}],
    )

print(rowcount)
# 2

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

Example - Execute Delete

Single

Execute the DELETE statement a single time.

from pydapper import connect

with connect() as commands:
    rowcount = commands.execute("delete from task where id = ?id?", params={"id": 1})

print(rowcount)
# 1

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

Multiple

Execute the DELETE statement multiple times, one for each object in the params list.

from pydapper import connect

with connect() as commands:
    rowcount = commands.execute("delete from task where id = ?id?", params=[{"id": 2}, {"id": 3}])

print(rowcount)
# 2

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