module

Ralph::Athena

Athena Framework integration - Auto Migration Listener

An optional event listener that runs pending migrations on the first HTTP request. This is useful for development environments where you want migrations to run automatically when you start the server.

Usage

To enable auto-migrations, require this file and configure Ralph::Athena with auto_migrate: true:

require "ralph/plugins/athena"

Ralph::Athena.configure(auto_migrate: true)

Production Considerations

Auto-migrations on first request is generally not recommended for production. In production, you should run migrations explicitly during deployment:

./ralph.cr db:migrate

Or use a separate migration process before starting your application.

Class methods

config

Global configuration instance

Source
config=(config : Configuration)

Global configuration instance

Source
configure(database_url : String | Nil = nil, auto_migrate : Bool = false, log_migrations : Bool = true, migrations_dir : String = "./db/migrations", models_dir : String = "./src/models", lazy_connect : Bool = false, &) : Nil

Configure Ralph for use with Athena Framework.

This method:

  1. Reads DATABASE_URL from environment (or uses provided URL)
  2. Auto-detects the appropriate backend (SQLite or PostgreSQL)
  3. Configures Ralph with sensible defaults
  4. Optionally runs pending migrations

Parameters

  • database_url: Optional database URL. If not provided, reads from DATABASE_URL env var.
  • auto_migrate: Whether to run pending migrations on startup. Default: false.
  • lazy_connect: If true, defer database connection until first use. Default: false. This is useful for CLI tools where commands like db:create need to run before the database exists.

Example

# Simple setup - reads DATABASE_URL from environment
Ralph::Athena.configure

# With auto-migrations
Ralph::Athena.configure(auto_migrate: true)

# With custom URL
Ralph::Athena.configure(database_url: "sqlite3://./dev.db")

# With block for additional Ralph settings
Ralph::Athena.configure(auto_migrate: true) do |config|
  config.max_pool_size = 50
  config.query_cache_ttl = 10.minutes
end

# For CLI tools - defer connection until needed
Ralph::Athena.configure(lazy_connect: true)

Backend Detection

The backend is auto-detected from the URL scheme:

  • sqlite3:// or sqlite:// → Requires ralph/backends/sqlite to be required
  • postgres:// or postgresql:// → Requires ralph/backends/postgres to be required

Make sure to require the appropriate backend BEFORE calling configure:

require "ralph/backends/sqlite"
require "ralph/plugins/athena"

Ralph::Athena.configure(database_url: "sqlite3://./dev.db")
Source
configure(database_url : String | Nil = nil, auto_migrate : Bool = false, log_migrations : Bool = true, migrations_dir : String = "./db/migrations", models_dir : String = "./src/models", lazy_connect : Bool = false) : Nil

Overload without block

Source
connected?

Check if the database is connected.

Source
ensure_connected

Ensure the database is connected.

Call this when you need the database and lazy_connect was used. If already connected, this is a no-op. If not connected, this will create the connection using the stored URL.

Raises

  • ConfigurationError if no database URL was configured
  • Database connection errors if the database is not available
Source
lazy_connect_pending

Track if lazy_connect was used and connection is still pending

Source
lazy_connect_pending=(lazy_connect_pending : Bool)

Track if lazy_connect was used and connection is still pending

Source
run_pending_migrations

Run any pending migrations.

This is called automatically if auto_migrate: true is passed to configure, but can also be called manually at any time.

Example

Ralph::Athena.run_pending_migrations
Source

Nested types