Class | Amalgalite::Database
In: | lib/amalgalite/database.rb lib/amalgalite/database.rb
Parent: | Object

The encapsulation of a connection to an SQLite3 database.

Example opening and possibly creating a new database

      db = Amalgalite::Database.new( "mydb.db" )
      db.execute( "SELECT * FROM table" ) do |row|
        puts row
      end

      db.close

Open a database read only:

      db = Amalgalite::Database.new( "mydb.db", "r" )

Open an in-memory database:

      db = Amalgalite::MemoryDatabase.new

### Methods

aggregate aggregate autocommit? autocommit? busy_handler busy_handler clear_taps! clear_taps! close close commit commit deferred_transaction deferred_transaction define_aggregate define_aggregate define_busy_handler define_busy_handler define_function define_function define_progress_handler define_progress_handler encoding encoding escape escape exclusive_transaction exclusive_transaction execute execute execute_batch execute_batch first_row_from first_row_from first_value_from first_value_from function function immediate_transaction immediate_transaction import_csv_to_table import_csv_to_table in_transaction? in_transaction? interrupt! interrupt! last_insert_rowid last_insert_rowid new new open? open? pragma pragma prepare prepare profile_tap= profile_tap= progress_handler progress_handler quote quote release release reload_schema! reload_schema! remove_aggregate remove_aggregate remove_busy_handler remove_busy_handler remove_function remove_function remove_progress_handler remove_progress_handler replicate_to replicate_to rollback rollback rollback_to rollback_to row_changes row_changes savepoint savepoint schema schema total_changes total_changes trace_tap= trace_tap= transaction transaction type_map= type_map= utf16? utf16?

### Included Modules

Amalgalite::SQLite3::Constants Amalgalite::SQLite3::Constants

### Classes and Modules

Class Amalgalite::Database::AggregateError
Class Amalgalite::Database::BusyHandlerError
Class Amalgalite::Database::FunctionError
Class Amalgalite::Database::InvalidModeError
Class Amalgalite::Database::ProgressHandlerError
Class Amalgalite::Database::TransactionBehavior

### Constants

VALID_MODES | = | { "r" => Open::READONLY, "r+" => Open::READWRITE, "w+" => Open::READWRITE | Open::CREATE, } |  | list of valid modes for opening an Amalgalite::Database
VALID_MODES | = | { "r" => Open::READONLY, "r+" => Open::READWRITE, "w+" => Open::READWRITE | Open::CREATE, } |  | list of valid modes for opening an Amalgalite::Database

### Attributes

aggregates | [R] | A list of the user defined aggregates
aggregates | [R] | A list of the user defined aggregates
api | [R] | the low level Amalgalite::SQLite3::Database
api | [R] | the low level Amalgalite::SQLite3::Database
functions | [R] | A list of the user defined functions
functions | [R] | A list of the user defined functions
profile_tap | [R] | An object that follows the ProfileTap protocol, or nil. By default this is nil
profile_tap | [R] | An object that follows the ProfileTap protocol, or nil. By default this is nil
trace_tap | [R] | An object that follows the TraceTap protocol, or nil. By default this is nil
trace_tap | [R] | An object that follows the TraceTap protocol, or nil. By default this is nil
type_map | [R] | An object that follows the TypeMap protocol, or nil. By default this is an instances of TypeMaps::DefaultMap
type_map | [R] | An object that follows the TypeMap protocol, or nil. By default this is an instances of TypeMaps::DefaultMap

### Public Class methods

Amalgalite::Database.new( filename, "w+", opts = {}) → Database

Create a new Amalgalite database

The first parameter is the filename of the sqlite database. Specifying ":memory:" as the filename creates an in-memory database.

The second parameter is the standard file modes of how to open a file.

The modes are:

- r - Read-only
- r+ - Read/write, an error is thrown if the database does not already exist
- w+ - Read/write, create a new database if it doesn‘t exist

`w+` is the default as this is how most databases will want to be utilized.

opts is a hash of available options for the database:

- :utf16 option to set the database to a utf16 encoding if creating a database.

By default, databases are created with an encoding of utf8. Setting this to true and opening an already existing database has no effect.

NOTE Currently :utf16 is not supported by Amalgalite, it is planned for a later release

