HeliosDB Nano SQLite Compatibility Layer - Distribution Guide

HeliosDB Nano SQLite Compatibility Layer - Distribution Guide

Package: heliosdb-sqlite Version: 3.0.0 Platform: PyPI Last Updated: 2025-12-08

---

Table of Contents

1. Installation Methods
2. Version Compatibility Matrix
3. Platform Support
4. Troubleshooting Installation
5. Building from Source
6. Contributing Guidelines
7. Release Process

---

1. Installation Methods

1.1 Standard Installation (Recommended)

Install the latest stable version from PyPI:

pip install heliosdb-sqlite

Verify installation:

python -c "import heliosdb_sqlite; print(heliosdb_sqlite.__version__)"
# Output: 3.0.0

1.2 Install with Optional Dependencies

Vector operations support (numpy, scipy):

pip install heliosdb-sqlite[vector]

Pandas DataFrame integration:

pip install heliosdb-sqlite[pandas]

Async operations support:

pip install heliosdb-sqlite[async]

All optional features:

pip install heliosdb-sqlite[all]

1.3 Install Specific Version

# Install specific version
pip install heliosdb-sqlite==3.0.0

# Install with version constraints
pip install "heliosdb-sqlite>=3.0.0,<4.0.0"

# Install pre-release versions
pip install --pre heliosdb-sqlite

1.4 Install from Test PyPI

For testing pre-release versions:

pip install --index-url https://test.pypi.org/simple/ heliosdb-sqlite

1.5 Install from Source Repository

# Install latest development version
pip install git+https://github.com/dimensigon/HDB-HeliosDB-Nano.git#subdirectory=sdks/python-sqlite

# Install specific branch
pip install git+https://github.com/dimensigon/HDB-HeliosDB-Nano.git@main#subdirectory=sdks/python-sqlite

# Install specific tag
pip install git+https://github.com/dimensigon/HDB-HeliosDB-Nano.git@v3.0.0#subdirectory=sdks/python-sqlite

1.6 Upgrade Existing Installation

# Upgrade to latest version
pip install --upgrade heliosdb-sqlite

# Force reinstall (useful for troubleshooting)
pip install --force-reinstall heliosdb-sqlite

1.7 Conda Installation (Future)

Planned for v3.1.0:

# Install from conda-forge
conda install -c conda-forge heliosdb-sqlite

# Create new environment
conda create -n myapp python=3.11 heliosdb-sqlite
conda activate myapp

---

2. Version Compatibility Matrix

2.1 Python Version Compatibility

heliosdb-sqlite Version	Python 3.8	Python 3.9	Python 3.10	Python 3.11	Python 3.12	Python 3.13
3.0.0 (Current)	✅	✅	✅	✅	✅	✅
3.0.1 (Planned)	✅	✅	✅	✅	✅	✅
3.1.0 (Future)	❌	✅	✅	✅	✅	✅

Legend:

• ✅ Fully supported with binary wheels
• ⚠️ Supported but requires building from source
• ❌ Not supported

2.2 Operating System Compatibility

OS	Architecture	Wheel Type	Status	Notes
Linux	x86_64	manylinux2014	✅	CentOS 7+ compatible
Linux	aarch64	manylinux2014	✅	ARM64 support
Linux	x86	Source only	⚠️	Requires manual build
macOS	x86_64	macosx_10_12	✅	Intel Macs, 10.12+
macOS	arm64	macosx_11_0	✅	Apple Silicon, 11.0+
Windows	x86_64	win_amd64	✅	64-bit Windows 10+
Windows	x86	Source only	⚠️	Requires manual build
FreeBSD	Any	Source only	⚠️	Community support

2.3 HeliosDB Nano Version Mapping

heliosdb-sqlite	HeliosDB Nano	SQLite API	Key Features
3.0.0	3.0.0	3.43.0	Initial GA release
3.0.1	3.0.1	3.43.0	Bug fixes, stability improvements
3.1.0	3.1.0	3.44.0	New SQLite features, conda support
3.2.0	3.2.0	3.45.0	Performance optimizations

---

3. Platform Support

3.1 Linux

Supported Distributions:

• Ubuntu 18.04+ (LTS)
• Debian 10+ (Buster)
• CentOS 7+ / RHEL 7+
• Fedora 32+
• Arch Linux (rolling)
• Alpine Linux (via source build)

Minimum Requirements:

• glibc 2.17+ (manylinux2014 compatibility)
• 64-bit architecture (x86_64 or aarch64)

Installation:

# Standard installation
pip install heliosdb-sqlite

# Verify platform
python -c "import platform; print(platform.platform())"

3.2 macOS

Supported Versions:

• macOS 10.12 (Sierra) or later for Intel
• macOS 11.0 (Big Sur) or later for Apple Silicon

Installation:

# Standard installation (works for both Intel and Apple Silicon)
pip install heliosdb-sqlite

