---
title: "HeliosDB Nano SQLite Compatibility Troubleshooting Guide"
---

# HeliosDB Nano SQLite Compatibility Troubleshooting Guide

This guide helps you quickly resolve common issues when using HeliosDB Nano as a SQLite drop-in replacement.

---

## Table of Contents

1. [Installation Issues](#installation-issues)
2. [Import and Module Errors](#import-and-module-errors)
3. [Compatibility Issues](#compatibility-issues)
4. [Performance Problems](#performance-problems)
5. [Data Migration Issues](#data-migration-issues)
6. [Mode Switching Issues](#mode-switching-issues)
7. [Connection and Threading Issues](#connection-and-threading-issues)
8. [Testing and Debugging Tips](#testing-and-debugging-tips)

---

## Installation Issues

### Problem: pip install fails

**Symptoms:**
```bash
$ pip install heliosdb-sqlite
ERROR: Could not find a version that satisfies the requirement heliosdb-sqlite
```

**Cause:** `heliosdb-sqlite` is not published on PyPI, so a plain
`pip install heliosdb-sqlite` always fails with this error.

**Solutions:**

1. **Install from the SDKs source repository:**
```bash
python -m pip install --upgrade pip setuptools wheel
pip install "git+https://github.com/HeliosDatabase/HeliosDB-SDKs.git#subdirectory=sdks/python-sqlite"
```

2. **Check Python version:**
```bash
python --version  # Must be Python 3.8 or higher
```

3. **Install from a local checkout:**
```bash
git clone https://github.com/HeliosDatabase/HeliosDB-SDKs.git
cd HeliosDB-SDKs/sdks/python-sqlite
pip install .
```

---

### Problem: Import works in terminal but not in IDE

**Symptoms:**
```python
# Works in terminal
$ python -c "import heliosdb_sqlite"

# Fails in PyCharm/VSCode
ModuleNotFoundError: No module named 'heliosdb_sqlite'
```

**Solutions:**

1. **Verify IDE is using correct Python interpreter:**
   - PyCharm: Settings > Project > Python Interpreter
   - VSCode: Select interpreter from command palette (Ctrl+Shift+P)

2. **Install in IDE's environment:**
```bash
# Find IDE's Python path
which python

# Install there explicitly
/path/to/ide/python -m pip install "heliosdb-sqlite @ git+https://github.com/HeliosDatabase/HeliosDB-SDKs.git#subdirectory=sdks/python-sqlite"
```

3. **Restart IDE after installation**

---

## Import and Module Errors

### Problem: "No module named 'heliosdb_sqlite'"

**Symptoms:**
```python
import heliosdb_sqlite as sqlite3
# ModuleNotFoundError: No module named 'heliosdb_sqlite'
```

**Solutions:**

1. **Verify installation:**
```bash
pip list | grep heliosdb
python -c "import heliosdb_sqlite; print(heliosdb_sqlite.__version__)"
```

2. **Check virtual environment:**
```bash
# Activate correct environment
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

# Verify
which python
pip list
```

3. **Reinstall package:**
```bash
pip uninstall heliosdb-sqlite
pip install "git+https://github.com/HeliosDatabase/HeliosDB-SDKs.git#subdirectory=sdks/python-sqlite"
```

---

### Problem: AttributeError with HeliosDB Nano methods

**Symptoms:**
```python
conn = sqlite3.connect('app.db')
conn.some_method()
# AttributeError: 'Connection' object has no attribute 'some_method'
```

**Solutions:**

1. **Check if method is standard SQLite:**
```python
import sqlite3 as std_sqlite

# Check if method exists in standard SQLite
print(dir(std_sqlite.connect(':memory:')))
```

2. **Use HeliosDB Nano specific features correctly:**
```python
# Wrong: advanced features need to be enabled
conn = sqlite3.connect('app.db')
conn.create_branch('test')  # May fail

# Right: enable advanced features
conn = sqlite3.connect('app.db', heliosdb_mode='advanced')
branch = conn.create_branch('test')  # Works!
```

3. **Check API documentation:**
```python
# Get help on connection object
help(conn)

# List all available methods
print([m for m in dir(conn) if not m.startswith('_')])
```

---

## Compatibility Issues

### Problem: Existing code breaks with HeliosDB Nano

**Symptoms:**
```python
# Code worked with SQLite but fails with HeliosDB Nano
cursor.execute('SELECT * FROM users')
# Some error occurs
```

**Solutions:**

1. **Enable compatibility mode:**
```python
# Maximum SQLite compatibility
conn = sqlite3.connect('app.db', heliosdb_mode='sqlite_compat')
```

2. **Check for unsupported features:**
```python
# Test basic operations one by one
import heliosdb_sqlite as sqlite3

conn = sqlite3.connect(':memory:')
cursor = conn.cursor()

# Test CREATE
cursor.execute('CREATE TABLE test (id INTEGER, name TEXT)')
print("CREATE: OK")

# Test INSERT
cursor.execute('INSERT INTO test VALUES (1, "test")')
conn.commit()
print("INSERT: OK")

# Test SELECT
cursor.execute('SELECT * FROM test')
print(f"SELECT: {cursor.fetchall()}")

# Test UPDATE
cursor.execute('UPDATE test SET name = "updated" WHERE id = 1')
conn.commit()
print("UPDATE: OK")

# Test DELETE
cursor.execute('DELETE FROM test WHERE id = 1')
conn.commit()
print("DELETE: OK")
```

3. **Use fallback pattern:**
```python
# Conditional import for safety
try:
    import heliosdb_sqlite as sqlite3
    db_engine = 'heliosdb'
except Exception as e:
    print(f"HeliosDB Nano failed ({e}), falling back to SQLite")
    import sqlite3
    db_engine = 'sqlite'

print(f"Using: {db_engine}")
```

---

### Problem: SQL syntax not recognized

**Symptoms:**
```python
cursor.execute('SELECT * FROM users LIMIT 10 OFFSET 5')
# Syntax error or unexpected behavior
```

**Solutions:**

1. **Verify SQL is standard SQLite syntax:**
```python
# Test query in standard SQLite first
import sqlite3 as std_sqlite
test_conn = std_sqlite.connect(':memory:')
test_conn.execute('CREATE TABLE users (id INTEGER, name TEXT)')
test_conn.execute('INSERT INTO users VALUES (1, "test")')
result = test_conn.execute('SELECT * FROM users LIMIT 10 OFFSET 5')
print(result.fetchall())
```

2. **Check for HeliosDB Nano specific syntax:**
```python
# Some advanced features require enabling
conn = sqlite3.connect('app.db', enable_time_travel=True)

# Now time-travel syntax works
cursor.execute('''
    SELECT * FROM users
    AS OF TIMESTAMP '2024-01-01 10:00:00'
''')
```

3. **Use parameterized queries:**
```python
# Instead of string formatting
# cursor.execute(f'SELECT * FROM users WHERE id = {user_id}')  # Bad

# Use parameters
cursor.execute('SELECT * FROM users WHERE id = ?', (user_id,))  # Good
```

---

## Performance Problems

### Problem: Queries are slower than SQLite

**Symptoms:**
```python
# Query takes longer than expected
start = time.time()
cursor.execute('SELECT * FROM large_table')
results = cursor.fetchall()
print(f"Time: {time.time() - start:.2f}s")  # Slower than SQLite
```

**Solutions:**

1. **Create appropriate indexes:**
```python
# Check if indexes exist
cursor.execute("SELECT name FROM sqlite_master WHERE type='index'")
print("Existing indexes:", cursor.fetchall())

# Create missing indexes
cursor.execute('CREATE INDEX IF NOT EXISTS idx_user_email ON users(email)')
cursor.execute('CREATE INDEX IF NOT EXISTS idx_post_date ON posts(created_at)')
conn.commit()
```

2. **Enable query caching:**
```python
# Enable result caching for read-heavy workloads
conn = sqlite3.connect('app.db', enable_cache=True, cache_size_mb=100)
```

3. **Use batch operations:**
```python
# Slow: individual inserts
for user in users:
    cursor.execute('INSERT INTO users VALUES (?, ?)', user)
    conn.commit()  # Don't commit each insert!

# Fast: batch with single commit
for user in users:
    cursor.execute('INSERT INTO users VALUES (?, ?)', user)
conn.commit()  # Single commit at end

# Fastest: executemany
cursor.executemany('INSERT INTO users VALUES (?, ?)', users)
conn.commit()
```

4. **Analyze query plans:**
```python
# See how query is executed
cursor.execute('EXPLAIN QUERY PLAN SELECT * FROM users WHERE email = ?', ('test@example.com',))
plan = cursor.fetchall()
print("Query plan:", plan)

# Look for "SCAN" (bad) vs "SEARCH" (good)
# If you see SCAN, you probably need an index
```

5. **Adjust connection settings:**
```python
# Tune for performance
conn = sqlite3.connect(
    'app.db',
    isolation_level='DEFERRED',  # Less locking
    check_same_thread=False,     # Multi-threaded
    cached_statements=100,       # Cache prepared statements
    timeout=30.0                 # Longer timeout
)

# Set pragmas
conn.execute('PRAGMA journal_mode=WAL')
conn.execute('PRAGMA synchronous=NORMAL')
conn.execute('PRAGMA cache_size=10000')
conn.execute('PRAGMA temp_store=MEMORY')
```

---

### Problem: High memory usage

**Symptoms:**
```python
# Memory keeps growing
conn = sqlite3.connect('app.db')
# Memory usage increases over time
```

**Solutions:**

1. **Close connections properly:**
```python
# Use context manager
with sqlite3.connect('app.db') as conn:
    cursor = conn.cursor()
    cursor.execute('SELECT * FROM users')
    results = cursor.fetchall()
# Connection automatically closed

# Or explicit close
conn = sqlite3.connect('app.db')
try:
    # ... do work ...
finally:
    conn.close()
```

2. **Fetch data in chunks:**
```python
# Don't load all data at once
cursor.execute('SELECT * FROM large_table')

# Fetch in batches
batch_size = 1000
while True:
    rows = cursor.fetchmany(batch_size)
    if not rows:
        break
    process_rows(rows)
```

3. **Limit cache size:**
```python
conn = sqlite3.connect('app.db', cache_size_mb=50)  # Limit cache to 50MB
```

4. **Vacuum database:**
```python
# Reclaim unused space
conn.execute('VACUUM')
```

---

## Data Migration Issues

### Problem: Can't open existing SQLite database

**Symptoms:**
```python
conn = sqlite3.connect('existing.db')
# Error: database disk image is malformed
```

**Solutions:**

1. **Check database integrity:**
```bash
# Use SQLite CLI to check
sqlite3 existing.db "PRAGMA integrity_check;"
```

2. **Repair database:**
```bash
# Export and reimport
sqlite3 existing.db ".dump" > backup.sql
sqlite3 new.db < backup.sql

# Then use new.db with HeliosDB Nano
```

3. **Check file permissions:**
```bash
ls -la existing.db  # Should be readable/writable
chmod 644 existing.db
```

---

### Problem: Data looks corrupted after switching to HeliosDB Nano

**Symptoms:**
```python
# Data appears incorrect or missing
cursor.execute('SELECT * FROM users')
results = cursor.fetchall()
# Results don't match expectations
```

**Solutions:**

1. **Verify with SQLite first:**
```python
import sqlite3 as std_sqlite

# Check with standard SQLite
std_conn = std_sqlite.connect('app.db')
std_cursor = std_conn.cursor()
std_cursor.execute('SELECT COUNT(*) FROM users')
print(f"SQLite sees: {std_cursor.fetchone()[0]} users")

# Check with HeliosDB Nano
import heliosdb_sqlite
hdb_conn = heliosdb_sqlite.connect('app.db')
hdb_cursor = hdb_conn.cursor()
hdb_cursor.execute('SELECT COUNT(*) FROM users')
print(f"HeliosDB Nano sees: {hdb_cursor.fetchone()[0]} users")
```

2. **Check transaction isolation:**
```python
# Ensure proper transaction handling
conn = sqlite3.connect('app.db', isolation_level='DEFERRED')
conn.execute('BEGIN')
cursor = conn.cursor()
cursor.execute('SELECT * FROM users')
results = cursor.fetchall()
conn.commit()
```

3. **Flush caches:**
```python
# Force data to disk
conn.commit()
conn.execute('PRAGMA wal_checkpoint(FULL)')
```

---

## Mode Switching Issues

### Problem: Can't start server mode

**Symptoms:**
```python
server = sqlite3.start_server('app.db', port=5432)
# Error: Address already in use
```

**Solutions:**

1. **Check if port is in use:**
```bash
# Linux/Mac
lsof -i :5432
netstat -tuln | grep 5432

# Windows
netstat -ano | findstr :5432

# Kill existing process or use different port
```

2. **Use different port:**
```python
server = sqlite3.start_server('app.db', port=5433)  # Different port
```

3. **Check permissions:**
```bash
# Ensure you can bind to port (< 1024 needs root)
sudo python your_script.py  # If port < 1024

# Or use port > 1024
server = sqlite3.start_server('app.db', port=8432)
```

---

### Problem: Hybrid mode not working

**Symptoms:**
```python
conn = sqlite3.connect('app.db', heliosdb_mode='hybrid')
# Can't connect remotely even though server should be running
```

**Solutions:**

1. **Check server info:**
```python
conn = sqlite3.connect('app.db', heliosdb_mode='hybrid')
info = conn.get_server_info()
print(f"Server running: {info.is_running}")
print(f"Port: {info.port}")
print(f"Host: {info.host}")
```

2. **Check firewall:**
```bash
# Linux
sudo ufw status
sudo ufw allow 5432/tcp

# Check if server is listening
netstat -tuln | grep 5432
```

3. **Test connection:**
```bash
# Try connecting with psql
psql -h localhost -p 5432 -U helios app

# Or with Python
import psycopg2
conn = psycopg2.connect(host='localhost', port=5432, database='app')
```

---

## Connection and Threading Issues

### Problem: "SQLite objects created in a thread can only be used in that same thread"

**Symptoms:**
```python
conn = sqlite3.connect('app.db')
# Use connection from different thread
# Error: SQLite objects created in a thread can only be used in that same thread
```

**Solutions:**

1. **Disable thread checking:**
```python
conn = sqlite3.connect('app.db', check_same_thread=False)
```

2. **Use connection per thread:**
```python
import threading

thread_local = threading.local()

def get_connection():
    if not hasattr(thread_local, 'conn'):
        thread_local.conn = sqlite3.connect('app.db')
    return thread_local.conn

# Each thread gets its own connection
def worker():
    conn = get_connection()
    cursor = conn.cursor()
    cursor.execute('SELECT * FROM users')
```

3. **Use connection pooling:**
```python
from heliosdb_sqlite import connection_pool

pool = connection_pool.create('app.db', pool_size=10)

def worker():
    with pool.connection() as conn:
        cursor = conn.cursor()
        cursor.execute('SELECT * FROM users')
```

---

### Problem: Concurrent write deadlocks

**Symptoms:**
```python
# Multiple threads trying to write
# Some threads hang or timeout
```

**Solutions:**

1. **HeliosDB Nano should handle this, but if it happens:**
```python
# Increase timeout
conn = sqlite3.connect('app.db', timeout=30.0)

# Use retry logic
import time

def write_with_retry(query, params, max_retries=3):
    for attempt in range(max_retries):
        try:
            cursor.execute(query, params)
            conn.commit()
            return
        except sqlite3.OperationalError as e:
            if 'locked' in str(e) and attempt < max_retries - 1:
                time.sleep(0.1 * (2 ** attempt))  # Exponential backoff
            else:
                raise
```

2. **Check if you're actually using HeliosDB Nano:**
```python
import heliosdb_sqlite as sqlite3
print(f"Using: {sqlite3.__name__}")  # Should say 'heliosdb_sqlite'
```

---

## Testing and Debugging Tips

### Enable debug logging

```python
import heliosdb_sqlite as sqlite3
import logging

# Enable debug logging
logging.basicConfig(level=logging.DEBUG)
sqlite3.enable_debug_logging()

# Now all database operations are logged
conn = sqlite3.connect('app.db')
cursor = conn.cursor()
cursor.execute('SELECT * FROM users')
```

---

### Compare behavior with SQLite

```python
import sqlite3 as std_sqlite
import heliosdb_sqlite as hdb_sqlite

def test_query(db_module, name):
    try:
        conn = db_module.connect(':memory:')
        cursor = conn.cursor()

        cursor.execute('CREATE TABLE test (id INTEGER, value TEXT)')
        cursor.execute('INSERT INTO test VALUES (1, "hello")')
        conn.commit()

        cursor.execute('SELECT * FROM test')
        result = cursor.fetchall()

        print(f"{name}: {result}")
        conn.close()
        return True
    except Exception as e:
        print(f"{name} failed: {e}")
        return False

# Test both
test_query(std_sqlite, "SQLite")
test_query(hdb_sqlite, "HeliosDB Nano")
```

---

### Isolate the problem

```python
# Minimal reproducible example
import heliosdb_sqlite as sqlite3

# Test with in-memory database (simpler)
conn = sqlite3.connect(':memory:')
cursor = conn.cursor()

# Test your exact failing query
try:
    cursor.execute('YOUR FAILING QUERY HERE')
    print("Query succeeded!")
except Exception as e:
    print(f"Query failed: {e}")
    import traceback
    traceback.print_exc()
```

---

### Check HeliosDB Nano version and capabilities

```python
import heliosdb_sqlite as sqlite3

print(f"HeliosDB Nano version: {sqlite3.__version__}")
print(f"SQLite version: {sqlite3.sqlite_version}")

# Check available features
conn = sqlite3.connect(':memory:')
features = conn.get_features()
print(f"Vector search: {features.vector_search}")
print(f"Time-travel: {features.time_travel}")
print(f"Branching: {features.branching}")
print(f"Encryption: {features.encryption}")
```

---

### Generate diagnostic report

```python
def generate_diagnostic_report():
    import heliosdb_sqlite as sqlite3
    import sys
    import platform

    print("=== HeliosDB Nano Diagnostic Report ===\n")

    print(f"Python version: {sys.version}")
    print(f"Platform: {platform.platform()}")
    print(f"HeliosDB Nano version: {sqlite3.__version__}")
    print(f"SQLite version: {sqlite3.sqlite_version}")

    print("\nTesting basic operations...")

    try:
        conn = sqlite3.connect(':memory:')
        cursor = conn.cursor()

        cursor.execute('CREATE TABLE test (id INTEGER)')
        cursor.execute('INSERT INTO test VALUES (1)')
        cursor.execute('SELECT * FROM test')
        result = cursor.fetchall()

        print(f"Basic operations: OK")
        print(f"Result: {result}")

        conn.close()
    except Exception as e:
        print(f"Basic operations: FAILED")
        print(f"Error: {e}")

    print("\n=== End Diagnostic Report ===")

# Run diagnostic
generate_diagnostic_report()
```

---

## Getting Help

If you've tried these solutions and still have issues:

1. **Check GitHub Issues:** https://github.com/HeliosDatabase/HeliosDB-Nano/issues
2. **Ask on Stack Overflow:** Tag with `heliosdb`
3. **Join Discord Community:** Real-time help from users
4. **Email Support:** support@heliosdb.com

**When asking for help, include:**
- HeliosDB Nano version (`sqlite3.__version__`)
- Python version
- Operating system
- Minimal code that reproduces the issue
- Full error message and traceback
- What you've already tried

---

## Common Error Messages

### "database is locked"

**Cause:** A second process tried to open a data directory that another process
already owns. A Nano data directory belongs to exactly one running process —
this is expected behaviour, not a bug, and raising `timeout` will not fix it.

**Fix:** decide which single process owns the directory.

- If only one process should be using it, find and stop the other one (a stray
  REPL, a leftover daemon — `heliosdb-nano status --pid-file …`).
- If several callers genuinely need the same data, run Nano as a server and
  connect to it instead of opening the directory directly:

```bash
heliosdb-nano start --data-dir ./my-data --port 5432 --listen 127.0.0.1
```

```python
import psycopg2
conn = psycopg2.connect(host="127.0.0.1", port=5432)
```

See [Deployment Modes](https://www.heliosdb.com/docs/nano/guides/deployment_modes/) and
[Concurrency and transactions](https://www.heliosdb.com/docs/nano/guides/concurrency-and-transactions/).

---

### "no such table"

**Cause:** Table doesn't exist or transaction issues

**Fix:**
```python
# List all tables
cursor.execute("SELECT name FROM sqlite_master WHERE type='table'")
print("Available tables:", cursor.fetchall())

# Create table if missing
cursor.execute('CREATE TABLE IF NOT EXISTS users (id INTEGER, name TEXT)')
```

---

### "disk I/O error"

**Cause:** Permissions, disk space, or hardware issues

**Fix:**
```bash
# Check disk space
df -h

# Check permissions
ls -la database.db

# Check disk health
# Linux: sudo smartctl -H /dev/sda
# Mac: diskutil verifyVolume /
```

---

## Prevention Tips

1. **Always use context managers:**
```python
with sqlite3.connect('app.db') as conn:
    # Work with database
    pass
# Automatically closed and committed
```

2. **Use parameterized queries:**
```python
cursor.execute('SELECT * FROM users WHERE id = ?', (user_id,))  # Safe
```

3. **Handle exceptions:**
```python
try:
    conn.execute('INSERT INTO users VALUES (?, ?)', (id, name))
    conn.commit()
except sqlite3.IntegrityError:
    print("Duplicate key")
    conn.rollback()
except Exception as e:
    print(f"Unexpected error: {e}")
    conn.rollback()
    raise
```

4. **Test thoroughly:**
```python
# Test suite should cover
pytest tests/ -v --cov

# Include integration tests
# Include concurrent access tests
# Include migration tests
```

5. **Monitor in production:**
```python
conn.enable_monitoring()
metrics = conn.get_metrics()
# Alert on anomalies
```

---

**For more help:**
- `HELIOSDB_SQLITE_DROP_IN_GUIDE.md` - Getting started
- `HELIOSDB_SQLITE_FAQ.md` - Common questions
- `HELIOSDB_SQLITE_ADVANCED_FEATURES.md` - Advanced usage
- GitHub Issues - Bug reports and discussions