class ROM::SQL::Gateway

SQL gateway

@api public

Constants

CONNECTION_EXTENSIONS

Attributes

logger[R]

@!attribute [r] logger

@return [Object] configured gateway logger
options[R]

@!attribute [r] options

@return [Hash] Options used for connection

Public Class Methods

new(uri, options = EMPTY_HASH) click to toggle source

Initialize an SQL gateway

Gateways are typically initialized via ROM::Configuration object, gateway constructor arguments such as URI and options are passed directly to this constructor

@overload initialize(uri)

Connects to a database via URI

@example
  ROM.container(:sql, 'postgres://localhost/db_name')

@param [String,Symbol] uri connection URI

@overload initialize(uri, options)

Connects to a database via URI and options

@example
  ROM.container(:sql, 'postgres://localhost/db_name', extensions: %w[pg_enum])

@param [String,Symbol] uri connection URI

@param [Hash] options connection options

@option options [Array<Symbol>] :extensions
  A list of connection extensions supported by Sequel

@option options [String] :user Database username

@option options [String] :password Database password

@overload initialize(connection)

Creates a gateway from an existing database connection. This
works with Sequel connections exclusively.

@example
  ROM.container(:sql, Sequel.connect(:sqlite))

@param [Sequel::Database] connection a connection instance

@return [SQL::Gateway]

@see github.com/jeremyevans/sequel/blob/master/doc/opening_databases.rdoc Sequel connection docs

@api public

Calls superclass method ROM::SQL::Migration::new
# File lib/rom/sql/gateway.rb, line 81
def initialize(uri, options = EMPTY_HASH)
  @connection = connect(uri, options)
  load_extensions(Array(options[:extensions]))
  Notifications.trigger("configuration.gateway.connected", connection: @connection)

  @options = options

  super
end

Public Instance Methods

[](name) click to toggle source

Return dataset with the given name

This returns a raw Sequel database

@param [String, Symbol] name The dataset name

@return [Dataset]

@api public

# File lib/rom/sql/gateway.rb, line 107
def [](name)
  connection[name]
end
call(function, *args) click to toggle source

Call a SQL function

@example

gateway.(:upper, 'John Doe') # => "JOHN DOE"

@param [Symbol] function Function name @param [Array<Object>] args Function arguments

@return [Object]

@api public

# File lib/rom/sql/gateway.rb, line 195
def call(function, *args)
  connection[Sequel.function(function, *args)].first.values.first
end
create_table(*args, &block) click to toggle source

Create a table using the configured connection

@api public

# File lib/rom/sql/gateway.rb, line 155
def create_table(*args, &block)
  connection.create_table(*args, &block)
end
database_type() click to toggle source

Underlying database type

@return [Symbol]

@api public

# File lib/rom/sql/gateway.rb, line 180
def database_type
  @database_type ||= connection.database_type.to_sym
end
dataset(name) click to toggle source

Return dataset with the given name

@param [String] name a dataset name

@return [Dataset]

@api public

# File lib/rom/sql/gateway.rb, line 139
def dataset(name)
  connection[name]
end
dataset?(name) click to toggle source

Check if a dataset exists

@param [String] name dataset name

@api public

# File lib/rom/sql/gateway.rb, line 148
def dataset?(name)
  schema.include?(name)
end
disconnect() click to toggle source

Disconnect from the gateway's database

@api public

# File lib/rom/sql/gateway.rb, line 94
def disconnect
  connection.disconnect
end
drop_table(*args, &block) click to toggle source

Drops a table

@api public

# File lib/rom/sql/gateway.rb, line 162
def drop_table(*args, &block)
  connection.drop_table(*args, &block)
end
run(statement) click to toggle source

Execute a statement

@param [String] statement

@api public

# File lib/rom/sql/gateway.rb, line 204
def run(statement)
  connection.run(statement)
end
schema() click to toggle source

Returns a list of datasets inferred from table names

@return [Array] array with table names

@api public

# File lib/rom/sql/gateway.rb, line 171
def schema
  @schema ||= connection.tables
end
use_logger(logger) click to toggle source

Setup a logger

@example set a logger during configuration process

rom = ROM.container(:sql, 'sqlite::memory') do |config|
  config.gateways[:default].use_logger(Logger.new($stdout))
end

@example set logger after gateway has been established

rom = ROM.container(:sql, 'sqlite::memory')
rom.gateways[:default].use_logger(Logger.new($stdout))

@param [Object] logger

@see Sequel::Database#loggers

@api public

# File lib/rom/sql/gateway.rb, line 127
def use_logger(logger)
  @logger = logger
  connection.loggers << logger
end

Private Instance Methods

connect(uri, *args) click to toggle source

Connect to database or reuse established connection instance

@return [Database::Sequel] a connection instance

@api private

# File lib/rom/sql/gateway.rb, line 215
def connect(uri, *args)
  case uri
  when ::Sequel::Database
    uri
  when Hash
    ::Sequel.connect(uri, *args)
  else
    ::Sequel.connect(uri.to_s, *args)
  end
end
load_extensions(exts) click to toggle source

Load database-specific extensions

@api private

# File lib/rom/sql/gateway.rb, line 229
def load_extensions(exts)
  if ROM::SQL.available_extension?(database_type)
    ROM::SQL.load_extensions(database_type)
  end

  extensions = (CONNECTION_EXTENSIONS.fetch(database_type, EMPTY_ARRAY) + exts).uniq
  connection.extension(*extensions)

  # this will be default in Sequel 5.0.0 and since we don't rely
  # on dataset mutation it is safe to enable it already
  connection.extension(:freeze_datasets) unless RUBY_ENGINE == 'rbx'

  # for ROM::SQL::Relation#nullify
  connection.extension(:null_dataset)
end
transaction_runner(_) click to toggle source

@api private

# File lib/rom/sql/gateway.rb, line 246
def transaction_runner(_)
  ROM::SQL::Transaction.new(connection)
end