Amalgalite::Database.new( filename, "w+", opts = {}) → Database

Create a new Amalgalite database

The first parameter is the filename of the sqlite database. Specifying ":memory:" as the filename creates an in-memory database.

The second parameter is the standard file modes of how to open a file.

The modes are:

- r - Read-only
- r+ - Read/write, an error is thrown if the database does not already exist
- w+ - Read/write, create a new database if it doesn‘t exist

`w+` is the default as this is how most databases will want to be utilized.

opts is a hash of available options for the database:

- :utf16 option to set the database to a utf16 encoding if creating a database.

By default, databases are created with an encoding of utf8. Setting this to true and opening an already existing database has no effect.

NOTE Currently :utf16 is not supported by Amalgalite, it is planned for a later release

### Public Instance methods

aggregate( name, klass )

Alias for define_aggregate

aggregate( name, klass )

Alias for define_aggregate

autocommit?()

Is the database in autocommit mode or not

autocommit?()

Is the database in autocommit mode or not

busy_handler( callable = nil, &block )

Alias for define_busy_handler

busy_handler( callable = nil, &block )

Alias for define_busy_handler

clear_taps!()

clear all the current taps

clear_taps!()

clear all the current taps

close()

Close the database

close()

Close the database

commit()

Commit a transaction

commit()

Commit a transaction

deferred_transaction( mode = TransactionBehavior::DEFERRED, &block )

Alias for transaction

deferred_transaction( mode = TransactionBehavior::DEFERRED, &block )

Alias for transaction

db.define_aggregate( 'name', MyAggregateClass )

Define an SQL aggregate function, these are functions like max(), min(), avg(), etc. SQL functions that would be used when a GROUP BY clause is in effect. See also ::Amalgalite::Aggregate.

A new instance of MyAggregateClass is created for each instance that the SQL aggregate is mentioned in SQL.

db.define_aggregate( 'name', MyAggregateClass )

Define an SQL aggregate function, these are functions like max(), min(), avg(), etc. SQL functions that would be used when a GROUP BY clause is in effect. See also ::Amalgalite::Aggregate.

A new instance of MyAggregateClass is created for each instance that the SQL aggregate is mentioned in SQL.

db.busy_handler( callable )
db.define_busy_handler do |count|
end
db.busy_handler( Amalgalite::BusyTimeout.new( 30 ) )

Register a busy handler for this database connection, the handler MUST follow the `to_proc` protocol indicating that is will +respond_to?(:call)+. This is intrinsic to lambdas and blocks so those will work automatically.

This exposes the sqlite busy handler api to ruby.

- sqlite.org/c3ref/busy_handler.html

The busy handler‘s _call(N)_ method may be invoked whenever an attempt is made to open a database table that another thread or process has locked. `N` will be the number of times the _call(N)_ method has been invoked during this locking event.

The handler may or maynot be called based upon what SQLite determins.

If the handler returns nil or false then no more busy handler calls will be made in this lock event and you are probably going to see an SQLite::Error in your immediately future in another process or in another piece of code.

If the handler returns non-nil or non-false then another attempt will be made to obtain the lock, lather, rinse, repeat.

If an Exception happens in a busy handler, it will be the same as if the busy handler had returned nil or false. The exception itself will not be propogated further.

db.busy_handler( callable )
db.define_busy_handler do |count|
end
db.busy_handler( Amalgalite::BusyTimeout.new( 30 ) )

Register a busy handler for this database connection, the handler MUST follow the `to_proc` protocol indicating that is will +respond_to?(:call)+. This is intrinsic to lambdas and blocks so those will work automatically.

This exposes the sqlite busy handler api to ruby.

- sqlite.org/c3ref/busy_handler.html

The busy handler‘s _call(N)_ method may be invoked whenever an attempt is made to open a database table that another thread or process has locked. `N` will be the number of times the _call(N)_ method has been invoked during this locking event.

The handler may or maynot be called based upon what SQLite determins.

If the handler returns nil or false then no more busy handler calls will be made in this lock event and you are probably going to see an SQLite::Error in your immediately future in another process or in another piece of code.

If the handler returns non-nil or non-false then another attempt will be made to obtain the lock, lather, rinse, repeat.

