Class: QueryKit::Connection

Inherits:
Object
  • Object
show all
Defined in:
lib/querykit/connection.rb

Overview

Connection class to manage database interactions.

Provides methods for executing queries, managing transactions, and optionally mapping results to model objects.

Examples:

Basic usage

db = Quby.connect(:sqlite, database: 'app.db')
query = db.query('users').where('age', '>', 18)
users = db.get(query)

With model mapping

users = db.get(query, User)  # Returns array of User objects

Transaction

db.transaction do
  db.execute_insert(db.insert('users').values(name: 'John'))
  db.execute_update(db.update('posts').set(status: 'published'))
end

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(adapter) ⇒ Connection

Initialize a new Connection with the given adapter.

Examples:

adapter = Quby::Adapters::SQLiteAdapter.new(database: 'app.db')
connection = Quby::Connection.new(adapter)

Parameters:

  • adapter (Adapter) —

    a database adapter instance (SQLite, PostgreSQL, or MySQL)



33
34
35
 
# File 'lib/querykit/connection.rb', line 33

def initialize(adapter)
  @adapter = adapter
end

Instance Attribute Details

#adapter ⇒ Adapter (readonly)

Returns the database adapter instance.

Returns:

  • (Adapter) —

    the database adapter instance



24
25
26
 
# File 'lib/querykit/connection.rb', line 24

def adapter
  @adapter
end

Instance Method Details

#delete(table = nil) ⇒ DeleteQuery

Create a new DELETE query builder.

Examples:

delete = db.delete('users').where('status', 'deleted')

Parameters:

  • table (String, nil) (defaults to: nil) —

    the table name

Returns:

  • (DeleteQuery) —

    a new delete query builder instance



99
100
101
 
# File 'lib/querykit/connection.rb', line 99

def delete(table = nil)
  DeleteQuery.new(table)
end

#execute_delete(query) ⇒ Object

Execute a delete query and return the number of affected rows



156
157
158
159
160
 
# File 'lib/querykit/connection.rb', line 156

def execute_delete(query)
  sql = query.to_sql
  @adapter.execute(sql, query.bindings)
  @adapter.affected_rows
end

#execute_insert(query) ⇒ Object

Execute an insert query and return the last insert ID



142
143
144
145
146
 
# File 'lib/querykit/connection.rb', line 142

def execute_insert(query)
  sql = query.to_sql
  @adapter.execute(sql, query.bindings)
  @adapter.last_insert_id
end

#execute_scalar(query) ⇒ Object

Execute a query and return a scalar value (first column of first row) Useful for aggregate queries like COUNT, SUM, AVG, etc.



164
165
166
167
168
 
# File 'lib/querykit/connection.rb', line 164

def execute_scalar(query)
  result = first(query)
  return nil if result.nil?
  result.is_a?(Hash) ? result.values.first : result
end

#execute_update(query) ⇒ Object

Execute an update query and return the number of affected rows



149
150
151
152
153
 
# File 'lib/querykit/connection.rb', line 149

def execute_update(query)
  sql = query.to_sql
  @adapter.execute(sql, query.bindings)
  @adapter.affected_rows
end

#first(query, model_class = nil) ⇒ Hash, ...

Execute a SELECT query and return the first result.

Examples:

user = db.first(db.query('users').where('email', '[email protected]'))

Parameters:

  • query (Query) —

    the query to execute

  • model_class (Class, nil) (defaults to: nil) —

    optional model class to map result to

Returns:

  • (Hash, Object, nil) —

    result hash, model instance, or nil if no results



132
133
134
135
136
137
138
139
 
# File 'lib/querykit/connection.rb', line 132

def first(query, model_class = nil)
  query.limit(1)
  results = @adapter.execute(query.to_sql, query.bindings)
  return nil if results.empty?
  
  row = results.first
  model_class ? map_to_model(row, model_class) : row
end

#from(table) ⇒ Query

Create a new query builder for the specified table (alias for query).

Examples:

query = db.from('users').where('status', 'active')

Parameters:

  • table (String) —

    the table name

Returns:

  • (Query) —

    a new query builder instance



55
56
57
 
# File 'lib/querykit/connection.rb', line 55

def from(table)
  Query.new(table)
end

#get(query, model_class = nil) ⇒ Array<Hash>, Array<Object>

Execute a SELECT query and return all results.

Examples:

Get raw hashes

users = db.get(db.query('users').where('age', '>', 18))

Map to model objects

users = db.get(db.query('users').where('age', '>', 18), User)

Parameters:

  • query (Query) —

    the query to execute

  • model_class (Class, nil) (defaults to: nil) —

    optional model class to map results to

Returns:

  • (Array<Hash>, Array<Object>) —

    array of result hashes or model instances



115
116
117
118
119
120
121
 
# File 'lib/querykit/connection.rb', line 115

def get(query, model_class = nil)
  sql = query.to_sql
  results = @adapter.execute(sql, query.bindings)
  return results unless model_class
  
  results.map { |row| map_to_model(row, model_class) }
end

#insert(table = nil) ⇒ InsertQuery

Create a new INSERT query builder.

Examples:

insert = db.insert('users').values(name: 'John', email: '[email protected]')

Parameters:

  • table (String, nil) (defaults to: nil) —

    the table name

Returns:

  • (InsertQuery) —

    a new insert query builder instance



77
78
79
 
# File 'lib/querykit/connection.rb', line 77

def insert(table = nil)
  InsertQuery.new(table)
end

#query(table = nil) ⇒ Query

Create a new query builder for the specified table.

Examples:

query = db.query('users').where('age', '>', 18)

Parameters:

  • table (String, nil) (defaults to: nil) —

    the table name (can be set later with from())

Returns:

  • (Query) —

    a new query builder instance



44
45
46
 
# File 'lib/querykit/connection.rb', line 44

def query(table = nil)
  Query.new(table)
end

#raw(sql, *bindings, model_class: nil) ⇒ Object

Raw SQL with optional model mapping



171
172
173
174
175
176
 
# File 'lib/querykit/connection.rb', line 171

def raw(sql, *bindings, model_class: nil)
  results = @adapter.execute(sql, bindings.flatten)
  return results unless model_class
  
  results.map { |row| map_to_model(row, model_class) }
end

#table(table) ⇒ Query

Create a new query builder for the specified table (alias for query).

Examples:

query = db.table('users').select('*')

Parameters:

  • table (String) —

    the table name

Returns:

  • (Query) —

    a new query builder instance



66
67
68
 
# File 'lib/querykit/connection.rb', line 66

def table(table)
  Query.new(table)
end

#transaction ⇒ Object

Transaction support



179
180
181
182
183
184
185
186
187
 
# File 'lib/querykit/connection.rb', line 179

def transaction
  @adapter.begin_transaction
  result = yield
  @adapter.commit
  result
rescue => e
  @adapter.rollback
  raise e
end

#update(table = nil) ⇒ UpdateQuery

Create a new UPDATE query builder.

Examples:

update = db.update('users').set(status: 'inactive').where('last_login', '<', '2020-01-01')

Parameters:

  • table (String, nil) (defaults to: nil) —

    the table name

Returns:

  • (UpdateQuery) —

    a new update query builder instance



88
89
90
 
# File 'lib/querykit/connection.rb', line 88

def update(table = nil)
  UpdateQuery.new(table)
end