Python: Database and documents

#sovaria.add_column

Add a column to an existing table.

await sovaria.add_column(
    table_name: str,
    column_name: str,
    data_type: str,
    *, is_nullable: bool = True,
    is_unique: bool = False,
    default_value: str | int | float | bool | None = None,
) -> dict[str, Any]

Returns

dict[str, Any]

#sovaria.add_foreign_key

Add a foreign-key relation.

await sovaria.add_foreign_key(
    table_name: str,
    column_name: str,
    referenced_table: str,
    referenced_column: str,
) -> dict[str, Any]

Returns

dict[str, Any]

#sovaria.begin_transaction

Start a table transaction and receive tx/snapshot IDs.

await sovaria.begin_transaction() -> dict[str, Any]

Returns

dict[str, Any]

#sovaria.commit_transaction

Commit a previously opened table transaction.

await sovaria.commit_transaction(txid: int) -> dict[str, Any]

Returns

dict[str, Any]

#sovaria.create_table

Create a relational table.

await sovaria.create_table(
    table_name: str,
    columns: list[dict[str, Any]],
    foreign_keys: list[dict[str, Any]] | None = None,
) -> dict[str, Any]

Returns

dict[str, Any]

#sovaria.delete_plain_document

Delete a document from Atlas-Doc.

await sovaria.delete_plain_document(
    collection_id: str,
    document_id: str,
) -> None

Returns

None

#sovaria.drop_column

Drop a column from a table.

await sovaria.drop_column(
    table_name: str,
    column_name: str,
) -> dict[str, Any]

Returns

dict[str, Any]

#sovaria.drop_foreign_key

Drop a foreign-key relation.

await sovaria.drop_foreign_key(
    table_name: str,
    column_name: str,
    referenced_table: str,
    referenced_column: str,
) -> dict[str, Any]

Returns

dict[str, Any]

#sovaria.drop_table

Drop a relational table.

await sovaria.drop_table(table_name: str) -> dict[str, Any]

Returns

dict[str, Any]

#sovaria.get_document

Retrieve and decrypt a document from Atlas-Doc. The gateway returns the stored ciphertext envelope.

await sovaria.get_document(
    collection_id: str,
    document_id: str,
    password: str | None = None,
    at_txid: int = 0,
    txid: int | None = None,
) -> DocumentGetResponse

Decryption happens entirely in-process here; plaintext never touches the wire.

Args: collection_id: Logical bucket name. document_id: Primary key. password: Required only when the session has no cached KEK. at_txid: Chrono time-travel: return document as it was at this TXID. 0 = HEAD (latest version). txid: Deprecated alias for at_txid.

Returns: DocumentGetResponse with the decrypted plaintext bytes.

Returns

DocumentGetResponse

#sovaria.get_plain_document

Read a plain JSON document from Atlas-Doc. Snapshot reads use the at_txid query key.

await sovaria.get_plain_document(
    collection_id: str,
    document_id: str,
    *, txid: int | None = None,
    at_txid: int | None = None,
) -> dict[str, Any]

txid is accepted as a deprecated alias.

Returns

dict[str, Any]

#sovaria.list_migrations

List Atlas-Rel migration history.

await sovaria.list_migrations(
    *, table_name: str | None = None,
    limit: int = 100,
    offset: int = 0,
) -> dict[str, Any]

Returns

dict[str, Any]

#sovaria.put_document

Encrypt a document client-side and write it to Atlas-Doc. The plaintext NEVER leaves this device in readable form.

await sovaria.put_document(
    collection_id: str,
    document_id: str,
    plaintext: bytes,
    password: str | None = None,
) -> DocumentResponse

The gateway receives only the AES-GCM ciphertext envelope + the X-Payload-Hash integrity proof. Atlas stores the envelope verbatim (Zero-Knowledge).

Phase 2 Sprint 1 / Part 8 §1.3: - Uses the cached Argon2id KEK from login() if available. - password is required only if login() was pre-Phase-2 (no salt returned). Pass it explicitly in that case and it will be used to derive a fresh KEK (and discarded immediately).

Args: collection_id: Logical bucket name (e.g. "medical_records"). document_id: Primary key for this document. plaintext: Raw document bytes to encrypt. password: Only needed when the session has no cached KEK.

Returns: DocumentResponse with the TXID assigned by Atlas WAL.

Returns

DocumentResponse

#sovaria.put_plain_document

Write a plain JSON document to Atlas-Doc.

await sovaria.put_plain_document(
    collection_id: str,
    document_id: str,
    data: dict[str, Any],
) -> dict[str, Any]

Returns

dict[str, Any]

#sovaria.rollback_transaction

Rollback transaction.

await sovaria.rollback_transaction(txid: int) -> dict[str, Any]

Returns

dict[str, Any]

#sovaria.scan_documents

Run a key-prefix/range scan in Atlas-Doc.

await sovaria.scan_documents(
    *, prefix: str | None = None,
    start_key: str | None = None,
    end_key: str | None = None,
    limit: int = 100,
) -> dict[str, Any]

Returns

dict[str, Any]

#sovaria.sql_query

Execute a SQL query via Atlas-Rel. Parameters: sql: SQL statement to execute.

await sovaria.sql_query(
    sql: str,
    txid: int = 0,
    params: list[Any] | None = None,
) -> dict[str, Any]

Use $1, $2, … for values. params: Values for the placeholders, bound by the database (never spliced into SQL). txid: Optional explicit transaction ID for snapshot isolation. If 0 (default), uses the latest snapshot. If > 0, uses snapshot isolation at that TXID. Atlas-Rel requires txid >= 1 if provided explicitly.

Returns

dict[str, Any] — columns, rows and row_count.

result = await sovaria.sql_query("insert into notes (body) values ($1) returning id", params=["Buy milk"])
note_id = result["rows"][0][0]