Service¶

class

Defined in src/ralph/plugins/athena/service.cr:55

A dependency-injectable service that provides access to Ralph's database functionality within Athena applications.

This service is automatically registered with Athena's DI container when you require "ralph/plugins/athena".

Injection¶

Inject this service into your controllers or other services:

class MyController < ATH::Controller
  def initialize(@ralph : Ralph::Athena::Service)
  end
end

Features¶

• Access to the configured database backend
• Transaction helpers with automatic rollback on exceptions
• Connection pool statistics
• Health check support

Instance Methods¶

#clear_cache¶

View source

Clear the query cache.

Useful after bulk updates or when you need fresh data.

#database¶

View source

Returns the configured Ralph database backend.

Example¶

@ralph.database.execute("SELECT 1")

#healthy?¶

View source

Check if the database connection pool is healthy.

Performs a simple health check query to verify database connectivity.

Example¶

@[ARTA::Get("/health")]
def health_check : NamedTuple(status: String, database: Bool)
  {status: "ok", database: @ralph.healthy?}
end

#invalidate_cache(table : String) : Int32¶

View source

Invalidate cached queries for a specific table.

Parameters¶

• table: The table name to invalidate

Returns¶

The number of cache entries invalidated.

#pool_info¶

View source

Get detailed pool information including configuration.

Example¶

@[ARTA::Get("/admin/pool-info")]
def pool_info
  @ralph.pool_info
end

#pool_stats¶

View source

Get connection pool statistics.

Returns pool statistics if available, nil otherwise.

Example¶

if stats = @ralph.pool_stats
  puts "Open connections: #{stats.open_connections}"
end

#transaction¶

View source

Execute a block within a database transaction.

If the block raises an exception, the transaction is rolled back. Otherwise, the transaction is committed when the block completes.

Example¶

@ralph.transaction do
  user = User.create!(name: "Alice")
  profile = Profile.create!(user_id: user.id)
end

Nested Transactions¶

Ralph supports nested transactions via savepoints:

@ralph.transaction do
  User.create!(name: "Alice")

  @ralph.transaction do
    # This creates a savepoint
    Post.create!(title: "Hello")
  end
end

Note¶

This method wraps Ralph::Model.transaction. You can use any model class's .transaction method directly if preferred:

User.transaction do
  # ...
end