class

Ralph::Database::Backend

Instance methods

begin_transaction_sql

SQL to begin a transaction

clear_statement_cache

Clear the prepared statement cache

This invalidates all cached statements, forcing them to be reparsed on next use. Call this after schema changes or when you want to release memory.

Example

Ralph.database.clear_statement_cache

Source

Close the database connection

Source

closed?

Check if the connection is open

Source

commit_sql

SQL to commit a transaction

Source

dialect

Returns the dialect identifier for this backend Used by migrations and schema generation

Source

enable_statement_cache=(enabled : Bool)

Enable or disable prepared statement caching at runtime

Example

# Disable caching temporarily
Ralph.database.enable_statement_cache = false

# Run some one-off queries...

# Re-enable caching
Ralph.database.enable_statement_cache = true

Source

execute(query : String, args : Array(DB::Any) = [] of DB::Any)

Execute a query and return the raw result

Source

execute(query : String, args : Array(Query::DBValue))

Execute with DBValue args (converts UUIDs to strings)

Source

insert(query : String, args : Array(DB::Any) = [] of DB::Any) : Int64

Execute a query and return the last inserted ID

Implementation note: Different backends handle this differently:

SQLite: Uses SELECT last_insert_rowid() after INSERT
PostgreSQL: Uses INSERT ... RETURNING id

Source

insert(query : String, args : Array(Query::DBValue)) : Int64

Insert with DBValue args (converts UUIDs to strings)

Source

introspect_columns(table : String) : Array(Schema::DatabaseColumn)

Get column information for a specific table

Returns all columns with their types, nullability, defaults, etc.

Source

introspect_foreign_keys(table : String) : Array(Schema::DatabaseForeignKey)

Get foreign key constraints FROM a table (outgoing FKs)

These are FKs defined on this table that reference other tables. Used for inferring belongs_to associations.

Source

introspect_foreign_keys_referencing(table : String) : Array(Schema::DatabaseForeignKey)

Get foreign key constraints TO a table (incoming FKs)

These are FKs from OTHER tables that reference this table. Used for inferring has_many and has_one associations.

Source

introspect_indexes(table : String) : Array(Schema::DatabaseIndex)

Get index information for a specific table

Returns all indexes including primary key index.

Source

introspect_schema

Introspect the entire database schema

Returns a DatabaseSchema containing all tables with their columns, indexes, and foreign keys.

Source

introspect_table(name : String) : Schema::DatabaseTable

Introspect a single table completely

Returns a DatabaseTable with all columns, indexes, and foreign keys.

Source

introspect_tables(names : Array(String)) : Schema::DatabaseSchema

Introspect specific tables only

More efficient than full schema introspection when you only need a subset of tables.

Source

pool_healthy?

Check if the connection pool is healthy

Performs a simple query to verify database connectivity. Returns true if the database is reachable and responsive.

Example

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

Source

pool_stats

Get current connection pool statistics

Returns a PoolStats record with information about the pool state. Useful for monitoring and debugging connection issues.

Example

stats = backend.pool_stats
puts "Connections: #{stats.open_connections}/#{stats.max_connections}"

Source

query_all(query : String, args : Array(DB::Any) = [] of DB::Any) : DB::ResultSet

Query multiple rows

Source

query_all(query : String, args : Array(Query::DBValue)) : DB::ResultSet

Query all with DBValue args (converts UUIDs to strings)

Source

query_one(query : String, args : Array(DB::Any) = [] of DB::Any) : DB::ResultSet | Nil

Query a single row and map it to a result

Source

query_one(query : String, args : Array(Query::DBValue)) : DB::ResultSet | Nil

Query one with DBValue args (converts UUIDs to strings)

Source

raw_connection

Get the underlying DB::Database connection for advanced operations

Source

release_savepoint_sql(name : String) : String

SQL to release a savepoint

Source

rollback_sql

SQL to rollback a transaction

Source

rollback_to_savepoint_sql(name : String) : String

SQL to rollback to a savepoint

Source

savepoint_sql(name : String) : String

SQL to create a savepoint

Source

scalar(query : String, args : Array(DB::Any) = [] of DB::Any) : DB::Any | Nil

Execute a query and return a single scalar value (first column of first row)

Source

scalar(query : String, args : Array(Query::DBValue)) : DB::Any | Nil

Scalar with DBValue args (converts UUIDs to strings)

Source

statement_cache_enabled?

Check if prepared statement caching is enabled

Source

statement_cache_stats

Get statistics about the prepared statement cache

Returns a NamedTuple with cache size, max size, and enabled status.

Example

stats = Ralph.database.statement_cache_stats
puts "Cached: #{stats[:size]}/#{stats[:max_size]}"

Source

table_names

Get list of all user tables (excluding system tables)

Should exclude:

SQLite: sqlite_* tables, schema_migrations
PostgreSQL: pg_* tables, information_schema tables, schema_migrations

Returns table names in alphabetical order.

Source

transaction

Begin a transaction

Source