class

Ralph::Database::SqliteBackend

Inherits Ralph::Database::Backend / Reference / Object

SQLite database backend implementation

Provides SQLite-specific database operations for Ralph ORM. Uses the crystal-sqlite3 shard for database connectivity.

Example

# File-based database
backend = Ralph::Database::SqliteBackend.new("sqlite3://./db/development.sqlite3")

# In-memory database (useful for testing)
backend = Ralph::Database::SqliteBackend.new("sqlite3::memory:")

# Enable WAL mode for better concurrency in production
backend = Ralph::Database::SqliteBackend.new("sqlite3://./db.sqlite3", wal_mode: true)

Connection String Format

SQLite connection strings follow the format: sqlite3://path/to/database.db

Special values:

sqlite3::memory: - Creates an in-memory database

Connection Pooling

Connection pooling is configured automatically from Ralph.settings:

Ralph.configure do |config|
  config.initial_pool_size = 5
  config.max_pool_size = 25
  config.max_idle_pool_size = 10
  config.checkout_timeout = 5.0
  config.retry_attempts = 3
  config.retry_delay = 0.2
end

Prepared Statement Caching

This backend supports prepared statement caching for improved query performance. Enable and configure via Ralph.settings:

Ralph.configure do |config|
  config.enable_prepared_statements = true
  config.prepared_statement_cache_size = 100
end

Concurrency

SQLite only supports one writer at a time. This backend provides two modes:

Default mode (wal_mode: false): Uses a mutex to serialize all write operations from this application. This prevents "database is locked" errors but limits write throughput to one operation at a time.
WAL mode (wal_mode: true): Enables SQLite's Write-Ahead Logging, which allows concurrent reads during writes. Writes are still serialized by SQLite but don't block readers. Recommended for production use with concurrent requests.

Note: WAL mode creates additional files (.sqlite3-wal, .sqlite3-shm) and is not supported for in-memory databases.

Constructors

new(connection_string : String, wal_mode : Bool = false, busy_timeout : Int32 = 5000, apply_pool_settings : Bool = true)

Creates a new SQLite backend with the given connection string

Parameters

connection_string: SQLite connection URI
wal_mode: Enable WAL mode for better concurrency (default: false)
busy_timeout: Milliseconds to wait for locks (default: 5000)
apply_pool_settings: Whether to apply pool settings from Ralph.settings (default: true)

Example

# Basic usage
backend = Ralph::Database::SqliteBackend.new("sqlite3://./db.sqlite3")

# Production usage with WAL mode
backend = Ralph::Database::SqliteBackend.new("sqlite3://./db.sqlite3", wal_mode: true)

# Skip pool settings (useful for CLI tools)
backend = Ralph::Database::SqliteBackend.new("sqlite3://./db.sqlite3", apply_pool_settings: false)

Source