Litestack Documentation

Litestack is a unified solution for Ruby and Rails web applications that provides a database, caching, and job queueing system. It is built on top of SQLite, leveraging its file-based nature for easy setup and management without requiring separate server installations.

Key benefits include:

• Performance & Efficiency: Low memory footprint and optimized database access via SQLite, supplemented by asynchronous job queueing and in-memory caching.
• Simplicity: Designed as a turnkey solution to minimize infrastructure management.
• Modern Concurrency: Deep integration with state-of-the-art Ruby IO libraries like Async and Polyphony for improved concurrency and parallelism.
• Low Overhead: Reduces DevOps complexity by minimizing dependencies and configuration requirements.

Litestack (via the Ruby sqlite3 gem) does not release the Global VM Lock (GVL) while performing queries. This means a query in one thread will prevent other threads in the same Ruby process from resuming until the query returns.

Recommendation: For low-latency multi-threaded applications, use Fibers instead of Threads. Since execution is effectively serialized by the GVL during database operations, using Fibers avoids the unnecessary overhead of a multi-threaded environment.

Litestack follows the SQLite concurrency model: it allows multiple simultaneous readers, but only one writer at a time.

Warning: Long-running write operations (such as creating an index on a large table) will block all other write attempts until the operation completes. SQLite does not currently support concurrent index creation.

Litestack is designed for dead-simple integration with Ruby on Rails. You can transition to a fully functional database, caching, and job queueing solution using the following steps:

1. Install the gem.
2. Apply three lines of configuration changes to your Rails application.

To use Litestack in a Ruby application, add the gem to your Gemfile and run bundle install.

For Rails applications, you can run the generator to set up the full Litestack configuration automatically.

$ bundle add litestack

# For Rails applications
$ rails generate litestack:install

Litestack is a collection of lightweight, integrated components for Ruby applications. The library provides several specialized modules that can be used individually or together:

• LiteScheduler: For task scheduling.
• LiteSupport: Core support utilities.
• LiteMetric: For metrics and monitoring.
• LiteDb: A lightweight database interface.
• LiteCache: For caching mechanisms.
• LiteJob: For background job processing.
• LiteCable: For real-time communication (ActionCable compatible).
• LiteKd: For K-D tree based spatial indexing or similar structures.

To use Litecache as your Rails cache store, configure it in your environment files (e.g., config/environments/production.rb).

config.cache_store = :litecache, {path: './path/to/your/cache/file'}

The Litesupport::Liteconnection module provides a managed interface for SQLite connections, including connection pooling, transaction management, and automatic handling of process exiting and forking.

Key capabilities include:

• Connection Pooling: Uses create_pooled_connection to manage multiple connections.
• Transaction Management: The transaction method allows wrapping blocks of code in a database transaction. It supports :immediate mode by default.
• Automatic Cleanup: Automatically closes connections and prepared statements on process exit.
• Fork Safety: Uses Litescheduler::ForkListener to restart connections and background threads when a process forks.
• Environment-aware Configuration: Loads settings from a YAML file based on the current Litesupport.environment (e.g., production, development).

You can define multiple queues and their priorities in litejob.yml (or config/litejob.yml in Rails).

Queues require a name and a priority (1-10). Adding the token "spawn" tells Litejob to run every job in its own concurrency context (thread or fiber).

queues:
    - [default, 1]
    - [urgent, 5]
    - [critical, 10, "spawn"]