Skip to main content
A Connection is the primary object in the turso package. Obtain one by calling turso.connect().

​
turso.connect(database, **options)

Opens a Turso (SQLite-compatible) database and returns a Connection. 
import turso

conn = turso.connect("app.db")
conn = turso.connect(":memory:")
​
database
str
required
Path to the database file, or ":memory:" for an in-memory database. The file is created if it does not exist.
​
isolation_level
str | None
default:"DEFERRED"
Default transaction mode used for implicit transactions. Accepted values: "DEFERRED", "IMMEDIATE", "EXCLUSIVE", or None (autocommit-like behavior without automatic BEGIN).
​
experimental_features
str | None
Comma-separated list of experimental features to enable, e.g. "views,encryption".
​
vfs
str | None
VFS backend override. Available: "memory", "syscall", "io_uring" (Linux only).
​
encryption
EncryptionOpts | None
Encryption configuration. Requires "encryption" in experimental_features.
Returns Connection

​
connection.cursor(factory?)

Creates and returns a new Cursor object. 
cur = conn.cursor()
​
factory
callable | None
Optional callable that takes a Connection and returns a Cursor subclass. Defaults to the built-in Cursor.
Returns Cursor — see Cursor for the full method list.

​
connection.execute(sql, parameters?)

Shortcut that creates a cursor, calls cursor.execute(sql, parameters), and returns the cursor. 
cursor = conn.execute("SELECT * FROM users WHERE id = ?", (1,))
​
sql
str
required
SQL statement to execute.
​
parameters
Sequence | Mapping
default:"()"
Bind parameters.
Returns Cursor

​
connection.executemany(sql, seq_of_parameters)

Shortcut that creates a cursor and calls cursor.executemany(sql, seq_of_parameters).
​
sql
str
required
A DML statement (INSERT, UPDATE, DELETE, or REPLACE).
​
seq_of_parameters
Iterable[Sequence]
required
An iterable of parameter sequences, one per execution.
Returns Cursor

​
connection.executescript(sql_script)

Shortcut that creates a cursor and calls cursor.executescript(sql_script).
​
sql_script
str
required
A string of one or more semicolon-separated SQL statements.
Returns Cursor

​
connection.commit()

Commits the current transaction. If isolation_level is not None, a new transaction is begun automatically after the commit to maintain DB-API 2.0 semantics. 
conn.execute("INSERT INTO users (name) VALUES (?)", ("Alice",))
conn.commit()

​
connection.rollback()

Rolls back the current transaction. Any changes made since the last commit() or rollback() are discarded. 
try:
    conn.execute("INSERT INTO users (name) VALUES (?)", ("Bob",))
    # something goes wrong
    raise RuntimeError("oops")
except RuntimeError:
    conn.rollback()

​
connection.close()

Closes the connection. If autocommit is False and a transaction is open, it is implicitly rolled back. 
conn.close()

​
Properties

PropertyTypeDescription
connection.in_transactionboolTrue when a transaction is currently open.
connection.isolation_levelstr | NoneCurrent isolation level setting.
connection.autocommitbool | "LEGACY"Autocommit mode. Set to True, False, or "LEGACY" (default).
connection.row_factorycallable | NoneOptional factory called with (cursor, row) to produce custom row objects.
connection.text_factorycallableCallable used to decode text values. Defaults to str.

​
Context manager

Connection implements the context manager protocol: 
with turso.connect("app.db") as conn:
    conn.execute("INSERT INTO users (name) VALUES (?)", ("Alice",))
# Commits on success, rolls back on exception

​
Exception hierarchy

Turso follows the DB-API 2.0 exception hierarchy: 
Exception
└─ Warning
└─ Error
   ├─ InterfaceError
   └─ DatabaseError
      ├─ DataError
      ├─ OperationalError
      ├─ IntegrityError
      ├─ InternalError
      ├─ ProgrammingError
      └─ NotSupportedError
All exception classes are also accessible as attributes of the Connection object (e.g. conn.IntegrityError).

Build docs developers (and LLMs) love

Get started for freeTalk to us