Skip to main content

Installation Guide

This guide covers installing dqlitepy and its requirements.

Prerequisites​

  • Python 3.8 or higher
  • Linux x86_64 system (pre-built wheels available)
  • For building from source: Go 1.20+, GCC, build tools

The easiest way to install dqlitepy is using the pre-built wheel:

pip install dqlitepy-0.2.0-py3-none-linux_x86_64.whl

The wheel includes:

  • Compiled Go shim library
  • dqlite and raft native libraries
  • All Python dependencies

Note: Wheels are platform-specific. Make sure to download the correct wheel for your system.

Using with uv​

If you're using uv for package management:

uv pip install dqlitepy-0.2.0-py3-none-linux_x86_64.whl

Building from Source​

Prerequisites for Building​

# Ubuntu/Debian
sudo apt-get install -y \
    build-essential \
    pkg-config \
    autoconf \
    automake \
    libtool \
    libuv1-dev \
    libsqlite3-dev \
    golang-1.20

# macOS
brew install autoconf automake libtool pkg-config libuv sqlite go

Build Steps​

  1. Clone the repository:
git clone https://github.com/vantagecompute/dqlitepy
cd dqlitepy
  1. Build the wheel using Docker (easiest):
bash scripts/build_wheel_docker.sh

This will create a wheel file in the dist/ directory.

  1. Install the wheel:
pip install dist/dqlitepy-*.whl

Manual Build (Advanced)​

If you prefer to build without Docker:

  1. Build the vendor libraries:
bash scripts/build_vendor_libs.sh
  1. Build the Python wheel:
pip install build
python -m build
  1. Install:
pip install dist/dqlitepy-*.whl

Verify Installation​

Test that dqlitepy is installed correctly:

import dqlitepy

# Check version
print(f"dqlitepy version: {dqlitepy.__version__}")

# Create a simple node
from dqlitepy import Node

node = Node("127.0.0.1:9001", "/tmp/dqlite-test")
try:
    node.start()
    node.open_db("test.db")
    node.exec("CREATE TABLE test (id INTEGER, value TEXT)")
    node.exec("INSERT INTO test VALUES (1, 'Hello dqlite!')")
    result = node.query("SELECT * FROM test")
    print(f"Query result: {result}")
finally:
    node.close()

Expected output:

dqlitepy version: 0.2.0
Query result: {'columns': ['id', 'value'], 'rows': [[1, 'Hello dqlite!']]}

Troubleshooting​

cffi Not Found​

If you get ModuleNotFoundError: No module named 'cffi':

pip install cffi

libdqlitepy.so Not Found​

If you get errors about missing libdqlitepy.so, ensure you're using the wheel built for your platform:

# Check your platform
python3 -c "import platform; print(platform.platform())"

# The wheel name should match your platform
# Example: dqlitepy-0.2.0-py3-none-linux_x86_64.whl

Permission Errors​

If you get permission errors when starting a node:

import os
os.makedirs("/tmp/dqlite-data", exist_ok=True, mode=0o755)
node = Node("127.0.0.1:9001", "/tmp/dqlite-data")

Next Steps​