⌘K ctrl+k
Search Shortcut cmd + k | ctrl + k
Executing SQL in Python

SQL queries can be executed using the duckdb.sql function.

import duckdb

duckdb.sql("SELECT 42").show()

By default this will create a relation object. The result can be converted to various formats using the result conversion functions. For example, the fetchall method can be used to convert the result to Python objects.

results = duckdb.sql("SELECT 42").fetchall()
print(results)

[(42,)]

Several other result objects exist. For example, you can use df to convert the result to a Pandas DataFrame.

results = duckdb.sql("SELECT 42").df()
print(results)

    42
 0  42

By default, a global in-memory connection will be used. Any data stored in files will be lost after shutting down the program. A connection to a persistent database can be created using the connect function.

After connecting, SQL queries can be executed using the sql command.

con = duckdb.connect("file.db")
con.sql("CREATE TABLE integers (i INTEGER)")
con.sql("INSERT INTO integers VALUES (42)")
con.sql("SELECT * FROM integers").show()

Query Parameters

To parameterize a query, pass the values separately from the SQL string using the execute method. Use ? for positional parameters, supplying the values as a list:

con.execute("SELECT * FROM integers WHERE i = ?", [42]).fetchall()

Named parameters use the $name syntax, with the values supplied as a dictionary:

con.execute("SELECT * FROM integers WHERE i = $value", {"value": 42}).fetchall()

To run the same parameterized statement for many sets of values, for example when inserting multiple rows, use executemany:

con.executemany("INSERT INTO integers VALUES (?)", [[1], [2], [3]])

The duckdb.sql function also accepts parameters through its params keyword argument.

© 2026 DuckDB Foundation, Amsterdam NL
DuckDB Home Code of Conduct Trademark Use Blog