module SQLite3 - sqlite3-1.3.13 Documentation

# module SQLite3

SQLite3 is a wrapper around the popular database sqlite.

For an example of usage, see SQLite3::Database.

### Constants

SQLITE_VERSION
SQLITE_VERSION_NUMBER
VERSION

### Public Class Methods

const_missing(name) click to toggle source
Calls superclass method

    # File lib/sqlite3/version.rb, line 18
      def self.const_missing(name)
        return super unless name == :Version
        warn(<<-eowarn) if $VERBOSE
    #{caller[0]}: SQLite::Version will be removed in sqlite3-ruby version 2.0.0
        eowarn
        VersionProxy
      end

libversion() click to toggle source

    static VALUE libversion(VALUE UNUSED(klass))
    {
      return INT2NUM(sqlite3_libversion_number());
    }

new(klass) click to toggle source

    # File lib/sqlite3/database.rb, line 454
    def initialize klass
      @klass = klass
      @fp    = FunctionProxy.new
    end

threadsafe() click to toggle source

Returns the compile time setting of the SQLITE_THREADSAFE flag. See: www.sqlite.org/c3ref/threadsafe.html

    static VALUE threadsafe_p(VALUE UNUSED(klass))
    {
      return INT2NUM(sqlite3_threadsafe());
    }

threadsafe?() click to toggle source

Was sqlite3 compiled with thread safety on?

    # File lib/sqlite3.rb, line 14
    def self.threadsafe?; threadsafe > 0; end

### Public Instance Methods

commit() click to toggle source

Commits the current transaction. If there is no current transaction, this will cause an error to be raised. This returns `true`, in order to allow it to be used in idioms like `abort? and rollback or commit`.

    # File lib/sqlite3/database.rb, line 517
    def commit
      execute "commit transaction"
      true
    end

create_aggregate_handler( handler ) click to toggle source

This is another approach to creating an aggregate function (see create_aggregate). Instead of explicitly specifying the name, callbacks, arity, and type, you specify a factory object (the “handler”) that knows how to obtain all of that information. The handler should respond to the following messages:

`arity`

  corresponds to the `arity` parameter of create_aggregate. This message is optional, and if the handler does not respond to it, the function will have an arity of -1.

`name`

  this is the name of the function. The handler must implement this message.

`new`

  this must be implemented by the handler. It should return a new instance of the object that will handle a specific invocation of the function.

The handler instance (the object returned by the `new` message, described above), must respond to the following messages:

`step`

  this is the method that will be called for each step of the aggregate function's evaluation. It should implement the same signature as the `step` callback for create_aggregate.

`finalize`

  this is the method that will be called to finalize the aggregate function's evaluation. It should implement the same signature as the `finalize` callback for create_aggregate.

Example:

    class LengthsAggregateHandler
      def self.arity; 1; end
      def self.name; 'lengths'; end

      def initialize
        @total = 0
      end

      def step( ctx, name )
        @total += ( name ? name.length : 0 )
      end

      def finalize( ctx )
        ctx.result = @total
      end
    end

    db.create_aggregate_handler( LengthsAggregateHandler )
    puts db.get_first_value( "select lengths(name) from A" )

    # File lib/sqlite3/database.rb, line 452
    def create_aggregate_handler( handler )
      proxy = Class.new do
        def initialize klass
          @klass = klass
          @fp    = FunctionProxy.new
        end

        def step( *args )
          instance.step(@fp, *args)
        end

        def finalize
          instance.finalize @fp
          @instance = nil
          @fp.result
        end

        private

        def instance
          @instance ||= @klass.new
        end
      end
      define_aggregator(handler.name, proxy.new(handler))
      self
    end

finalize() click to toggle source

    # File lib/sqlite3/database.rb, line 463
    def finalize
      instance.finalize @fp
      @instance = nil
      @fp.result
    end

instance() click to toggle source

    # File lib/sqlite3/database.rb, line 471
    def instance
      @instance ||= @klass.new
    end

readonly?() click to toggle source

Returns `true` if the database has been open in readonly mode A helper to check before performing any operation

    # File lib/sqlite3/database.rb, line 533
    def readonly?
      @readonly
    end

rollback() click to toggle source

Rolls the current transaction back. If there is no current transaction, this will cause an error to be raised. This returns `true`, in order to allow it to be used in idioms like `abort? and rollback or commit`.

    # File lib/sqlite3/database.rb, line 526
    def rollback
      execute "rollback transaction"
      true
    end

step( *args ) click to toggle source

    # File lib/sqlite3/database.rb, line 459
    def step( *args )
      instance.step(@fp, *args)
    end

transaction( mode = :deferred ) { |self| ... } click to toggle source

Begins a new transaction. Note that nested transactions are not allowed by SQLite, so attempting to nest a transaction will result in a runtime exception.

The `mode` parameter may be either `:deferred` (the default), `:immediate`, or `:exclusive`.

If a block is given, the database instance is yielded to it, and the transaction is committed when the block terminates. If the block raises an exception, a rollback will be performed instead. Note that if a block is given, commit and rollback should never be called explicitly or you'll get an error when the block terminates.

If a block is not given, it is the caller's responsibility to end the transaction explicitly, either by calling commit, or by calling rollback.

    # File lib/sqlite3/database.rb, line 495
    def transaction( mode = :deferred )
      execute "begin #{mode.to_s} transaction"

      if block_given?
        abort = false
        begin
          yield self
        rescue ::Object
          abort = true
          raise
        ensure
          abort and rollback or commit
        end
      end

      true
    end

### Private Instance Methods

ordered_map_for(columns, row) click to toggle source

    # File lib/sqlite3/database.rb, line 585
    def ordered_map_for columns, row
      h = Hash[*columns.zip(row).flatten]
      row.each_with_index { |r, i| h[i] = r }
      h
    end