Module: Ronin::Database

Defined in:
lib/ronin/database/database.rb,
lib/ronin/database/migrations/1.0.0.rb,
lib/ronin/database/migrations/1.1.0.rb,
lib/ronin/database/migrations/graph.rb,
lib/ronin/database/migrations/migration.rb,
lib/ronin/database/migrations/migrations.rb,
lib/ronin/database/exceptions/invalid_config.rb,
lib/ronin/database/exceptions/unknown_repository.rb,
lib/ronin/database/migrations/exceptions/unknown_migration.rb,
lib/ronin/database/migrations/exceptions/duplicate_migration.rb

Overview

Manages the Database configuration and the defined repositories. Also provides a simple wrapper around DataMapper, for initializing, auto-upgrading and querying Database repositories.

Defined Under Namespace

Modules: Migrations Classes: InvalidConfig, UnknownRepository

Constant Summary collapse

CONFIG_FILE =

Database configuration file

File.join(Config::PATH,'database.yml')
DEFAULT_LOG_PATH =

Database log file

File.join(Config::PATH,'database.log')
DEFAULT_LOG_LEVEL =

Database log level

:info
DEFAULT_REPOSITORY =

Default database repository

{
  :adapter => 'sqlite3',
  :database => File.join(Config::PATH,'database.sqlite3')
}

Class Method Summary collapse

Class Method Details

.clear(name) { ... } ⇒ nil

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Clears the Database, by running destructive auto-migrations.

Parameters:

  • name (String, Symbol) —

    The name of the Database repository to clear.

Yields:

  • [] If a block is given, it will be called after the Database repository has been cleared.

Returns:

  • (nil)

Raises:

Since:

  • 1.0.0



276
277
278
279
280
281
282
283
284
285
286
287
 
# File 'lib/ronin/database/database.rb', line 276

def Database.clear(name)
  name = name.to_sym

  unless repository?(name)
    raise(UnknownRepository,"unknown database repository #{name}")
  end

  DataMapper.auto_migrate!(name)

  yield if block_given?
  return nil
end

.map { ... } ⇒ Array

Performs Database transactions in each of the Database repositories.

Yields:

  • [] The given block will be ran within the context of each Database repository.

Returns:

  • (Array) —

    The results from each database transaction.

Since:

  • 1.0.0



304
305
306
307
308
309
310
311
312
313
314
315
 
# File 'lib/ronin/database/database.rb', line 304

def Database.map
  results = []

  repositories.each_key do |name|
    DataMapper.repository(name) do
      result = yield
      results << result unless result.nil?
    end
  end

  return results
end

.repositories ⇒ Hash{Symbol => Hash}

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the Database repositories to use.

Returns:

  • (Hash{Symbol => Hash}) —

    The database repository names and URIs.

Raises:

  • (InvalidConfig) —

    The config file did not contain a YAML Hash.

Since:

  • 1.0.0



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
 
# File 'lib/ronin/database/database.rb', line 66

def Database.repositories
  if @repositories.empty?
    @repositories[:default] = DEFAULT_REPOSITORY

    if File.file?(CONFIG_FILE)
      config = YAML.load_file(CONFIG_FILE)

      unless config.kind_of?(Hash)
        raise(InvalidConfig,"#{CONFIG_FILE} must contain a YAML Hash of repositories")
      end

      config.each do |name,uri|
        @repositories[name.to_sym] = uri
      end
    end
  end

  return @repositories
end

.repository(name, &block) ⇒ DataMapper::Repository

Performs Database transactions within a given repository.

Parameters:

  • name (String, Symbol) —

    The name of the repository to access.

Returns:

  • (DataMapper::Repository) —

    The Database repository.

Raises:

Since:

  • 1.0.0



247
248
249
250
251
252
253
254
255
 
# File 'lib/ronin/database/database.rb', line 247

def Database.repository(name,&block)
  name = name.to_sym

  unless repository?(name)
    raise(UnknownRepository,"unknown database repository #{name}")
  end

  return DataMapper.repository(name,&block)
end

.repository?(name) ⇒ Boolean

Determines if the Database provides a specific repository.

Parameters:

  • name (String, Symbol) —

    Name of the repository.

Returns:

  • (Boolean) —

    Specifies if the Database provides the repository.

Since:

  • 1.0.0



99
100
101
 
# File 'lib/ronin/database/database.rb', line 99

def Database.repository?(name)
  repositories.has_key?(name.to_sym)
end

.save { ... } ⇒ true

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Saves the Database configuration to CONFIG_FILE.

Yields:

  • [] If a block is given, it will be called before the database configuration is saved.

Returns:

  • (true)

Since:

  • 1.0.0



116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/ronin/database/database.rb', line 116

def Database.save
  yield if block_given?

  File.open(CONFIG_FILE,'w') do |file|
    hash = {}
    
    repositories.each do |name,value|
      hash[name.to_sym] = value
    end

    YAML.dump(hash,file)
  end

  return true
end

.setup ⇒ Object

Sets up the Database.

See Also:



209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
 
# File 'lib/ronin/database/database.rb', line 209

def Database.setup
  # setup the database log
  unless @log
    if ($DEBUG || ENV['DEBUG'])
      setup_log(:stream => $stderr, :level => :debug)
    else
      setup_log
    end
  end

  # setup the database repositories
  repositories.each do |name,uri|
    DataMapper.setup(name,uri)
  end

  # finalize the Models
  DataMapper.finalize

  # apply any new migrations to the database
  upgrade!
end

.setup?(name = :default) ⇒ Boolean

Determines if a specific database repository is setup.

Parameters:

  • name (Symbol) (defaults to: :default) —

    The database repository name.

Returns:

  • (Boolean) —

    Specifies whether or not the Database is setup.



178
179
180
181
182
 
# File 'lib/ronin/database/database.rb', line 178

def Database.setup?(name=:default)
  repository = DataMapper.repository(name)

  return repository.class.adapters.has_key?(repository.name)
end

.setup_log(options = {}) ⇒ true

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Setup the Database log.

Parameters:

  • options (Hash) (defaults to: {}) —

    Additional options.

Options Hash (options):

  • :path (String) — default: DEFAULT_LOG_PATH —

    The path of the log file.

  • :stream (IO) —

    The stream to use for the log.

  • :level (Symbol) —

    The level of messages to log. May one of:

    • :fatal
    • :error
    • :warn
    • :info
    • :debug

Returns:

  • (true) —

    Specifies that the log has been setup.



158
159
160
161
162
163
164
165
 
# File 'lib/ronin/database/database.rb', line 158

def Database.setup_log(options={})
  path = options.fetch(:path,DEFAULT_LOG_PATH)
  stream = options.fetch(:stream,File.new(path,'w+'))
  level = options.fetch(:level,DEFAULT_LOG_LEVEL)

  @log = DataMapper::Logger.new(stream,level)
  return true
end

.upgrade! ⇒ Boolean

Upgrades the Database, by running migrations for a given ronin library, but only if the Database has been setup.

Returns:

  • (Boolean) —

    Specifies whether the Database was migrated or is currently not setup.



194
195
196
197
198
199
200
 
# File 'lib/ronin/database/database.rb', line 194

def Database.upgrade!
  if setup?
    Migrations.migrate_up!
  else
    false
  end
end