hubvault.repo.sqlite

SQLite truth-store helpers for hubvault.repo.

This module centralizes the conservative stdlib-sqlite3 repository metadata store used by Phase 15. The database keeps repo metadata, refs, reflog, transaction journals, visible chunk locations, and object metadata inside one repo-local file while blob/pack payload bytes remain in the filesystem.

The module contains:

SQLiteMetadataStore - Repo-local SQLite metadata/object store

Example:

>>> from pathlib import Path
>>> import tempfile
>>> with tempfile.TemporaryDirectory() as tmpdir:
...     store = SQLiteMetadataStore(Path(tmpdir))
...     store.initialize_empty()
...     conn = store.open_connection()
...     store.set_repo_meta(conn, {"default_branch": "main"})
...     store.get_repo_meta(conn)["default_branch"]
'main'

SQLITE_METADATA_FILENAME

hubvault.repo.sqlite.SQLITE_METADATA_FILENAME = 'metadata.sqlite3'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

SQLITE_SCHEMA_VERSION

hubvault.repo.sqlite.SQLITE_SCHEMA_VERSION = 1

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4

REQUIRED_REPO_META_KEYS

hubvault.repo.sqlite.REQUIRED_REPO_META_KEYS = ('format_version', 'default_branch', 'object_hash', 'file_mode', 'large_file_threshold', 'metadata')

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

SQLiteMetadataStore

class hubvault.repo.sqlite.SQLiteMetadataStore(repo_path: str | Path)[source]

Manage the repo-local SQLite metadata and object truth-store.

Parameters:: repo_path (Union[str, pathlib.Path]) – Repository root path

__init__(repo_path: str | Path) → None[source]

Initialize the metadata store wrapper.

Parameters:: repo_path (Union[str, pathlib.Path]) – Repository root path
Returns:: None.
Return type:: None

append_reflog(connection: Connection, ref_kind: str, ref_name: str, timestamp: str, old_head: str | None, new_head: str | None, message: str, checksum: str) → None[source]

Append one reflog record.

Parameters:

connection (sqlite3.Connection) – Open SQLite connection
ref_kind (str) – "branch" or "tag"
ref_name (str) – Normalized ref name
timestamp (str) – UTC timestamp string
old_head (Optional[str]) – Previous head
new_head (Optional[str]) – New head
message (str) – Reflog message
checksum (str) – Reflog checksum

Returns:

None.

Return type:

None

clear_truth_tables(connection: Connection) → None[source]

Remove all persisted truth rows while preserving the schema.

Parameters:: connection (sqlite3.Connection) – Open SQLite connection
Returns:: None.
Return type:: None

property db_path: Path

Return the metadata database path.

Returns:: Absolute SQLite database path
Return type:: pathlib.Path

delete_chunk_entries(connection: Connection, chunk_ids: Iterable[str]) → None[source]

Delete selected chunk-visible entries.

Parameters:

connection (sqlite3.Connection) – Open SQLite connection
chunk_ids (Iterable[str]) – Chunk identifiers to remove

Returns:

None.

Return type:

None

delete_object(connection: Connection, object_type: str, object_id: str) → None[source]

Delete one object payload row.

Parameters:

connection (sqlite3.Connection) – Open SQLite connection
object_type (str) – Object collection name
object_id (str) – Object identifier

Returns:

None.

Return type:

None

delete_ref(connection: Connection, ref_kind: str, ref_name: str) → None[source]

Delete one persisted ref.

Parameters:

connection (sqlite3.Connection) – Open SQLite connection
ref_kind (str) – "branch" or "tag"
ref_name (str) – Normalized ref name

Returns:

None.

Return type:

None

delete_tx_log(connection: Connection, txid: str) → None[source]

Delete one transaction-journal row.

Parameters:

connection (sqlite3.Connection) – Open SQLite connection
txid (str) – Transaction identifier

Returns:

None.

Return type:

None

ensure_schema(connection: Connection) → None[source]

Ensure the metadata schema exists and matches the expected version.

Parameters:: connection (sqlite3.Connection) – Open SQLite connection
Returns:: None.
Return type:: None
Raises:: IntegrityError – Raised when the on-disk schema version is not supported.

exists() → bool[source]

Return whether the SQLite metadata database already exists.

Returns:: Whether the database file exists
Return type:: bool

get_chunk_entry(connection: Connection, chunk_id: str) → IndexEntry | None[source]

Load one visible chunk entry.

Parameters:

connection (sqlite3.Connection) – Open SQLite connection
chunk_id (str) – Chunk identifier

Returns:

Visible chunk entry, or None

Return type:

Optional[IndexEntry]

get_object_payload(connection: Connection, object_type: str, object_id: str) → Dict[str, object][source]

Load one stored object payload.

Parameters:

connection (sqlite3.Connection) – Open SQLite connection
object_type (str) – Object collection name
object_id (str) – Object identifier

Returns:

Logical object payload

Return type:

Dict[str, object]

Raises:

RevisionNotFoundError – Raised when the object is absent.

get_ref(connection: Connection, ref_kind: str, ref_name: str) → str | None[source]

Load one ref target.

Parameters:

connection (sqlite3.Connection) – Open SQLite connection
ref_kind (str) – "branch" or "tag"
ref_name (str) – Normalized ref name

Returns:

Commit object ID or None

Return type:

Optional[str]

Raises:

RevisionNotFoundError – Raised when the ref does not exist.

get_repo_meta(connection: Connection) → Dict[str, object][source]

Load the full repository metadata mapping.

