GitHub

SqliteConnection

API reference for SqliteConnection.

Runs statements on one sqlite3 connection, on its worker thread.

sqlite3 keeps a cache of prepared statements (cached_statements) and has no other way to run one, so the prepared and unprepared calls run alike.

Functions

__init__

__init__(db, worker) -> None
ParameterTypeDescription
dbsqlite3.Connection
workerWorker
def __init__(self, db: sqlite3.Connection, worker: Worker) -> None:
    self._db = db
    self._worker = worker

is_transaction

is_transaction() -> bool

Returns bool

def is_transaction(self) -> bool:
    return self._db.in_transaction

execute

execute(sql, params, transform_rows) -> Effect[Sequence[Row], SqlError]
ParameterTypeDescription
sqlstr
paramsSequence[object]
transform_rowsTransformRows | None

Returns Effect[Sequence[Row], SqlError]

def execute(
    self, sql: str, params: Sequence[object], transform_rows: TransformRows | None, /
) -> Effect[Sequence[Row], SqlError]:
    rows = self._execute(sql, params)
    return rows if transform_rows is None else rows.map(transform_rows)

execute_unprepared

execute_unprepared(sql, params, transform_rows) -> Effect[Sequence[Row], SqlError]
ParameterTypeDescription
sqlstr
paramsSequence[object]
transform_rowsTransformRows | None

Returns Effect[Sequence[Row], SqlError]

def execute_unprepared(
    self, sql: str, params: Sequence[object], transform_rows: TransformRows | None, /
) -> Effect[Sequence[Row], SqlError]:
    return self.execute(sql, params, transform_rows)

execute_raw

execute_raw(sql, params) -> Effect[object, SqlError]

Rows, or a RunResult for a statement without result columns.

ParameterTypeDescription
sqlstr
paramsSequence[object]

Returns Effect[object, SqlError]

def execute_raw(self, sql: str, params: Sequence[object], /) -> Effect[object, SqlError]:
    """Rows, or a ``RunResult`` for a statement without result
    columns."""
    values = tuple(params)

    def run(db: sqlite3.Connection) -> object:
        cursor = db.execute(sql, values)
        if cursor.description is None:
            return _changes(db)
        return _rows(cursor)

    return self._call(run)

execute_values

execute_values(sql, params) -> Effect[Sequence[ValueRow], SqlError]
ParameterTypeDescription
sqlstr
paramsSequence[object]

Returns Effect[Sequence[ValueRow], SqlError]

def execute_values(
    self, sql: str, params: Sequence[object], /
) -> Effect[Sequence[ValueRow], SqlError]:
    values = tuple(params)

    def run(db: sqlite3.Connection) -> list[ValueRow]:
        cursor = db.execute(sql, values)
        if cursor.description is None:
            return []
        return [tuple(row) for row in cursor.fetchall()]

    return self._call(run)

execute_values_unprepared

execute_values_unprepared(sql, params) -> Effect[Sequence[ValueRow], SqlError]
ParameterTypeDescription
sqlstr
paramsSequence[object]

Returns Effect[Sequence[ValueRow], SqlError]

def execute_values_unprepared(
    self, sql: str, params: Sequence[object], /
) -> Effect[Sequence[ValueRow], SqlError]:
    return self.execute_values(sql, params)

execute_stream

execute_stream(sql, params, transform_rows) -> Stream[Row, SqlError]
ParameterTypeDescription
sqlstr
paramsSequence[object]
transform_rowsTransformRows | None

Returns Stream[Row, SqlError]

def execute_stream(
    self, sql: str, params: Sequence[object], transform_rows: TransformRows | None, /
) -> Stream[Row, SqlError]:
    from pyfect import stream

    return stream.die(NotImplementedError("executeStream not implemented"))

backup

backup(destination) -> Effect[BackupMetadata, SqlError]

Copy the database to the file destination.

ParameterTypeDescription
destinationstr

Returns Effect[BackupMetadata, SqlError]

def backup(self, destination: str) -> Effect[BackupMetadata, SqlError]:
    """Copy the database to the file ``destination``."""

    def run(db: sqlite3.Connection) -> BackupMetadata:
        pages = [0]

        def progress(_status: int, _remaining: int, total: int) -> None:
            pages[0] = total

        target = sqlite3.connect(destination)
        try:
            db.backup(target, progress=progress)
        finally:
            target.close()
        return BackupMetadata(pages[0], 0)

    return self._call(run, _catch("Failed to backup database", "backup"))

load_extension

load_extension(path) -> Effect[None, SqlError]

Load the SQLite extension at path (fails where Python's sqlite3 was built without extension loading).

ParameterTypeDescription
pathstr

Returns Effect[None, SqlError]

def load_extension(self, path: str) -> Effect[None, SqlError]:
    """Load the SQLite extension at ``path`` (fails where Python's
    ``sqlite3`` was built without extension loading)."""

    def run(db: sqlite3.Connection) -> None:
        enable: Any = getattr(db, "enable_load_extension", None)
        if enable is None:
            raise sqlite3.NotSupportedError("extension loading is not supported")
        enable(True)
        try:
            db.load_extension(path)
        finally:
            enable(False)

    return self._call(run, _catch("Failed to load extension", "loadExtension"))

exec_config

exec_config(sql) -> Effect[None, SqlError]

Run a configuration statement, failing as a connect error.

ParameterTypeDescription
sqlstr

Returns Effect[None, SqlError]

def exec_config(self, sql: str) -> Effect[None, SqlError]:
    """Run a configuration statement, failing as a connect error."""

    def run(db: sqlite3.Connection) -> None:
        db.execute(sql).fetchall()

    return self._call(run, _catch("Failed to configure database", "connect"))

close

close() -> Effect[None]

Returns Effect[None]

def close(self) -> Effect[None]:
    worker = self._worker

    def run(db: sqlite3.Connection) -> None:
        db.close()

    def stop(_: object) -> Effect[None]:
        worker.shutdown()
        return _Succeed(None)

    return self._call(run).or_die().flat_map(stop)