If an Exception happens in a busy handler, it will be the same as if the busy handler had returned nil or false. The exception itself will not be propogated further.

db.function( "name", MyDBFunction.new )
db.function( "my_func", callable )
db.function( "my_func" ) do |x,y|
....
return result
end

register a callback to be exposed as an SQL function. There are multiple ways to register this function:

1. db.function( "name" ) { |a| … }
   - pass `function` a name and a block.
   - The SQL function name taking arity parameters will be registered, where arity is the arity of the block.
   - The return value of the block is the return value of the registred SQL function
2. db.function( "name", callable )
   - pass `function` a name and something that `responds_to?( :to_proc )`
   - The SQL function name is registered taking arity parameters is registered where arity is the arity of +callable.to_proc.call+
   - The return value of the +callable.to_proc.call+ is the return value of the SQL function

See also ::Amalgalite::Function

db.function( "name", MyDBFunction.new )
db.function( "my_func", callable )
db.function( "my_func" ) do |x,y|
....
return result
end

register a callback to be exposed as an SQL function. There are multiple ways to register this function:

1. db.function( "name" ) { |a| … }
   - pass `function` a name and a block.
   - The SQL function name taking arity parameters will be registered, where arity is the arity of the block.
   - The return value of the block is the return value of the registred SQL function
2. db.function( "name", callable )
   - pass `function` a name and something that `responds_to?( :to_proc )`
   - The SQL function name is registered taking arity parameters is registered where arity is the arity of +callable.to_proc.call+
   - The return value of the +callable.to_proc.call+ is the return value of the SQL function

See also ::Amalgalite::Function

db.progress_handler( 50, MyProgressHandler.new )
db.progress_handler( 25 , callable )
db.progress_handler do
....
return result
end

Register a progress handler for this database connection, the handler MUST follow the `to_proc` protocol indicating that is will +respond_to?(:call)+. This is intrinsic to lambdas and blocks so those will work automatically.

This exposes the sqlite progress handler api to ruby.

- sqlite.org/c3ref/progress_handler.html

The progress handler‘s _call()_ method may be invoked ever N SQLite op codes. If the progress handler returns anything that can evaluate to `true` then current running sqlite statement is terminated at the earliest oppportunity.

You can use this to be notified that a thread is still processingn a request.

db.progress_handler( 50, MyProgressHandler.new )
db.progress_handler( 25 , callable )
db.progress_handler do
....
return result
end

Register a progress handler for this database connection, the handler MUST follow the `to_proc` protocol indicating that is will +respond_to?(:call)+. This is intrinsic to lambdas and blocks so those will work automatically.

This exposes the sqlite progress handler api to ruby.

- sqlite.org/c3ref/progress_handler.html

The progress handler‘s _call()_ method may be invoked ever N SQLite op codes. If the progress handler returns anything that can evaluate to `true` then current running sqlite statement is terminated at the earliest oppportunity.

You can use this to be notified that a thread is still processingn a request.

encoding()

return the encoding of the database

encoding()

return the encoding of the database

escape( s )

SQL escape the input string

escape( s )

SQL escape the input string

exclusive_transaction( &block )

helper for an exclusive transaction

exclusive_transaction( &block )

helper for an exclusive transaction

execute( sql, *bind_params ) {|row| ...}

Execute a single SQL statement.

If called with a block and there are result rows, then they are iteratively yielded to the block.

If no block is passed, then all the results are returned as an arrayfields instance. This is an array with field name access.

If no block is passed, and there are no results, then an empty Array is returned.

On an error an exception is thrown

This is just a wrapper around the preparation of an Amalgalite Statement and iterating over the results.

execute( sql, *bind_params ) {|row| ...}

Execute a single SQL statement.

If called with a block and there are result rows, then they are iteratively yielded to the block.

If no block is passed, then all the results are returned as an arrayfields instance. This is an array with field name access.

If no block is passed, and there are no results, then an empty Array is returned.

On an error an exception is thrown

This is just a wrapper around the preparation of an Amalgalite Statement and iterating over the results.

execute_batch( sql, *bind_params)

Execute a batch of statements, this will execute all the sql in the given string until no more sql can be found in the string. It will bind the same parameters to each statement. All data that would be returned from all of the statements is thrown away.

