Skip to main content

Examples Overview

This section provides practical examples demonstrating various features and use cases of dqlitepy. Each example is a complete, runnable project with its own dependencies and setup instructions.

Available Examples​

1. Simple Node Example​

Learn the basics by creating and managing a single dqlite node with basic SQL operations.

What You'll Learn:

  • Node initialization and configuration
  • Starting and stopping nodes
  • Basic SQL operations (CREATE, INSERT, SELECT)
  • Graceful shutdown procedures

View Example →

2. Multi-Node Cluster Example​

Set up a distributed dqlite cluster with multiple nodes for high availability.

What You'll Learn:

  • Multi-node cluster configuration
  • Node coordination and communication
  • Cluster status monitoring
  • Distributed consensus basics

View Example →

3. Cluster with Client API Example​

Use the Client API to dynamically manage cluster membership from outside the cluster.

What You'll Learn:

  • Client API usage and patterns
  • Dynamic node addition and removal
  • Leader election monitoring
  • Cluster management best practices

View Example →

4. SQLAlchemy ORM Example​

Integrate dqlitepy with SQLAlchemy ORM for distributed database operations with Python objects.

What You'll Learn:

  • SQLAlchemy dialect configuration
  • ORM model definitions
  • CRUD operations via SQLAlchemy
  • Relationship handling
  • Automatic replication with ORM

View Example →

5. FastAPI Integration Example​

This comprehensive example demonstrates how to build a production-ready REST API using FastAPI with dqlitepy and SQLAlchemy. It includes cluster management, Docker support, and a complete CLI for database operations.

What You'll Learn:

  • Building REST APIs with FastAPI and dqlitepy

View Example →

Quick Start​

All examples are located in the examples/ directory of the repository and follow a consistent structure:

# Clone the repository
git clone https://github.com/vantagecompute/dqlitepy.git
cd dqlitepy/examples

# Run any example with its quickstart script
cd example_name
bash quickstart.sh

General Prerequisites​

  • Python 3.12 or higher
  • uv package manager installed

Installing uv​

curl -LsSf https://astral.sh/uv/install.sh | sh

Example Structure​

Each example follows this structure:

example_name/
├── README.md              # Detailed documentation
├── pyproject.toml         # Dependencies and metadata
├── quickstart.sh          # One-command setup script
└── example_package/       # Python package
    ├── __init__.py
    └── main.py           # Entry point

Running Examples​

Use the provided quickstart script:

cd example_name
bash quickstart.sh

The script will automatically:

  1. Install dqlitepy from the repository
  2. Install example-specific dependencies
  3. Run the example

Method 2: Manual Installation​

Install and run manually:

cd example_name
uv pip install -e .
example-name-script  # Uses the installed entry point

Method 3: Direct Execution​

Run directly without installation:

cd example_name
uv run python -m example_package.main

Learning Path​

We recommend exploring the examples in this order:

  1. Simple Node - Foundation concepts
  2. Multi-Node Cluster - Distributed system basics
  3. Cluster with Client - Advanced cluster management
  4. SQLAlchemy ORM - ORM integration patterns
  5. FastAPI Integration - Production application development

Troubleshooting​

Import Errors​

If you encounter import errors, ensure dqlitepy is installed:

cd ../..  # Go to repository root
uv pip install -e .

Port Conflicts​

Examples use ports 9001-9003 for dqlite nodes. If these ports are occupied:

  • Stop conflicting processes: lsof -i :9001-9003
  • Or modify port numbers in the example code

Permission Issues​

Ensure data directories are writable:

chmod -R 755 /tmp/dqlite*

Virtual Environment Issues​

If you have virtual environment conflicts:

# Remove existing venv
rm -rf .venv

# Reinstall
uv pip install -e .

Getting Help​

Contributing​

Found an issue or want to add an example? Contributions are welcome!

  1. Fork the repository
  2. Create a new example following the established structure
  3. Test your example thoroughly
  4. Submit a pull request

Next Steps​