# Verify architecture
python -c "import platform; print(platform.machine())"
# Output: x86_64 (Intel) or arm64 (Apple Silicon)

Rosetta 2 Note: Apple Silicon Macs can run x86_64 wheels via Rosetta 2, but native arm64 wheels provide better performance.

3.3 Windows

Supported Versions:

• Windows 10 (64-bit)
• Windows 11 (64-bit)
• Windows Server 2016+

Installation:

# Standard installation
pip install heliosdb-sqlite

# Verify installation
python -c "import heliosdb_sqlite; print(heliosdb_sqlite.__version__)"

Windows-Specific Notes:

• Requires Microsoft Visual C++ 14.0 or greater (usually pre-installed)
• Binary is included as .exe in wheel
• Antivirus software may need to whitelist heliosdb-nano.exe

---

4. Troubleshooting Installation

4.1 Common Issues

Issue: “No matching distribution found”

Symptom:

ERROR: Could not find a version that satisfies the requirement heliosdb-sqlite
ERROR: No matching distribution found for heliosdb-sqlite

Solutions:

1. Upgrade pip: pip install --upgrade pip
2. Check Python version: python --version (must be 3.8+)
3. Check platform: python -c "import platform; print(platform.platform())"
4. Try installing from source (see section 5)

Issue: “Binary not found” or “Permission denied”

Symptom:

FileNotFoundError: HeliosDB Nano binary not found at /path/to/binary
PermissionError: [Errno 13] Permission denied: '/path/to/binary'

Solutions:

# 1. Reinstall with force
pip install --force-reinstall --no-cache-dir heliosdb-sqlite

# 2. Check binary permissions (Unix/macOS)
python -c "import heliosdb_sqlite; print(heliosdb_sqlite.get_binary_path())"
# Then manually set executable:
chmod +x /path/to/binary

# 3. Check antivirus (Windows)
# Add exception for heliosdb-nano.exe in Windows Defender or antivirus software

Issue: “Platform not supported”

Symptom:

ERROR: heliosdb-sqlite is not available for this platform

Solutions:

1. Check platform compatibility in section 2.2
2. Build from source (see section 5)
3. Use Docker container (see section 4.3)

Issue: “Import error after installation”

Symptom:

ImportError: cannot import name 'connect' from 'heliosdb_sqlite'
ModuleNotFoundError: No module named 'heliosdb_sqlite'

Solutions:

# 1. Verify installation
pip list | grep heliosdb-sqlite

# 2. Check Python path
python -c "import sys; print('\n'.join(sys.path))"

# 3. Reinstall in correct environment
pip uninstall heliosdb-sqlite
pip install heliosdb-sqlite

# 4. Check for name conflicts
python -c "import heliosdb_sqlite; print(heliosdb_sqlite.__file__)"

4.2 Diagnostic Commands

Run comprehensive diagnostics:

# Check installation
python -m heliosdb_sqlite.cli check

# Output example:
# ✓ heliosdb-sqlite version: 3.0.0
# ✓ Python version: 3.11.5
# ✓ Platform: Linux-5.15.0-x86_64
# ✓ Binary found: /home/user/.heliosdb/bin/heliosdb-nano-linux-x86_64
# ✓ Binary executable: Yes
# ✓ Binary version: 3.0.0
# ✓ All checks passed!

Manual verification:

import heliosdb_sqlite

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

# Check binary path
binary_path = heliosdb_sqlite.get_binary_path()
print(f"Binary: {binary_path}")
print(f"Binary exists: {binary_path.exists()}")

# Test connection
conn = heliosdb_sqlite.connect(":memory:")
cursor = conn.cursor()
cursor.execute("SELECT 'Hello, HeliosDB!'")
print(cursor.fetchone())
conn.close()

4.3 Docker Workaround

If installation fails on your platform, use Docker:

# Dockerfile
FROM python:3.11-slim

RUN pip install --no-cache-dir heliosdb-sqlite[all]

WORKDIR /app
COPY . /app

CMD ["python", "app.py"]

# Build and run
docker build -t myapp .
docker run -v $(pwd):/app myapp

---

5. Building from Source

5.1 Prerequisites

Required:

• Python 3.8 or later
• Rust toolchain 1.75 or later
• C compiler (gcc, clang, or MSVC)
• Git

Platform-Specific:

Linux:

# Debian/Ubuntu
sudo apt-get update
sudo apt-get install build-essential git curl

# Fedora/RHEL
sudo dnf install gcc git curl

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

macOS:

# Install Xcode Command Line Tools
xcode-select --install

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

Windows:

# Install Visual Studio Build Tools
# Download from: https://visualstudio.microsoft.com/downloads/

# Install Rust
# Download from: https://rustup.rs/
# Or use: winget install Rustlang.Rustup

5.2 Build Steps

Clone repository:

git clone https://github.com/dimensigon/HDB-HeliosDB-Nano.git
cd heliosdb-nano/sdks/python-sqlite