All statements to be executed in the batch must be terminated with a ’;’ Returns the number of statements executed

execute_batch( sql, *bind_params)

Execute a batch of statements, this will execute all the sql in the given string until no more sql can be found in the string. It will bind the same parameters to each statement. All data that would be returned from all of the statements is thrown away.

All statements to be executed in the batch must be terminated with a ’;’ Returns the number of statements executed

first_row_from( sql, *bind_params )

Execute a sql statment, and only return the first row of results. This is a shorthand method when you only want a single row of results from a query. If there is no result, then return an empty array

It is in all other was, exactly like execute()

first_row_from( sql, *bind_params )

Execute a sql statment, and only return the first row of results. This is a shorthand method when you only want a single row of results from a query. If there is no result, then return an empty array

It is in all other was, exactly like execute()

first_value_from( sql, *bind_params )

Execute an sql statement, and return only the first column of the first row. If there is no result, return nil.

It is in all other ways, exactly like first_row_from()

first_value_from( sql, *bind_params )

Execute an sql statement, and return only the first column of the first row. If there is no result, return nil.

It is in all other ways, exactly like first_row_from()

function( name, callable = nil, &block )

Alias for define_function

function( name, callable = nil, &block )

Alias for define_function

immediate_transaction( &block )

helper for an immediate transaction

immediate_transaction( &block )

helper for an immediate transaction

db.import_csv_to_table( "/some/location/data.csv", "my_table" )
db.import_csv_to_table( "countries.csv", "countries", :col_sep => "|", :headers => %w[ name two_letter id ] )

import_csv_to_table() takes 2 required arguments, and a hash of options. The first argument is the path to a CSV, the second is the table in which to load the data. The options has is a subset of those used by CSV

- :col_sep - the string placed between each field. Default is ","
- :row_sep - the String appended to the end of each row. Default is :auto
- :quote_char - The character used to quote fields. Default ’"’
- :headers - set to true or :first_row if there are headers in this CSV. Default is false.

                 This may also be an Array.  If that is the case then the
                 array is used as the fields in the CSV and the fields in the
                 table in which to insert.  If this is set to an Array, it is
                 assumed that all rows in the csv will be inserted.

db.import_csv_to_table( "/some/location/data.csv", "my_table" )
db.import_csv_to_table( "countries.csv", "countries", :col_sep => "|", :headers => %w[ name two_letter id ] )

import_csv_to_table() takes 2 required arguments, and a hash of options. The first argument is the path to a CSV, the second is the table in which to load the data. The options has is a subset of those used by CSV

- :col_sep - the string placed between each field. Default is ","
- :row_sep - the String appended to the end of each row. Default is :auto
- :quote_char - The character used to quote fields. Default ’"’
- :headers - set to true or :first_row if there are headers in this CSV. Default is false.

                 This may also be an Array.  If that is the case then the
                 array is used as the fields in the CSV and the fields in the
                 table in which to insert.  If this is set to an Array, it is
                 assumed that all rows in the csv will be inserted.

in_transaction?()

return whether or not the database is currently in a transaction or not

in_transaction?()

return whether or not the database is currently in a transaction or not

db.interrupt!

Cause another thread with a handle on this database to be interrupted and return at the earliest opportunity as interrupted. It is not safe to call this method if the database might be closed before interrupt! returns.

db.interrupt!

Cause another thread with a handle on this database to be interrupted and return at the earliest opportunity as interrupted. It is not safe to call this method if the database might be closed before interrupt! returns.

last_insert_rowid()

Return the rowid of the last inserted row

last_insert_rowid()

Return the rowid of the last inserted row

open?()

Is the database open or not

open?()

Is the database open or not

pragma( cmd, &block )

Run a pragma command against the database

Returns the result set of the pragma

pragma( cmd, &block )

Run a pragma command against the database

Returns the result set of the pragma

prepare( sql ) {|stmt| ...}

Prepare a statement for execution

If called with a block, the statement is yielded to the block and the statement is closed when the block is done.

     db.prepare( "SELECT * FROM table WHERE c = ?" ) do |stmt|
       list_of_c_values.each do |c|
         stmt.execute( c ) do |row|
           puts "when c = #{c} : #{row.inspect}"
         end
       end
     end

