elitesql (Python)

Python binding for EliteSQL.

pip install elitesql

Wheels for Linux x86_64/aarch64 (manylinux_2_28) and macOS arm64 ship the engine (libelitesql) inside the package; Python 3.9 or newer. Until the first PyPI release, install the wheel attached to a GitHub Release.

  • EliteSQL(path): embedded in-process over the C ABI (libelitesql). ctypes releases the GIL on every foreign call, so threads truly parallelize. The library is loaded from the package itself; a source checkout also finds target/release, and ELITESQL_LIB=/path or EliteSQL(path, lib_path=...) point anywhere else.
  • SidecarClient(socket): client for the sidecar mode (elitesql serve <db> <socket>) for multi-worker deployments (gunicorn, uwsgi).
from elitesql import EliteSQL

with EliteSQL("app.esql") as db:
    db.query("CREATE TABLE notes (body text NOT NULL, emb vector(768))")
    db.create_text_index("notes", "body")
    db.create_vector_index("notes", "emb", quantized=True)
    db.query("INSERT INTO notes (body, emb) VALUES (%s, %s)", ["hello world", embedding])
    rows = db.query(
        "SELECT * FROM notes WHERE body = %(body)s LIMIT %(limit)s",
        {"body": "hello world", "limit": 10},
    )

    hits = db.search_hybrid("notes", text=("body", "hello"), vector=("emb", embedding))
    with db.snapshot() as snap:
        rows = snap.scan("notes")   # stable read while others write

query(sql, params=None) binds parameters without string interpolation. Sequences use ? or %s; mappings use %(name)s. Supported Python values include None, booleans, signed 64-bit integers, floats, strings, bytes, datetime/date/time, JSON dicts/lists and numeric lists for vector columns.

Building and releasing wheels

bash bindings/python/build_wheel.sh builds libelitesql with Cargo, copies it into the package and produces dist/elitesql-<version>-py3-none-<platform>.whl (pip install build wheel first). ELITESQL_LIB= reuses an existing library and ELITESQL_WHEEL_PLATFORM= names the platform tag; Linux wheels meant for distribution are built inside quay.io/pypa/manylinux_2_28_<arch> so they run on glibc 2.28 or newer.

The Wheels GitHub workflow does this for Linux x86_64, Linux aarch64 and macOS arm64 on every v* tag, smoke-tests each wheel from a clean virtualenv, attaches them to the GitHub Release, and uploads them to PyPI through trusted publishing when the repository variable PYPI_PUBLISH is true. One-time setup on PyPI: add a pending publisher for project elitesql with owner jalbarracinv, repository elitesql, workflow wheels.yml, environment pypi; then create the pypi environment in the repository settings and set the variable. The package version comes from pyproject.toml and should match the tag.

Error codes and retries

Every failure raises EliteSQLError with a stable code (also exposed as constants on the class). Two questions decide what to do next:

Code Constant Meaning Retry?
9 CONFLICT_RETRY Optimistic commit conflict; nothing was published Yes, the whole transaction (run_transaction does this)
21 TRANSACTION_EXPIRED Sidecar rolled the transaction back at its 30 s deadline Yes, the whole transaction
11 UNIQUE_VIOLATION Constraint refused the write No: fix the data
17 COMMIT_UNKNOWN The write is published and visible. Only its durability across a power loss is unknown (a sync failed). Further writes are fenced until the database is reopened Never blindly. Read back, then decide
1 IO I/O error. Over the sidecar this is also a lost connection or timeout: a commit or autocommit statement that was already sent may have been executed Never blindly. Reconnect, read back, then decide
2 CORRUPT On-disk validation failed; see elitesql check and elitesql repair No
10 DATABASE_LOCKED Another process holds the directory Later
13 READ_ONLY Handle opened read-only No
16 MEMORY_LIMIT Operation exceeds its memory pool; split it With smaller work
20 AUTH Sidecar token missing or wrong No

error.retry_safe is True for 9 and 21; error.maybe_published is True for 17 and 1. A catch-all except EliteSQLError: retry duplicates rows on 17 and 1: make inserts idempotent (explicit id or a unique key) if you retry those.

Sidecar timeouts

SidecarClient(..., timeout=seconds) bounds every request. When a request times out the client closes the connection and raises code 1: the late response cannot be matched to a later request (every request carries an id the server echoes, and a mismatch also closes the connection). Create a new client to continue; an in-progress transaction on the old connection is rolled back by the server when it notices the disconnect.

Durability notes

  • EliteSQL(path, durability="balanced"|"fast") acknowledges commits before they reach the disk. A clean close() syncs everything acknowledged; an OS crash before that may lose recent commits, never corrupt the database.
  • On macOS fsync does not flush the drive's cache. Pass full_fsync=True in the options (see EliteSQL.__init__) for safe to survive a power loss there; it is much slower. Linux needs nothing.

Project links

Data verified by PyPI on Sep 12, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for jalbarracin from gravatar.com jalbarracin

GitHub Statistics

Data verified by PyPI on Sep 12, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT OR Apache-2.0
View SPDX License List

Requires

Python >=3.9

Tags

database embedded vector-search full-text sqlite-alternative

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

elitesql-0.0.1-py3-none-manylinux_2_28_x86_64.whl (1.8 MB view details)

Uploaded Python 3manylinux: glibc 2.28+ x86-64

elitesql-0.0.1-py3-none-manylinux_2_28_aarch64.whl (1.7 MB view details)

Uploaded Python 3manylinux: glibc 2.28+ ARM64

elitesql-0.0.1-py3-none-macosx_11_0_arm64.whl (1.6 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

File details

Details for the file elitesql-0.0.1-py3-none-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for elitesql-0.0.1-py3-none-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 701d9d628b86e6b14d825d0284717eeb7e7de48ca6da350bd21f0e70e3fdb4ab
MD5 3237b28244c4f23210491521dc2df19b
BLAKE2b-256 0bcf030a399d1f5548f695f525476c3d26847bb14fcbb318036a051ef63ac4f6

See more details on using hashes here.

Provenance

The following attestation bundles were made for elitesql-0.0.1-py3-none-manylinux_2_28_x86_64.whl:

Publisher: wheels.yml on jalbarracinv/elitesql

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file elitesql-0.0.1-py3-none-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for elitesql-0.0.1-py3-none-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 6c274591cb6e9a5700228af9a0865e3f80fe5e6c9b352d2a0675e4de91410d4a
MD5 8766b4f7524c2e948adbba87be5bf1e9
BLAKE2b-256 c9712e64a70df14f4585b8801f85a4e20858dc247597deae82492a94a85669a1

See more details on using hashes here.

Provenance

The following attestation bundles were made for elitesql-0.0.1-py3-none-manylinux_2_28_aarch64.whl:

Publisher: wheels.yml on jalbarracinv/elitesql

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file elitesql-0.0.1-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for elitesql-0.0.1-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 68abee4b6947d9c2b6f9e0388babff9649aea26c68b716e16b17b8255963f26c
MD5 03f972b86cf551e1cb922e43c6bd3894
BLAKE2b-256 4a09fd8d39502bc6b16c8b35a85b087d458f2ee246dbb1e2f77ccf836c5a51c5

See more details on using hashes here.

Provenance

The following attestation bundles were made for elitesql-0.0.1-py3-none-macosx_11_0_arm64.whl:

Publisher: wheels.yml on jalbarracinv/elitesql

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.0.1 This release

3 files

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