class

Ralph::Settings

Inherits Reference / Object

Global settings for the ORM

Settings can be configured via Ralph.configure:

Ralph.configure do |config|
  config.database = Ralph::Database::SqliteBackend.new("sqlite3://./db.sqlite3")

  # Connection pool settings
  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

Constructors

Instance methods

apply_query_cache_settings

Apply query cache settings to the global cache

Call this after modifying cache settings to apply them.

Source
checkout_timeout

Seconds to wait for an available connection before raising PoolTimeout.

Should be set slightly higher than your slowest expected query. Recommended: 5.0 for development, 10.0-30.0 for production.

Source
checkout_timeout=(checkout_timeout : Float64)

Seconds to wait for an available connection before raising PoolTimeout.

Should be set slightly higher than your slowest expected query. Recommended: 5.0 for development, 10.0-30.0 for production.

Source
database

The primary database backend to use

Source
database=(database : Database::Backend | Nil)

The primary database backend to use

Source
database?

Check if a database is configured

Source
databases

Hash of named database backends Allows connecting to multiple databases

Source
databases=(databases : Hash(String, Database::Backend))

Hash of named database backends Allows connecting to multiple databases

Source
enable_prepared_statements

Whether to enable prepared statement caching.

When enabled, SQL queries are compiled once and reused with different parameters. This reduces database overhead for frequently executed queries.

Note: Enable only if your application executes the same queries repeatedly with different parameters.

Default: true

Source
enable_prepared_statements=(enable_prepared_statements : Bool)

Whether to enable prepared statement caching.

When enabled, SQL queries are compiled once and reused with different parameters. This reduces database overhead for frequently executed queries.

Note: Enable only if your application executes the same queries repeatedly with different parameters.

Default: true

Source
get_database(name : String) : Database::Backend

Get a named database backend

Parameters

  • name: The name of the database

Returns

The Database::Backend instance for the named database

Raises

If named database is not registered

Source
initial_pool_size

Initial number of connections created when the pool is established.

Higher values mean faster initial queries but more upfront resource usage.

Note for SQLite: Should be kept at 1 since SQLite only supports one writer at a time and Ralph's transaction management assumes single-connection.

Recommended: 1 for SQLite, 5-10 for PostgreSQL in production.

Source
initial_pool_size=(initial_pool_size : Int32)

Initial number of connections created when the pool is established.

Higher values mean faster initial queries but more upfront resource usage.

Note for SQLite: Should be kept at 1 since SQLite only supports one writer at a time and Ralph's transaction management assumes single-connection.

Recommended: 1 for SQLite, 5-10 for PostgreSQL in production.

Source
max_idle_pool_size

Maximum number of idle connections to keep in the pool.

When a connection is released and idle count exceeds this, it's closed. Higher values = faster checkout but more memory usage.

Note for SQLite: Should be kept at 1 to match initial_pool_size.

Recommended: 1 for SQLite, 10-25 for PostgreSQL in production.

Source
max_idle_pool_size=(max_idle_pool_size : Int32)

Maximum number of idle connections to keep in the pool.

When a connection is released and idle count exceeds this, it's closed. Higher values = faster checkout but more memory usage.

Note for SQLite: Should be kept at 1 to match initial_pool_size.

Recommended: 1 for SQLite, 10-25 for PostgreSQL in production.

Source
max_pool_size

Maximum number of connections the pool can hold (idle + in-use).

Set to 0 for unlimited connections (not recommended for production). When reached, new requests wait until a connection becomes available. Recommended: 10-25 for low traffic, 50-100 for high traffic.

Source
max_pool_size=(max_pool_size : Int32)

Maximum number of connections the pool can hold (idle + in-use).

Set to 0 for unlimited connections (not recommended for production). When reached, new requests wait until a connection becomes available. Recommended: 10-25 for low traffic, 50-100 for high traffic.

Source
pool_params

Build query string parameters for pool configuration.

Returns a hash that can be merged into connection URI query params.

Source
prepared_statement_cache_size

Maximum number of prepared statements to cache per database connection.

Higher values use more memory but can improve performance for applications with many distinct queries. When the cache is full, least recently used statements are evicted.

Recommended: 50-100 for most applications, 200+ for query-heavy apps. Default: 100

Source
prepared_statement_cache_size=(prepared_statement_cache_size : Int32)

Maximum number of prepared statements to cache per database connection.

Higher values use more memory but can improve performance for applications with many distinct queries. When the cache is full, least recently used statements are evicted.

Recommended: 50-100 for most applications, 200+ for query-heavy apps. Default: 100

Source
query_cache_auto_invalidate

Whether to automatically invalidate cache on model writes.

When enabled, saving, updating, or destroying a model will automatically invalidate cached queries that reference the model's table.

Default: true

Source
query_cache_auto_invalidate=(query_cache_auto_invalidate : Bool)

Whether to automatically invalidate cache on model writes.

When enabled, saving, updating, or destroying a model will automatically invalidate cached queries that reference the model's table.

Default: true