Or without a block:

      stmt = db.prepare( "INSERT INTO t1(x, y, z) VALUES ( :

prepare( sql ) {|stmt| ...}

Prepare a statement for execution

If called with a block, the statement is yielded to the block and the statement is closed when the block is done.

     db.prepare( "SELECT * FROM table WHERE c = ?" ) do |stmt|
       list_of_c_values.each do |c|
         stmt.execute( c ) do |row|
           puts "when c = #{c} : #{row.inspect}"
         end
       end
     end

Or without a block:

      stmt = db.prepare( "INSERT INTO t1(x, y, z) VALUES ( :

db.profile_tap = obj

Register a profile tap.

Registering a profile tap means that the `obj` registered will have its `profile` method called with an Integer and a String parameter every time a profile event happens. The Integer is the number of nanoseconds it took for the String (SQL) to execute in wall-clock time.

That is, every time a profile event happens in SQLite the following is invoked:

      obj.profile( str, int )

For instance:

      db.profile_tap = Amalgalite::ProfileTap.new( logger, 'debug' )

This will register an instance of ProfileTap, which wraps an logger object. On each `profile` event the ProfileTap#profile method will be called which in turn will call <tt>logger.debug<tt> with a formatted string containing the String and Integer from the profile event.

      db.profile_tap = nil

This will unregister the profile tap

db.profile_tap = obj

Register a profile tap.

Registering a profile tap means that the `obj` registered will have its `profile` method called with an Integer and a String parameter every time a profile event happens. The Integer is the number of nanoseconds it took for the String (SQL) to execute in wall-clock time.

That is, every time a profile event happens in SQLite the following is invoked:

      obj.profile( str, int )

For instance:

      db.profile_tap = Amalgalite::ProfileTap.new( logger, 'debug' )

This will register an instance of ProfileTap, which wraps an logger object. On each `profile` event the ProfileTap#profile method will be called which in turn will call <tt>logger.debug<tt> with a formatted string containing the String and Integer from the profile event.

      db.profile_tap = nil

This will unregister the profile tap

progress_handler( op_code_count = 25, callable = nil, &block )

Alias for define_progress_handler

progress_handler( op_code_count = 25, callable = nil, &block )

Alias for define_progress_handler

quote( s )

Surround the give string with single-quotes and escape any single-quotes in the string

quote( s )

Surround the give string with single-quotes and escape any single-quotes in the string

db.release( 'mypoint' )

Release a savepoint. This is similar to a commit but only for savepoints. All savepoints up the savepoint stack and include the name savepoint being released are ‘committed’ to the transaction. There are several ways of thinking about release and they are all detailed in the sqlite documentation: sqlite.org/lang_savepoint.html

db.release( 'mypoint' )

Release a savepoint. This is similar to a commit but only for savepoints. All savepoints up the savepoint stack and include the name savepoint being released are ‘committed’ to the transaction. There are several ways of thinking about release and they are all detailed in the sqlite documentation: sqlite.org/lang_savepoint.html

db.reload_schema! → Schema

By default once the schema is obtained, it is cached. This is here to force the schema to be reloaded.

db.reload_schema! → Schema

By default once the schema is obtained, it is cached. This is here to force the schema to be reloaded.

db.remove_aggregate( 'name', MyAggregateClass )
db.remove_aggregate( 'name' )

Remove an aggregate from use in the database. Since the same aggregate may be refistered more than once with different arity, you may specify the arity, or the aggregate class, or nil. If nil is used for the arity then Amalgalite does its best to remove all aggregates of the given name

db.remove_aggregate( 'name', MyAggregateClass )
db.remove_aggregate( 'name' )

Remove an aggregate from use in the database. Since the same aggregate may be refistered more than once with different arity, you may specify the arity, or the aggregate class, or nil. If nil is used for the arity then Amalgalite does its best to remove all aggregates of the given name

db.remove_busy_handler

Remove the busy handler for this database connection.

db.remove_busy_handler

Remove the busy handler for this database connection.

db.remove_function( 'name', MyScalerFunctor.new )
db.remove_function( 'name', callable )
db.remove_function( 'name', arity )
db.remove_function( 'name' )

Remove a function from use in the database. Since the same function may be registered more than once with different arity, you may specify the arity, or the function object, or nil. If nil is used for the arity, then Amalgalite does its best to remove all functions of given name.

db.remove_function( 'name', MyScalerFunctor.new )
db.remove_function( 'name', callable )
db.remove_function( 'name', arity )
db.remove_function( 'name' )

Remove a function from use in the database. Since the same function may be registered more than once with different arity, you may specify the arity, or the function object, or nil. If nil is used for the arity, then Amalgalite does its best to remove all functions of given name.

db.remove_progress_handler

Remove the progress handler for this database connection.

db.remove_progress_handler

Remove the progress handler for this database connection.

db.replicate_to( ":memory:" ) → new_db
db.replicate_to( "/some/location/my.db" ) → new_db
db.replicate_to( Amalgalite::Database.new( "/my/backup.db" ) ) → new_db

replicate_to() takes a single argument, either a String or an Amalgalite::Database. It returns the replicated database object. If given a String, it will truncate that database if it already exists.

Replicate the current database to another location, this can be used for a number of purposes:

- load an sqlite database from disk into memory
- snaphost an in memory db and save it to disk
- backup on sqlite database to another location

db.replicate_to( ":memory:" ) → new_db
db.replicate_to( "/some/location/my.db" ) → new_db
db.replicate_to( Amalgalite::Database.new( "/my/backup.db" ) ) → new_db

replicate_to() takes a single argument, either a String or an Amalgalite::Database. It returns the replicated database object. If given a String, it will truncate that database if it already exists.

Replicate the current database to another location, this can be used for a number of purposes:

- load an sqlite database from disk into memory
- snaphost an in memory db and save it to disk
- backup on sqlite database to another location

rollback()

Rollback a transaction

rollback()

Rollback a transaction

db.rollback_to( point_name )

Rollback to a savepoint. The transaction is not cancelled, the transaction is restarted.

db.rollback_to( point_name )

Rollback to a savepoint. The transaction is not cancelled, the transaction is restarted.

row_changes()

return how many rows changed in the last insert, update or delete statement.

row_changes()

return how many rows changed in the last insert, update or delete statement.

db.savepoint( 'mypoint' ) → db
db.savepoint( 'mypoint' ) do |db_in_savepoint|
...
end

Much of the following documentation is para-phrased from sqlite.org/lang_savepoint.html

Savepoints are a method of creating transactions, similar to transaction except that they may be nested.

- Every savepoint must have a name, `to_s` is called on the method argument
- A savepoint does not need to be initialized inside a transaction. If it is not inside a transaction it behaves exactly as if a DEFERRED transaction had been started.
- If a block is passed to saveponit then when the block exists, it is guaranteed that either a ‘RELEASE’ or ‘ROLLBACK TO name’ has been executed.
- If any exception happens during the savepoint transaction, then a ‘ROLLOBACK TO’ is issued when the block closes.
- If no exception happens during the transaction then a ‘RELEASE name’ is issued upon leaving the block

If no block is passed in then you are on your own.

db.savepoint( 'mypoint' ) → db
db.savepoint( 'mypoint' ) do |db_in_savepoint|
...
end

Much of the following documentation is para-phrased from sqlite.org/lang_savepoint.html

Savepoints are a method of creating transactions, similar to transaction except that they may be nested.

- Every savepoint must have a name, `to_s` is called on the method argument
- A savepoint does not need to be initialized inside a transaction. If it is not inside a transaction it behaves exactly as if a DEFERRED transaction had been started.
- If a block is passed to saveponit then when the block exists, it is guaranteed that either a ‘RELEASE’ or ‘ROLLBACK TO name’ has been executed.
- If any exception happens during the savepoint transaction, then a ‘ROLLOBACK TO’ is issued when the block closes.
- If no exception happens during the transaction then a ‘RELEASE name’ is issued upon leaving the block

If no block is passed in then you are on your own.

db.schema( dbname = "main" ) → Schema

Returns a Schema object containing the table and column structure of the database.

db.schema( dbname = "main" ) → Schema

Returns a Schema object containing the table and column structure of the database.

total_changes()

return how many rows have changed since this connection to the database was opened.

total_changes()

return how many rows have changed since this connection to the database was opened.

db.trace_tap = obj

Register a trace tap.

Registering a trace tap measn that the `obj` registered will have its `trace` method called with a string parameter at various times. If the object doesn‘t respond to the `trace` method then `write` will be called.

For instance:

      db.trace_tap = Amalgalite::TraceTap.new( logger, 'debug' )

This will register an instance of TraceTap, which wraps an logger object. On each `trace` event the TraceTap#trace method will be called, which in turn will call the `logger.debug` method

      db.trace_tap = $stderr

This will register the `$stderr` io stream as a trace tap. Every time a `trace` event happens then `$stderr.write( msg )` will be called.

      db.trace_tap = nil

This will unregistere the trace tap

db.trace_tap = obj

Register a trace tap.

Registering a trace tap measn that the `obj` registered will have its `trace` method called with a string parameter at various times. If the object doesn‘t respond to the `trace` method then `write` will be called.

For instance:

      db.trace_tap = Amalgalite::TraceTap.new( logger, 'debug' )

This will register an instance of TraceTap, which wraps an logger object. On each `trace` event the TraceTap#trace method will be called, which in turn will call the `logger.debug` method

      db.trace_tap = $stderr

This will register the `$stderr` io stream as a trace tap. Every time a `trace` event happens then `$stderr.write( msg )` will be called.

      db.trace_tap = nil

This will unregistere the trace tap

transaction( mode = TransactionBehavior::DEFERRED ) {|self )| ...}

Begin a transaction. The valid transaction types are:

DEFERRED: | no read or write locks are created until the first statement is executed that requries a read or a write
IMMEDIATE: | a readlock is obtained immediately so that no other process can write to the database
EXCLUSIVE: | a read+write lock is obtained, no other proces can read or write to the database

As a convenience, these are constants available in the Database::TransactionBehavior class.

Amalgalite Transactions are database level transactions, just as SQLite‘s are.

If a block is passed in, then when the block exits, it is guaranteed that either ‘COMMIT’ or ‘ROLLBACK’ has been executed.

If any exception happens during the transaction that is caught by Amalgalite, then a ‘ROLLBACK’ is issued when the block closes.

If no exception happens during the transaction then a ‘COMMIT’ is issued upon leaving the block.

If no block is passed in then you are on your own.

Nesting a transaaction via the transaction method are no-ops. If you call transaction within a transaction, no new transaction is started, the current one is just continued.

True nexted transactions are available through the savepoint method.

transaction( mode = TransactionBehavior::DEFERRED ) {|self )| ...}

