synology_apm_repo.sdk.storage.sqlite module¶
Opening a SQLite database inside an ObjectStore, for every backend.
Fast path (
LocalFsStoreonly, the one place the SDK maps store paths onto real files): with no non-empty-walsidecar, open the file read-only through an immutablefile:URI.Slow path (every other store, a non-empty
-wal, or atransform): copy the file and any-wal/-shmsidecars into a temp directory and open that copy read-write, so SQLite replays the WAL without touching the store. A non-empty-shmalone 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
aiosqliteconnection topathwithinstore, 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, orNone), answering for the-wal/-shmsidecars with no request; without it each is probed withexists.
- Returns:
(connection, materialized_tmp_dir).materialized_tmp_dirisNoneon the fast path; on the slow path it is theTemporaryDirectorybacking the copy, which the caller must keep referenced whileconnectionis used and then.cleanup().- Raises:
NotFoundError –
pathdoes not exist, on either path.ResourceLimitExceededError – A file of the slow path’s copy doesn’t fit in
tmp_dirwithdisk_space’s reserve left free.
- 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), fromPRAGMA table_infoonce per connection.
- async synology_apm_repo.sdk.storage.sqlite.apply_index_hint(conn, table, columns)¶
Declare that queries on
tablewill filter or sort bycolumns; a hint, not a guarantee. Skips if an existing index already coverscolumnsas a leading prefix, otherwise triesCREATE 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.