Parameters:: connection (sqlite3.Connection) – Open SQLite connection
Returns:: Repository metadata mapping
Return type:: Dict[str, object]

get_tx_log(connection: Connection, txid: str) → Dict[str, object] | None[source]

Load one transaction-journal row.

Parameters:

connection (sqlite3.Connection) – Open SQLite connection
txid (str) – Transaction identifier

Returns:

Transaction payload mapping, or None

Return type:

Optional[Dict[str, object]]

has_required_repo_meta(connection: Connection) → bool[source]

Return whether the repo metadata store is fully bootstrapped.

Parameters:: connection (sqlite3.Connection) – Open SQLite connection
Returns:: Whether all required repo metadata keys are present
Return type:: bool

initialize_empty() → None[source]

Create the metadata database and schema if missing.

Returns:: None.
Return type:: None

last_reflog_entry(connection: Connection, ref_kind: str, ref_name: str) → Dict[str, object] | None[source]

Return the newest reflog entry for one ref.

Parameters:

connection (sqlite3.Connection) – Open SQLite connection
ref_kind (str) – "branch" or "tag"
ref_name (str) – Normalized ref name

Returns:

Reflog entry mapping, or None

Return type:

Optional[Dict[str, object]]

list_chunk_entries(connection: Connection) → List[IndexEntry][source]

List all visible chunk entries.

Parameters:: connection (sqlite3.Connection) – Open SQLite connection
Returns:: Visible chunk entries ordered by chunk ID
Return type:: List[IndexEntry]

list_object_ids(connection: Connection, object_type: str) → List[str][source]

List all persisted object identifiers for one logical type.

Parameters:

connection (sqlite3.Connection) – Open SQLite connection
object_type (str) – Object collection name

Returns:

Object identifiers ordered lexicographically

Return type:

List[str]

list_reflog(connection: Connection, ref_kind: str, ref_name: str, limit: int | None = None) → List[Dict[str, object]][source]

List reflog records for one ref ordered from newest to oldest.

Parameters:

connection (sqlite3.Connection) – Open SQLite connection
ref_kind (str) – "branch" or "tag"
ref_name (str) – Normalized ref name
limit (Optional[int], optional) – Optional maximum result count

Returns:

Reflog entry mappings

Return type:

List[Dict[str, object]]

list_refs(connection: Connection, ref_kind: str | None = None) → List[Tuple[str, str, str | None]][source]

List refs stored in the metadata database.

Parameters:

connection (sqlite3.Connection) – Open SQLite connection
ref_kind (Optional[str], optional) – Optional ref-kind filter

Returns:

(ref_kind, ref_name, commit_id) tuples

Return type:

List[Tuple[str, str, Optional[str]]]

list_tx_logs(connection: Connection) → List[Dict[str, object]][source]

List all persisted transaction-journal rows.

Parameters:: connection (sqlite3.Connection) – Open SQLite connection
Returns:: Transaction payload mappings ordered by txid
Return type:: List[Dict[str, object]]

object_exists(connection: Connection, object_type: str, object_id: str) → bool[source]

Return whether one object payload row exists.

Parameters:

connection (sqlite3.Connection) – Open SQLite connection
object_type (str) – Object collection name
object_id (str) – Object identifier

Returns:

Whether the object exists

Return type:

bool

open_connection(readonly: bool = False) → Connection[source]

Open one SQLite connection configured for the repository baseline.

Parameters:: readonly (bool, optional) – Whether to open the database in read-only mode
Returns:: Configured SQLite connection
Return type:: sqlite3.Connection

replace_tx_log(connection: Connection, payload: Dict[str, object]) → None[source]

Insert or replace one transaction-journal row.

Parameters:

connection (sqlite3.Connection) – Open SQLite connection
payload (Dict[str, object]) – Journal payload mapping

Returns:

None.

Return type:

None

set_chunk_entries(connection: Connection, entries: Sequence[IndexEntry]) → None[source]

Replace the full visible chunk-entry set.

Parameters:

connection (sqlite3.Connection) – Open SQLite connection
entries (Sequence[IndexEntry]) – Visible chunk entries to persist

Returns:

None.

Return type:

None

set_object_payload(connection: Connection, object_type: str, object_id: str, payload: object) → None[source]

Upsert one object payload row.

Parameters:

connection (sqlite3.Connection) – Open SQLite connection
object_type (str) – Object collection name
object_id (str) – Object identifier
payload (object) – Logical object payload

Returns:

None.

Return type:

None

set_ref(connection: Connection, ref_kind: str, ref_name: str, commit_id: str | None, updated_at: str) → None[source]

Upsert one ref target.

Parameters:

connection (sqlite3.Connection) – Open SQLite connection
ref_kind (str) – "branch" or "tag"
ref_name (str) – Normalized ref name
commit_id (Optional[str]) – New target commit ID or None
updated_at (str) – UTC timestamp string

Returns:

None.

Return type:

None

set_repo_meta(connection: Connection, values: Dict[str, object]) → None[source]

Replace selected repository metadata keys.

Parameters:

connection (sqlite3.Connection) – Open SQLite connection
values (Dict[str, object]) – Key/value mapping to persist

Returns:

None.

Return type:

None

truncate_reflog(connection: Connection, ref_kind: str, ref_name: str, keep_through_seq: int) → None[source]

Remove reflog rows newer than one retained sequence number.

Parameters:

connection (sqlite3.Connection) – Open SQLite connection
ref_kind (str) – "branch" or "tag"
ref_name (str) – Normalized ref name
keep_through_seq (int) – Highest sequence number to keep, or 0 to delete the whole reflog

Returns:

None.

Return type:

None