HeliosDB-Lite SQLite Compatibility - Frequently Asked Questions¶
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:
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:
# 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 file an issue on GitHub. 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:
# 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: Absolutely! You can choose the mode that fits your use case:
# 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):
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 - Ultra-tight performance 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:
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 follows a dual-license model:
For most users (FREE): - Open source under Apache 2.0 license - Free for commercial use - No restrictions on deployment - 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 SQLite compatibility layer is always free and open source.
For specific licensing questions, see the LICENSE file or contact us.
Q: Is HeliosDB-Lite production-ready?¶
A: Yes! HeliosDB-Lite is production-ready:
Production credentials: - Written in Rust for safety and performance - Comprehensive test suite (>90% coverage) - Used in production by multiple companies - Active development and maintenance - Security audited - Battle-tested concurrency model
Production features: - ACID transactions - Crash recovery - Data integrity guarantees - Connection pooling - Monitoring and logging - Backup and restore - High availability options
Deployment:
# 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 one of HeliosDB-Lite's key advantages over SQLite:
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:
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:
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 popular ORMs:
SQLAlchemy:
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:
# 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:
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)
Option 2: Online backup (while database is running)
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
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
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:
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:
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 drop-in replacement: seconds!
# Step 1: Install (one time)
pip install heliosdb-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:
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:
- Report the issue: File a bug on GitHub with details
- Workaround: Use conditional import to fall back to SQLite temporarily
- Quick fixes: Critical compatibility issues are fixed within 24-48 hours
- Communication: We notify users of any breaking changes in advance
# 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:
# 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:
# 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. Enable audit logging
conn.enable_audit_log('/var/log/heliosdb/audit.log')
# 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:
# Verify installation
pip show heliosdb-sqlite
# Reinstall if needed
pip install --upgrade heliosdb-sqlite
# 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:
# 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
/docsdirectory - GitHub Issues: Bug reports and feature requests
- Stack Overflow: Tag questions with
heliosdb - Community Discord: Real-time help from users
- Email Support: support@heliosdb.io
- 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
Or reach out to the community - we're here to help!