class

Ralph::Athena::Service

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

Clear the query cache.

Useful after bulk updates or when you need fresh data.

Source

database

Returns the configured Ralph database backend.

Example

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

Source

healthy?

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

Source

invalidate_cache(table : String) : Int32

Invalidate cached queries for a specific table.

Parameters

table: The table name to invalidate

Returns

The number of cache entries invalidated.

Source

pool_info

Get detailed pool information including configuration.

Example

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

Source

pool_stats

Get connection pool statistics.

Returns pool statistics if available, nil otherwise.

Example

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

Source

transaction

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

Source