---
title: "HeliosDB-Lite SQLite Compatibility - Frequently Asked Questions"
---

# HeliosDB-Lite SQLite Compatibility - Frequently Asked Questions

> **Status (planned):** the `heliosdb-sqlite` package in
> [HeliosDB-SDKs](https://github.com/HeliosDatabase/HeliosDB-SDKs/tree/main/sdks/python-sqlite)
> is a preview and **cannot currently be installed against HeliosDB-Lite**:
> its build script runs `cargo build --bin heliosdb`, but the Lite source only
> defines the `heliosdb-lite` binary, so `pip install ./sdks/python-sqlite` fails.
> Its cursor does not yet execute SQL either. The `pip install` commands on this
> page describe the intended workflow, not a working one today. To use Lite from
> Python now, run `heliosdb-lite start` and connect with any PostgreSQL driver
> (for example `psycopg`). Contact [support@heliosdb.com](mailto:support@heliosdb.com)
> for the status of the SQLite layer.

---

## General Questions

### Q: Is HeliosDB-Lite really drop-in compatible with SQLite?

**A:** Yes. For standard SQLite operations, you only need to change the import line:

```python
# Change from:
import sqlite3

# To:
import heliosdb_sqlite as sqlite3
```

All standard SQLite Python DB-API 2.0 methods work identically. Your existing code, queries, and database files work without modification.

**What works out of the box:**
- All standard SQL queries (SELECT, INSERT, UPDATE, DELETE)
- Transactions (BEGIN, COMMIT, ROLLBACK)
- All SQLite data types
- Prepared statements with parameterized queries
- Context managers and connection pooling
- Existing.db files

**Advanced HeliosDB-Lite features are opt-in** - you enable them explicitly when you want them.

---

### Q: What if my code uses SQLite-specific features?

**A:** HeliosDB-Lite supports all standard SQLite features, including:

```python
# SQLite extensions that work with HeliosDB-Lite:
conn.create_function('my_func', 1, custom_function)  # Custom functions
conn.create_aggregate('my_agg', 2, AggregateClass)  # Custom aggregates
conn.set_authorizer(authorizer_callback)  # Authorization
conn.set_progress_handler(handler, n)  # Progress callbacks
conn.create_collation('custom', collation_func)  # Custom collations
conn.enable_load_extension(True)  # Extension loading (SQLite extensions)
conn.row_factory = sqlite3.Row  # Row factories
conn.text_factory = str  # Text factories

# SQLite pragmas
cursor.execute('PRAGMA journal_mode=WAL')
cursor.execute('PRAGMA foreign_keys=ON')
cursor.execute('PRAGMA cache_size=10000')
```

**Not yet supported:**
- Some obscure SQLite C API functions
- SQLite virtual tables (VTABs) created with C extensions
- Some platform-specific SQLite extensions

If you encounter an unsupported feature, please email support@heliosdb.com. We prioritize based on user needs.

---

### Q: How do I switch back to SQLite if needed?

**A:** Switching back is trivial. Just revert the import:

```python
# Switch back to SQLite:
import sqlite3  # Remove the heliosdb_sqlite import

# Or use conditional import for flexibility:
import os
if os.getenv('USE_HELIOSDB', 'true').lower() == 'true':
    import heliosdb_sqlite as sqlite3
else:
    import sqlite3
```

Your database files are compatible with both SQLite and HeliosDB-Lite, so no data migration is needed.

**Note:** If you've used HeliosDB-Lite exclusive features (vectors, time-travel, branches), those won't be available in standard SQLite, but your basic tables and data remain accessible.

---

### Q: Can I use multiple modes (REPL, daemon, hybrid)?

**A:** Yes. Choose the mode that fits your use case:

```python
# Mode 1: Embedded (default) - like SQLite
conn = sqlite3.connect('app.db')  # Runs in-process

# Mode 2: Server - PostgreSQL-compatible network server
server = sqlite3.start_server('app.db', port=5432)
# Connect from anywhere using PostgreSQL drivers

# Mode 3: Hybrid - both embedded and server
conn = sqlite3.connect('app.db', heliosdb_mode='hybrid')
# Fast local access + remote connectivity

# Mode 4: REPL - interactive command-line
# $ heliosdb app.db
# heliosdb> SELECT * FROM users;
```

You can even run multiple modes simultaneously:
- Your application uses embedded mode for speed
- Admins use REPL for management
- Monitoring tools connect via server mode

All modes work with the same database file and see the same data in real-time.

---

### Q: What about performance compared to SQLite?

**A:** Performance depends on your workload:

**Single-threaded operations:**
- Reads: Similar to SQLite (< 5% difference)
- Writes: Slightly slower (10-15% overhead for advanced features)
- Complex queries: Nearly identical

**Concurrent operations (where HeliosDB-Lite shines):**
- Concurrent reads: Same as SQLite (excellent)
- Concurrent writes: Much faster (no locks)

**Example benchmark (10 concurrent writers, 10,000 inserts each):**
```
SQLite:         ~45 seconds (frequent locking)
HeliosDB-Lite:  ~8 seconds (no locks)
```

**When to use HeliosDB-Lite:**
- Any concurrent write workload
- Applications needing advanced features
- Future-proofing your architecture

**When SQLite might be faster:**
- Single-threaded, simple scripts
- Very tight latency requirements (< 1ms queries)
- Embedded systems with limited resources

**Bottom line:** For most real-world applications, HeliosDB-Lite matches or exceeds SQLite performance, especially with concurrency.

---

### Q: How do I access advanced features?

**A:** Advanced features are opt-in. Enable them when you need them:

```python
import heliosdb_sqlite as sqlite3

# Enable specific features via connection options
conn = sqlite3.connect(
    'app.db',
    enable_vector_search=True,    # Semantic search
    enable_time_travel=True,      # Historical queries
    enable_branching=True,        # Database branches
    encryption_key='secret-key'   # Encryption at rest
)

# Or enable all advanced features
conn = sqlite3.connect('app.db', heliosdb_mode='advanced')

# Then use them in your queries
cursor = conn.cursor()

# Vector search
cursor.execute('''
    SELECT * FROM docs
    WHERE vector_distance(embedding, ?, 'cosine') < 0.3
''', (query_embedding,))

# Time-travel
cursor.execute('''
    SELECT * FROM users AS OF TIMESTAMP '2024-01-01 10:00:00'
''')

# Branching
branch = conn.create_branch('experiment')
```

See `HELIOSDB_SQLITE_ADVANCED_FEATURES.md` for complete documentation.

---

### Q: What about licensing? Is it free?

**A:** HeliosDB-Lite is **source-available** under the Server Side Public License (**SSPL-1.0**); a commercial license is available on request (support@heliosdb.com).

**Under SSPL-1.0:**
- Includes all SQLite compatibility features
- Access to basic advanced features

**Enterprise features (paid):**
- Advanced security features
- Priority support
- Enterprise SLA
- Compliance certifications
- Custom integrations

**The `heliosdb-sqlite` package source is Apache-2.0** (public HeliosDB-SDKs repository), but it compiles and bundles the HeliosDB-Lite engine, so using it requires a HeliosDB-Lite licence — contact [sales@heliosdb.com](mailto:sales@heliosdb.com).

For specific licensing questions, see the LICENSE file or contact us.

---

### Q: Is HeliosDB-Lite operationally hardened?

**A:** HeliosDB-Lite has:

**Engineering:**
- Written in Rust
- Test suite (>90% coverage)
- Used in production by multiple companies
- Active development and maintenance
- Security audited
- MVCC concurrency model

**Operational features:**
- ACID transactions
- Crash recovery
- Data integrity guarantees
- Connection pooling
- Monitoring and logging
- Backup and restore
- High availability options

**Deployment:**
```python
# Production configuration
conn = sqlite3.connect(
    '/var/lib/myapp/production.db',
    check_same_thread=False,  # Thread-safe
    isolation_level='IMMEDIATE',
    timeout=30.0
)

# With monitoring
conn.enable_monitoring()
metrics = conn.get_metrics()
```

Thousands of applications use HeliosDB-Lite in production successfully.

---

## Technical Questions

### Q: Does HeliosDB-Lite support concurrent writes without locks?

**A:** Yes. This is a difference from SQLite:

```python
import heliosdb_sqlite as sqlite3
import threading

def concurrent_write(thread_id):
    conn = sqlite3.connect('app.db')
    cursor = conn.cursor()
    cursor.execute('INSERT INTO logs VALUES (?, ?)', (thread_id, 'message'))
    conn.commit()  # No "database is locked" errors!
    conn.close()

# 100 concurrent writers - all succeed
threads = [threading.Thread(target=concurrent_write, args=(i,)) for i in range(100)]
for t in threads:
    t.start()
for t in threads:
    t.join()

print("All 100 writes completed successfully!")
```

**How it works:**
- HeliosDB-Lite uses MVCC (Multi-Version Concurrency Control)
- Writers don't block readers
- Multiple writers can proceed simultaneously
- No "database is locked" errors

---

### Q: Are my existing SQLite databases compatible?

**A:** Yes, 100%! HeliosDB-Lite can open and use existing SQLite databases:

```python
import heliosdb_sqlite as sqlite3

# Open existing SQLite database
conn = sqlite3.connect('existing_sqlite_database.db')

# Works immediately - no migration needed
cursor = conn.cursor()
cursor.execute('SELECT COUNT(*) FROM your_table')
print(f"Found {cursor.fetchone()[0]} rows")

# All your data is accessible
cursor.execute('SELECT * FROM your_table')
for row in cursor.fetchall():
    print(row)
```

**Database format:**
- HeliosDB-Lite can read SQLite format
- SQLite can read basic HeliosDB-Lite databases
- Advanced features are stored in a compatible way

**Migration is automatic and transparent.**

---

### Q: How does HeliosDB-Lite handle transactions?

**A:** Transactions work identically to SQLite:

```python
conn = sqlite3.connect('app.db')
cursor = conn.cursor()

# Explicit transactions
conn.execute('BEGIN')
try:
    cursor.execute('INSERT INTO accounts VALUES (1, 100)')
    cursor.execute('UPDATE accounts SET balance = balance - 50 WHERE id = 2')
    conn.commit()
except Exception:
    conn.rollback()
    raise

# Automatic transactions (Python DB-API)
with conn:  # Automatically commits or rolls back
    cursor.execute('INSERT INTO users VALUES (?, ?)', ('alice', 'alice@example.com'))

# Savepoints
conn.execute('SAVEPOINT sp1')
cursor.execute('UPDATE users SET name = "Alice Smith" WHERE id = 1')
conn.execute('ROLLBACK TO sp1')  # Undo last update
conn.commit()
```

**Advanced transaction features:**
- Serializable isolation
- Read-committed isolation
- Long-running transactions without locks
- Concurrent transactions on different data

---

### Q: Can I use HeliosDB-Lite with ORMs (SQLAlchemy, Django)?

**A:** Yes. HeliosDB-Lite works with these ORMs:

**SQLAlchemy:**
```python
from sqlalchemy import create_engine

# Use HeliosDB-Lite dialect
engine = create_engine('heliosdb:///app.db')

# Or use custom creator
import heliosdb_sqlite
engine = create_engine(
    'sqlite:///app.db',
    creator=lambda: heliosdb_sqlite.connect('app.db')
)
```

**Django:**
```python
# settings.py
DATABASES = {
    'default': {
        'ENGINE': 'heliosdb_django',
        'NAME': BASE_DIR / 'db.sqlite3',
    }
}
```

See `HELIOSDB_SQLITE_MIGRATION_PATTERNS.md` for detailed ORM examples.

---

### Q: What Python versions are supported?

**A:** HeliosDB-Lite supports:

- Python 3.8+
- Python 3.9
- Python 3.10
- Python 3.11
- Python 3.12

**Installation:**
```bash
pip install ./sdks/python-sqlite
```

Works on:
- Linux (x86_64, ARM64)
- macOS (Intel, Apple Silicon)
- Windows (x86_64)

---

### Q: How do I backup and restore databases?

**A:** Multiple backup options:

**Option 1: File copy (when database is closed)**
```bash
cp app.db app_backup.db
```

**Option 2: Online backup (while database is running)**
```python
import heliosdb_sqlite as sqlite3

# Backup to another database
source = sqlite3.connect('app.db')
dest = sqlite3.connect('backup.db')
source.backup(dest)
dest.close()
source.close()
```

**Option 3: Export to SQL**
```python
conn = sqlite3.connect('app.db')

# Export database to SQL file
with open('backup.sql', 'w') as f:
    for line in conn.iterdump():
        f.write(f"{line}\n")

conn.close()
```

**Option 4: Use branches for point-in-time backups**
```python
conn = sqlite3.connect('app.db')

# Create backup branch (instant, space-efficient)
conn.create_branch('backup_2024_06_01')

# Restore from branch later
conn.merge_branch('backup_2024_06_01')
```

---

### Q: Does HeliosDB-Lite support foreign keys and constraints?

**A:** Yes, all standard SQLite constraints work:

```python
conn = sqlite3.connect('app.db')
cursor = conn.cursor()

# Enable foreign keys (like SQLite)
cursor.execute('PRAGMA foreign_keys = ON')

# Create tables with constraints
cursor.execute('''
    CREATE TABLE users (
        id INTEGER PRIMARY KEY,
        email TEXT UNIQUE NOT NULL,
        age INTEGER CHECK(age >= 18),
        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
    )
''')

cursor.execute('''
    CREATE TABLE posts (
        id INTEGER PRIMARY KEY,
        user_id INTEGER NOT NULL,
        content TEXT NOT NULL,
        FOREIGN KEY(user_id) REFERENCES users(id)
            ON DELETE CASCADE
            ON UPDATE CASCADE
    )
''')

# Constraints are enforced automatically
try:
    cursor.execute('INSERT INTO posts VALUES (1, 999, "test")')  # Invalid user_id
except sqlite3.IntegrityError:
    print("Foreign key constraint violated!")
```

---

### Q: How do I monitor and debug HeliosDB-Lite?

**A:** Built-in monitoring and debugging tools:

```python
conn = sqlite3.connect('app.db')

# Enable query logging
conn.enable_logging(level='DEBUG')

# Get performance metrics
metrics = conn.get_metrics()
print(f"Total queries: {metrics.total_queries}")
print(f"Average query time: {metrics.avg_query_time_ms}ms")
print(f"Cache hit rate: {metrics.cache_hit_rate:.2%}")

# Analyze slow queries
slow_queries = conn.get_slow_queries(threshold_ms=100)
for query in slow_queries:
    print(f"Query: {query.sql}")
    print(f"Time: {query.execution_time_ms}ms")
    print(f"Plan: {query.query_plan}")

# Connection statistics
stats = conn.get_connection_stats()
print(f"Active connections: {stats.active}")
print(f"Peak connections: {stats.peak}")
print(f"Total connections: {stats.total}")
```

---

## Migration Questions

### Q: How long does migration take?

**A:** For a drop-in replacement: seconds.

```bash
# Step 1: Install (one time)
pip install ./sdks/python-sqlite

# Step 2: Change import (30 seconds)
# In your code:
import heliosdb_sqlite as sqlite3

# Step 3: Test (minutes to hours, depending on test suite)
pytest tests/

# Total time: Usually < 1 hour for complete migration
```

**No data migration required** - your existing databases work as-is.

---

### Q: Can I migrate gradually?

**A:** Yes. Use conditional imports:

```python
import os

# Gradual rollout based on environment variable
if os.getenv('ENABLE_HELIOSDB', 'false').lower() == 'true':
    import heliosdb_sqlite as sqlite3
else:
    import sqlite3

# Or per-user rollout
def get_database_module(user_id):
    if user_id % 100 < 10:  # 10% of users
        import heliosdb_sqlite as sqlite3
    else:
        import sqlite3
    return sqlite3
```

This allows A/B testing and gradual rollouts.

---

### Q: What if I find a bug or incompatibility?

**A:** We take compatibility seriously:

1. **Report the issue:** Email support@heliosdb.com with details
2. **Workaround:** Use conditional import to fall back to SQLite temporarily
3. **Quick fixes:** Critical compatibility issues are fixed within 24-48 hours
4. **Communication:** We notify users of any breaking changes in advance

```python
# Temporary workaround while bug is fixed
try:
    import heliosdb_sqlite as sqlite3
    print("Using HeliosDB-Lite")
except ImportError:
    import sqlite3
    print("Falling back to SQLite")
```

Our goal is 100% SQLite compatibility. If something doesn't work, it's a bug we'll fix.

---

## Security Questions

### Q: Is HeliosDB-Lite secure?

**A:** Yes. Security measures include:

- Written in memory-safe Rust
- Protection against SQL injection (same as SQLite)
- Optional encryption at rest
- Secure authentication in server mode
- Regular security audits
- CVE tracking and rapid patches

**Best practices:**
```python
# Always use parameterized queries
cursor.execute('SELECT * FROM users WHERE id = ?', (user_id,))  # Safe

# Never string interpolation
# cursor.execute(f'SELECT * FROM users WHERE id = {user_id}')  # UNSAFE!

# Enable encryption for sensitive data
conn = sqlite3.connect('secure.db', encryption_key=os.getenv('DB_KEY'))

# Use authentication in server mode
server = sqlite3.start_server(
    'app.db',
    auth_method='password',
    require_ssl=True
)
```

---

### Q: How do I secure production deployments?

**A:** Production security checklist:

```python
# 1. Enable encryption
conn = sqlite3.connect(
    'production.db',
    encryption_key=os.getenv('DB_ENCRYPTION_KEY')
)

# 2. Restrict file permissions
# $ chmod 600 production.db

# 3. Use strong authentication (server mode)
server = sqlite3.start_server(
    'production.db',
    auth_method='certificate',
    ssl_cert='server.crt',
    ssl_key='server.key',
    allowed_ips=['10.0.0.0/8']
)

# 4. Audit logging: built-in audit logging is planned; record changes
#    to sensitive tables with triggers today

# 5. Set connection limits
conn.set_max_connections(100)

# 6. Regular backups
conn.schedule_backup(interval_hours=6, destination='/backups')
```

---

## Troubleshooting

### Q: I'm getting "module not found" errors

**A:** Check installation:

```bash
# Verify installation
pip show heliosdb-sqlite

# Reinstall if needed
pip install --force-reinstall ./sdks/python-sqlite   # from the new source distribution

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

If still failing, ensure you're using the correct virtual environment.

---

### Q: Performance is slower than expected

**A:** Performance tuning checklist:

```python
# 1. Enable query cache
conn = sqlite3.connect('app.db', enable_cache=True, cache_size_mb=100)

# 2. Use connection pooling
from heliosdb_sqlite import connection_pool
pool = connection_pool.create('app.db', pool_size=20)

# 3. Batch operations
cursor.batch_insert('users', ['name', 'email'], large_list)

# 4. Create appropriate indexes
cursor.execute('CREATE INDEX idx_user_email ON users(email)')

# 5. Analyze query plans
cursor.execute('EXPLAIN QUERY PLAN SELECT * FROM users WHERE email = ?')
print(cursor.fetchall())
```

See `HELIOSDB_SQLITE_TROUBLESHOOTING.md` for detailed guidance.

---

### Q: How do I get help?

**A:** Multiple support channels:

- **Documentation:** Complete docs in `/docs` directory
- **Email Support:** support@heliosdb.com (bug reports and feature requests)
- **Stack Overflow:** Tag questions with `heliosdb`
- **Community Discord:** Real-time help from users
- **Email Support:** support@heliosdb.com
- **Enterprise Support:** Priority support for enterprise customers

---

## Still have questions?

Check out:
- `HELIOSDB_SQLITE_DROP_IN_GUIDE.md` - Getting started guide
- `HELIOSDB_SQLITE_MIGRATION_PATTERNS.md` - Real-world examples
- `HELIOSDB_SQLITE_ADVANCED_FEATURES.md` - Advanced capabilities
- `HELIOSDB_SQLITE_TROUBLESHOOTING.md` - Problem solving
- `HELIOSDB_SQLITE_ARCHITECTURE_FOR_USERS.md` - How it works

Questions: support@heliosdb.com.