synology_apm_repo.sdk.storage.sqlite module

Opening a SQLite database inside an ObjectStore, for every backend.

  • Fast path (LocalFsStore only, the one place the SDK maps store paths onto real files): with no non-empty -wal sidecar, open the file read-only through an immutable file: URI.

  • Slow path (every other store, a non-empty -wal, or a transform): copy the file and any -wal/-shm sidecars into a temp directory and open that copy read-write, so SQLite replays the WAL without touching the store. A non-empty -shm alone doesn’t trigger it.

apply_index_hint lives here because only the slow path’s private copy can be given an index.

table_columns and apply_index_hint ask each open connection only once per table (per hint): an open database’s tables keep their columns, and an applied hint only adds an index.

async synology_apm_repo.sdk.storage.sqlite.connect(uri)

aiosqlite.connect(uri, uri=True), closing the connection if it opens anyway after the caller failed or was cancelled mid-connect: its non-daemon thread would otherwise block interpreter exit.

async synology_apm_repo.sdk.storage.sqlite.open_sqlite(store, path, *, tmp_dir=None, transform=None, listing=None)

Open an aiosqlite connection to path within store, read-only on the fast path, read-write on the slow path’s private copy (see the module docstring).

Parameters:
  • store (ObjectStore) – The store holding path.

  • path (str) – Store-relative path of the SQLite file.

  • tmp_dir (Path | None) – Parent directory for the slow path’s temp directory (default: the system temp directory).

  • transform (Callable[[bytes, BinaryIO], None] | None) – Applied independently to each file’s raw bytes (main file and any -wal/-shm) before materializing, and forces the slow path. It receives the raw bytes and an open destination file and writes the result into it, so a decompressing transform never holds its whole output in memory. It reserves its own disk space (disk_space); an untransformed copy is reserved here.

  • listing (Mapping[str, int | None] | None) – path’s directory as already listed (entry name -> the size the listing reported, or None), answering for the -wal/-shm sidecars with no request; without it each is probed with exists.

Returns:

(connection, materialized_tmp_dir). materialized_tmp_dir is None on the fast path; on the slow path it is the TemporaryDirectory backing the copy, which the caller must keep referenced while connection is used and then .cleanup().

Raises:
Return type:

tuple[Connection, TemporaryDirectory[str] | None]

async synology_apm_repo.sdk.storage.sqlite.table_columns(conn, table)

table’s column names (empty when it doesn’t exist), from PRAGMA table_info once per connection.

async synology_apm_repo.sdk.storage.sqlite.apply_index_hint(conn, table, columns)

Declare that queries on table will filter or sort by columns; a hint, not a guarantee. Skips if an existing index already covers columns as a leading prefix, otherwise tries CREATE INDEX IF NOT EXISTS. A read-only connection’s “readonly database” error is swallowed (the hint does nothing); any other error propagates, and the hint is tried again on the next call.