module

Ralph

SQL Migration Runner

Discovers, tracks, and executes SQL migration files from the migrations directory. No recompilation required - migrations are read and executed at runtime.

Usage

migrator = Ralph::Migrations::Migrator.new(Ralph.database)

# Run all pending migrations
migrator.migrate

# Roll back the last migration
migrator.rollback

# Check status
migrator.status.each do |version, applied|
  puts "#{version}: #{applied ? "UP" : "DOWN"}"
end

Constants

VERSION = "1.0.0-beta.5"

Class methods

cache_enabled?

Check if query caching is enabled

Source
cache_stats

Get query cache statistics

Returns statistics about cache hits, misses, size, evictions, etc.

Example

stats = Ralph.cache_stats
puts "Hits: #{stats.hits}"
puts "Misses: #{stats.misses}"
puts "Hit rate: #{(stats.hit_rate * 100).round(1)}%"
puts "Size: #{stats.size}"
puts "Evictions: #{stats.evictions}"
Source
clear_cache

Clear the query cache

Removes all cached query results. This is useful when you need to ensure fresh data is loaded from the database.

Example

Ralph.clear_cache
Source
configure

Configure the ORM with a block

Source
database

Get the current database connection

If the Athena plugin is loaded with lazy_connect: true, this will automatically establish the connection on first access.

Source
disable_cache

Disable query caching (clears all cached entries)

Useful for testing or when you need to ensure fresh data.

Source
enable_cache

Enable query caching

Source
invalidate_table_cache(table : String) : Int32

Invalidate cache entries for a specific table

This is called automatically on model save/update/destroy when query_cache_auto_invalidate is enabled (default).

Parameters

  • table: The table name to invalidate

Returns

The number of cache entries that were invalidated.

Source
pool_healthy?

Check if the database connection pool is healthy

Performs a simple health check query to verify database connectivity. Returns true if the database is reachable and responsive, false otherwise.

Example

if Ralph.pool_healthy?
  puts "Database connection: OK"
else
  puts "Database connection: FAILED"
end

Health Checks

Use this method for:

  • Kubernetes/Docker health check endpoints
  • Load balancer health probes
  • Application startup verification
  • Periodic monitoring
Source
pool_info

Get detailed pool information including configuration

Returns a hash with current pool statistics and configuration settings. Useful for debugging and monitoring dashboards.

Example

info = Ralph.pool_info
puts "Pool status:"
info.each do |key, value|
  puts "  #{key}: #{value}"
end
Source
pool_stats

Get current connection pool statistics

Returns pool statistics if a database is configured, nil otherwise. Useful for monitoring connection pool health in production.

Example

if stats = Ralph.pool_stats
  puts "Open connections: #{stats.open_connections}"
  puts "Idle connections: #{stats.idle_connections}"
  puts "In-flight connections: #{stats.in_flight_connections}"
  puts "Max connections: #{stats.max_connections}"
end

Monitoring

Use this method to:

  • Monitor connection usage in production
  • Detect connection pool exhaustion
  • Tune pool configuration parameters
Source
settings
Source
settings=(value : Settings)
Source
validate_pool_config

Validate pool configuration and return any warnings

Returns an array of warning messages about potential pool configuration issues. Empty array means all settings are valid.

Example

warnings = Ralph.validate_pool_config
if warnings.empty?
  puts "Pool configuration: OK"
else
  warnings.each do |warning|
    puts "WARNING: #{warning}"
  end
end
Source

Nested types