Skip to main content

tortoise-sqlcipher

Build Status Maintenance PyPI version PyPI downloads Python versions

tortoise-sqlcipher provides a Tortoise ORM-specific SQLite backend using SQLCipher and aiosqlite for encrypted local databases.

Configuration

Configure Tortoise with the tortoise_sqlcipher.sqlite_sqlcipher engine and a 32-byte encryption key:

{
    "connections": {
        "default": {
            "engine": "tortoise_sqlcipher.sqlite_sqlcipher",
            "credentials": {
                "file_path": "encrypted.sqlite3",
                "encryption_key": encryption_key,
            },
        }
    }
}

The engine validates that the supplied key is exactly 32 bytes and never falls back to plaintext SQLite. Applications remain responsible for generating and storing their encryption keys.

Key rotation

Rotate an existing database through the configured client with a replacement 32-byte bytes key:

client = Tortoise.get_connection("default")
await client.rotate_key(replacement_key)

rotate_key returns only after it has reopened the database with the replacement key. Persist the replacement in external key storage only after that normal return.

If a caller cancels rotation after the native operation has begun, asyncio.CancelledError is re-raised only after the client has reconciled its connection. Its non-secret note says whether the replacement or former key was retained. In that case, re-read database state before changing external key storage or issuing further application work.

Key rotation requires a persistent file-backed database; in-memory databases, including SQLite memory URIs, and temporary databases are unsupported. If it raises OperationalError, do not discard either key until a fresh client verifies database access.

Applications can check the current database before scheduling maintenance:

if await client.is_mem_db():
    # Key rotation requires a persistent database.
    ...

Snapshots

Create an encrypted, self-contained snapshot at a persistent filesystem path, then restore it through the configured client:

await client.backup("encrypted.snapshot.sqlite")
await client.restore("encrypted.snapshot.sqlite")

Snapshots use SQLCipher's native copy operation. Backing up an in-memory database is supported; restoring into one replaces its live contents without closing the client connection.

SQLCipher pragmas

Additional connection credentials are applied as SQLCipher pragmas after the key is set. This permits necessary SQLCipher tuning, but it is also a foot-gun: key-management pragmas such as key, rekey, and hexkey, plus cipher_* settings, can alter the database's encryption configuration. Only supply extra pragmas when your application deliberately owns that configuration.

Supported Python versions

Requires Python 3.11+.

Metadata

Release files for tortoise-sqlcipher 0.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tortoise-sqlcipher 0.5.0
File Size Uploaded Provenance Actions
tortoise_sqlcipher-0.5.0.tar.gz 9.0 kB With provenance Details for tortoise_sqlcipher-0.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tortoise-sqlcipher 0.5.0
File Interpreter ABI Platform Actions
tortoise_sqlcipher-0.5.0-py3-none-any.whl Python 3 none any Details for tortoise_sqlcipher-0.5.0-py3-none-any.whl

Total release size: 19.1 kB

Release files / tortoise_sqlcipher-0.5.0.tar.gz

Download URL tortoise_sqlcipher-0.5.0.tar.gz
Size 9.0 kB
Tags Source
SHA-256 checksum
How to use checksums
8fffb6db29024e3b9d5152e7f03a7c1f359fd190680dc343c446f4df1f51c1e2
BLAKE2b-256 checksum
How to use checksums
7a410e3ca3d5b402dc6d68e5b54d45c1b2cf5c8964e8c5e0701a38d57cf82447
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 9, 2026.

Transparency log

Release files / tortoise_sqlcipher-0.5.0-py3-none-any.whl

Download URL tortoise_sqlcipher-0.5.0-py3-none-any.whl
Size 10.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0a6cdb3bd20f57c113209d7798b213b4343da5777855fa2b7ca39b98bf7fb1d4
BLAKE2b-256 checksum
How to use checksums
ef32ada52273cd7ed618ab414b51f2862188be2c495d7ca7ed6776e9a7bbb38b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 9, 2026.

Transparency log

Security for tortoise-sqlcipher 0.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for tortoise_sqlcipher-0.5.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 9, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.5.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page