Begin a transaction. The valid transaction types are:

DEFERRED: | no read or write locks are created until the first statement is executed that requries a read or a write
IMMEDIATE: | a readlock is obtained immediately so that no other process can write to the database
EXCLUSIVE: | a read+write lock is obtained, no other proces can read or write to the database

As a convenience, these are constants available in the Database::TransactionBehavior class.

Amalgalite Transactions are database level transactions, just as SQLite‘s are.

If a block is passed in, then when the block exits, it is guaranteed that either ‘COMMIT’ or ‘ROLLBACK’ has been executed.

If any exception happens during the transaction that is caught by Amalgalite, then a ‘ROLLBACK’ is issued when the block closes.

If no exception happens during the transaction then a ‘COMMIT’ is issued upon leaving the block.

If no block is passed in then you are on your own.

Nesting a transaaction via the transaction method are no-ops. If you call transaction within a transaction, no new transaction is started, the current one is just continued.

True nexted transactions are available through the savepoint method.

db.type_map = DefaultMap.new

Assign your own TypeMap instance to do type conversions. The value assigned here must respond to `bind_type_of` and `result_value_of` methods. See the TypeMap class for more details.

db.type_map = DefaultMap.new

Assign your own TypeMap instance to do type conversions. The value assigned here must respond to `bind_type_of` and `result_value_of` methods. See the TypeMap class for more details.

utf16?()

Is the database utf16 or not? A database is utf16 if the encoding is not UTF-8. Database can only be UTF-8 or UTF-16, and the default is UTF-8

utf16?()

Is the database utf16 or not? A database is utf16 if the encoding is not UTF-8. Database can only be UTF-8 or UTF-16, and the default is UTF-8

[Validate]