Source
query_cache_enabled

Whether to enable query result caching.

When enabled, queries marked with .cache will store their results and return cached data on subsequent executions with the same SQL/params.

Note for tests: This is typically disabled during testing to ensure predictable behavior. Set to false or use Ralph::Query.configure_cache(enabled: false).

Default: true (but consider disabling in test environment)

Source
query_cache_enabled=(query_cache_enabled : Bool)

Whether to enable query result caching.

When enabled, queries marked with .cache will store their results and return cached data on subsequent executions with the same SQL/params.

Note for tests: This is typically disabled during testing to ensure predictable behavior. Set to false or use Ralph::Query.configure_cache(enabled: false).

Default: true (but consider disabling in test environment)

Source
query_cache_max_size

Maximum number of query results to cache.

When the cache is full, least recently used entries are evicted. Higher values use more memory but can improve hit rates.

Recommended: 500-1000 for most applications. Default: 1000

Source
query_cache_max_size=(query_cache_max_size : Int32)

Maximum number of query results to cache.

When the cache is full, least recently used entries are evicted. Higher values use more memory but can improve hit rates.

Recommended: 500-1000 for most applications. Default: 1000

Source
query_cache_ttl

Default time-to-live for cached query results.

Cached results expire after this duration and will be re-fetched from the database. Shorter TTLs ensure fresher data but reduce cache effectiveness.

Recommended: 1-5 minutes for most applications. Default: 5 minutes

Source
query_cache_ttl=(query_cache_ttl : Time::Span)

Default time-to-live for cached query results.

Cached results expire after this duration and will be re-fetched from the database. Shorter TTLs ensure fresher data but reduce cache effectiveness.

Recommended: 1-5 minutes for most applications. Default: 5 minutes

Source
register_database(name : String, backend : Database::Backend)

Register a named database backend

Parameters

  • name: The name for this database connection
  • backend: The Database::Backend instance

Example

Ralph.configure do |config|
  config.database = Ralph::Database::SqliteBackend.new("sqlite3://./db.sqlite3")

  # Add analytics database
  analytics = Ralph::Database::PostgresBackend.new("postgres://localhost/analytics")
  config.register_database("analytics", analytics)
end
Source
retry_attempts

Number of times to retry establishing a connection on failure.

Useful for handling temporary network issues or database restarts. Set higher for production resilience. Recommended: 1-3 for development, 3-5 for production.

Source
retry_attempts=(retry_attempts : Int32)

Number of times to retry establishing a connection on failure.

Useful for handling temporary network issues or database restarts. Set higher for production resilience. Recommended: 1-3 for development, 3-5 for production.

Source
retry_delay

Seconds to wait between connection retry attempts.

Should be long enough for transient issues to resolve. Recommended: 0.2-0.5 for development, 0.5-2.0 for production.

Source
retry_delay=(retry_delay : Float64)

Seconds to wait between connection retry attempts.

Should be long enough for transient issues to resolve. Recommended: 0.2-0.5 for development, 0.5-2.0 for production.

Source
strict_resultset_validation

Whether to validate ResultSet columns match model columns during hydration.

When enabled, Ralph will check that the columns returned by a query match the columns expected by the model (same names, same count, same order). This catches schema drift early with a clear error message.

Performance impact: Minimal - one array comparison per query execution.

Recommendation: Enable in development/test, consider disabling in production if the small overhead is unacceptable (though it's very small).

Default: true

Source
strict_resultset_validation=(strict_resultset_validation : Bool)

Whether to validate ResultSet columns match model columns during hydration.

When enabled, Ralph will check that the columns returned by a query match the columns expected by the model (same names, same count, same order). This catches schema drift early with a clear error message.

Performance impact: Minimal - one array comparison per query execution.

Recommendation: Enable in development/test, consider disabling in production if the small overhead is unacceptable (though it's very small).

Default: true

Source
validate_pool_settings

Validate pool settings and return any warnings.

Returns an array of warning messages (empty if all settings are valid).

Source
validate_schema_on_boot

Whether to validate schema on first model access (boot-time validation).

When enabled, the first time a model class is accessed, Ralph will query the database to validate that the model's column definitions match the actual database schema.

This is more thorough than ResultSet validation as it catches:

  • Type mismatches (e.g., Float64 in model vs real in DB)
  • Nullability mismatches
  • Missing columns before any queries are run

Performance impact: One extra query per model class on first access.

Recommendation: Enable in development, disable in production.

Default: false (opt-in)

Source
validate_schema_on_boot=(validate_schema_on_boot : Bool)

Whether to validate schema on first model access (boot-time validation).

When enabled, the first time a model class is accessed, Ralph will query the database to validate that the model's column definitions match the actual database schema.

This is more thorough than ResultSet validation as it catches:

  • Type mismatches (e.g., Float64 in model vs real in DB)
  • Nullability mismatches
  • Missing columns before any queries are run

Performance impact: One extra query per model class on first access.

Recommendation: Enable in development, disable in production.

Default: false (opt-in)

Source