rapsqlite

Getting Started

  • Installation
    • Requirements
    • Installing from PyPI
    • Building from Source
    • Platform-Specific Notes
    • Verifying Installation
  • Quick Start
    • Basic Connection
    • Creating Tables
    • Inserting Data
    • Querying Data
    • Transactions
    • Using Cursors
    • Row Factories
    • Next Steps

API Reference

  • API Reference
    • Core Classes
      • Connection
        • Connection
        • Example
      • Cursor
        • Cursor
        • Example
      • Row
        • Row
        • Example
      • Exceptions
        • Error
        • Warning
        • DatabaseError
        • OperationalError
        • ProgrammingError
        • IntegrityError
        • Exception Hierarchy
        • Usage
    • Module Functions
      • ConnectionT
      • CursorT
      • connect()
      • PoolMetricsGauges
        • PoolMetricsGauges.rapsqlite_pool_size
        • PoolMetricsGauges.rapsqlite_pool_num_idle
        • PoolMetricsGauges.rapsqlite_pool_in_use
      • pool_metrics_gauges()
      • execute_iter()
      • paginate()
      • analyze_query_plan()
      • suggest_indexes()
      • in_clause_query()
      • rows_to_dicts()
      • timed_fetch_all()
      • transaction_retry()
      • transaction_with_timeout()
      • InterfaceError
      • DataError
      • InternalError
      • NotSupportedError

Guides

  • Advanced Usage Guide
    • Table of Contents
    • Connection Pooling
      • Understanding Connection Pools
      • When to Increase Pool Size
      • Pool Size Guidelines
      • Pool size is fixed at first use
      • Idle connection timeout
    • Monitoring
      • Pool metrics
      • Metrics export (Prometheus / custom)
      • Health checks
      • Connection health and recovery
      • Query logging and slow-query detection
      • Slow query threshold (Phase 3.5 — implemented)
      • Query timing (duration and callbacks)
    • Resource Cleanup and Connection Lifetime
      • Thread safety
    • Transaction Patterns
      • Explicit Transactions
      • Transaction Context Manager (Recommended)
      • Nested Transactions
      • Transaction retry (transient errors)
      • Transaction timeout
    • Error Handling Strategies
      • Handling Specific Errors
      • Retry Logic for Locked Database
      • Error Context
      • Callback Exception Handling
      • Streaming and large result sets
      • Query plan analysis
      • FTS, JSON, and UPSERT
      • Connection Lifecycle and Cleanup
      • Pool Exhaustion Troubleshooting
    • Performance Tuning
      • Use Parameterized Queries
      • IN clause expansion
      • Batch Operations
      • Connection Reuse
      • PRAGMA Optimization
      • Prepared Statement Caching
    • Common Anti-Patterns
      • ❌ Not Using Transactions for Multiple Operations
      • ❌ String Formatting Instead of Parameters
      • ❌ Fetching All Rows When Only One Needed
      • ❌ Not Handling Errors in Transactions
      • ❌ Creating Too Many Connections
      • ❌ Abandoning Connections Without Closing
      • ❌ Blocking the Event Loop
    • Best Practices
      • 1. Always Use Context Managers for Connections
      • 2. Use Transactions for Related Operations and Keep Them Short
      • 3. Handle Errors Appropriately
      • 4. Use Appropriate Fetch Methods
      • 5. Configure PRAGMAs for Your Workload
      • 6. Use Database Initialization Hooks
      • 7. Monitor Connection Pool Usage
      • 8. Use Schema Introspection
      • 9. Prefer Parameterized Queries and Choose the Right Fetch Pattern
    • Further Reading
  • Migration Guide: aiosqlite to rapsqlite
    • Quick Start
    • Why Migrate?
    • Migration Steps
      • 1. Install rapsqlite
      • 2. Update Imports
      • 3. Verify Compatibility
    • API Compatibility
      • Core API (100% Compatible)
      • Enhanced APIs
    • Code Examples
      • Basic Connection
      • Parameterized Queries
      • Transactions
    • Differences and Limitations
      • Migrating from aiosqlite: Common Patterns
      • Known Differences
      • register_adapter and register_converter
    • Advanced Features
      • Database Initialization Hooks
      • Schema Introspection
    • Troubleshooting
      • Import Errors
      • Performance Issues
      • Transaction Issues
    • Testing Your Migration
    • Example: Complete Migration
  • aiosqlite Compatibility Analysis
    • Test Execution
    • Known API Differences
      • 1. async with db.execute(...) Pattern
      • 2. Cursor as Async Context Manager / Async Iteration
      • 3. Connection Properties
      • 4. Row Format (lists vs tuples)
      • 5. Row Factory: aiosqlite.Row
      • 6. executescript() Method
      • 7. load_extension() Method
      • 8. Backup to sqlite3.Connection
      • 9. iterdump() Return Type
      • 10. init_hook parameter
    • True Async DBAPI (SQLAlchemy-style)
      • SQLAlchemy
      • Alembic with rapsqlite
      • FastAPI
      • Starlette
      • aiohttp
    • Compatibility Summary
    • Performance Characteristics
  • Performance Guide
    • Connection Pooling
      • Understanding Connection Pools
      • When to Increase Pool Size
      • Pool Size Guidelines
      • Single connection vs larger pool
    • Prepared Statement Caching
    • PRAGMA Optimization
    • Batch Operations
    • Connection Reuse
    • Use Appropriate Fetch Methods
    • Performance Monitoring
      • Query Timing
      • Connection Pool Metrics
    • Troubleshooting Performance Issues
      • Slow Queries
      • High Memory Usage
      • Database Locked Errors
    • Measuring performance and regression testing
    • Further Reading

Reference

  • Roadmap
    • Current Status
    • Goal
    • Future Enhancements
  • Type Conversion Strategy
    • Built-in type mapping
    • register_adapter and register_converter (supported)
    • Other options for custom types
rapsqlite
  • Search

© Copyright 2026, RAP Project.

Built with Sphinx using a theme provided by Read the Docs.