Build in development mode:

# Install in editable mode (recommended for development)
pip install -e .

# Or with optional dependencies
pip install -e ".[dev,all]"

Build wheel:

# Install build tools
pip install build wheel

# Build wheel
python -m build

# Install built wheel
pip install dist/heliosdb_sqlite-3.0.0-*.whl

Build with specific Rust target:

# Cross-compile for different architecture
export CARGO_BUILD_TARGET=aarch64-unknown-linux-gnu
rustup target add aarch64-unknown-linux-gnu
python -m build

5.3 Run Tests

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=heliosdb_sqlite --cov-report=html

# Run specific test
pytest tests/test_connection.py -v

---

6. Contributing Guidelines

6.1 Development Setup

# Fork and clone repository
git clone https://github.com/YOUR_USERNAME/heliosdb-nano.git
cd heliosdb-nano/sdks/python-sqlite

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode with all dependencies
pip install -e ".[dev,all]"

# Install pre-commit hooks
pip install pre-commit
pre-commit install

6.2 Code Quality Standards

Before submitting pull request:

# Format code
black heliosdb_sqlite/ tests/
isort heliosdb_sqlite/ tests/

# Lint code
ruff check heliosdb_sqlite/ tests/

# Type checking
mypy heliosdb_sqlite/

# Run tests
pytest tests/ --cov=heliosdb_sqlite

6.3 Submitting Changes

1. Create feature branch: git checkout -b feature/my-feature
2. Make changes and add tests
3. Ensure all tests pass
4. Commit with descriptive message
5. Push to your fork
6. Create pull request on GitHub

Pull Request Template:

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] All tests pass
- [ ] New tests added
- [ ] Manual testing completed

## Checklist
- [ ] Code follows style guidelines
- [ ] Documentation updated
- [ ] CHANGELOG.md updated

---

7. Release Process

7.1 Version Numbering

Semantic Versioning: MAJOR.MINOR.PATCH

• MAJOR: Breaking API changes
• MINOR: New features, backward compatible
• PATCH: Bug fixes, no API changes

Pre-release Suffixes:

• -alpha: Early development
• -beta: Feature complete, testing
• -rc1, -rc2: Release candidates

7.2 Release Checklist

For Maintainers:

1. Prepare Release:

   # Update version
   python scripts/bump_version.py minor  # or major/patch
   
   # Update CHANGELOG.md
   # Add release notes
   
   # Commit changes
   git add -A
   git commit -m "chore: Bump version to 3.1.0"

2. Create Tag:

   git tag -a v3.1.0 -m "Release v3.1.0"
   git push origin v3.1.0

3. Build and Test:

   # Build wheels
   python -m build
   
   # Test installation
   pip install dist/heliosdb_sqlite-3.1.0-*.whl
   python -m heliosdb_sqlite.cli check

4. Upload to Test PyPI:

   python -m twine upload --repository testpypi dist/*
   
   # Test installation from Test PyPI
   pip install --index-url https://test.pypi.org/simple/ heliosdb-sqlite==3.1.0

5. Upload to PyPI:

   python -m twine upload dist/*

6. Create GitHub Release:

   • Go to GitHub Releases
   • Create new release from tag
   • Add release notes
   • Attach wheel files

7. Announce Release:

   • Update documentation
   • Post on Discord/Twitter
   • Update project homepage

7.3 Automated Release (CI/CD)

Release workflow triggers automatically on tag push:

# Push tag triggers GitHub Actions
git tag v3.1.0
git push origin v3.1.0

# CI will:
# 1. Run tests
# 2. Build wheels for all platforms
# 3. Publish to PyPI
# 4. Create GitHub release

---

Appendix: Quick Reference

Installation Commands

# Standard installation
pip install heliosdb-sqlite

# With optional dependencies
pip install heliosdb-sqlite[vector]    # Vector operations
pip install heliosdb-sqlite[pandas]    # Pandas integration
pip install heliosdb-sqlite[all]       # All features

# Development installation
pip install -e ".[dev]"

# Upgrade
pip install --upgrade heliosdb-sqlite

# Specific version
pip install heliosdb-sqlite==3.0.0

Verification Commands

# Check version
python -c "import heliosdb_sqlite; print(heliosdb_sqlite.__version__)"

# Run diagnostics
python -m heliosdb_sqlite.cli check

# Test connection
python -c "import heliosdb_sqlite; conn = heliosdb_sqlite.connect(':memory:'); print('OK')"

Support Resources

• Documentation: https://docs.heliosdb.io/sqlite-compat
• GitHub Issues: https://github.com/dimensigon/HDB-HeliosDB-Nano/issues
• Discord: https://discord.gg/heliosdb
• Email: support@heliosdb.io

---

Document Version: 1.0 Last Updated: 2025-12-08 Maintainer: HeliosDB Team