# module SQLite3::Pragmas

This module is intended for inclusion solely by the Database class. It defines convenience methods for the various pragmas supported by SQLite3.

For a detailed description of these pragmas, see the SQLite3 documentation at sqlite.org/pragma.html.

### Constants

SYNCHRONOUS_MODES

  The enumeration of valid synchronous modes.

TEMP_STORE_MODES

  The enumeration of valid temp store modes.

### Public Instance Methods

auto_vacuum() click to toggle source

    # File lib/sqlite3/pragmas.rb, line 104
    def auto_vacuum
      get_boolean_pragma "auto_vacuum"
    end

auto_vacuum=( mode ) click to toggle source

    # File lib/sqlite3/pragmas.rb, line 108
    def auto_vacuum=( mode )
      set_boolean_pragma "auto_vacuum", mode
    end

cache_size() click to toggle source

    # File lib/sqlite3/pragmas.rb, line 128
    def cache_size
      get_int_pragma "cache_size"
    end

cache_size=( size ) click to toggle source

    # File lib/sqlite3/pragmas.rb, line 132
    def cache_size=( size )
      set_int_pragma "cache_size", size
    end

database_list( ) { |row| ... } click to toggle source

    # File lib/sqlite3/pragmas.rb, line 200
    def database_list( &block ) # :yields: row
      get_query_pragma "database_list", &block
    end

default_cache_size() click to toggle source

    # File lib/sqlite3/pragmas.rb, line 136
    def default_cache_size
      get_int_pragma "default_cache_size"
    end

default_cache_size=( size ) click to toggle source

    # File lib/sqlite3/pragmas.rb, line 140
    def default_cache_size=( size )
      set_int_pragma "default_cache_size", size
    end

default_synchronous() click to toggle source

    # File lib/sqlite3/pragmas.rb, line 144
    def default_synchronous
      get_enum_pragma "default_synchronous"
    end

default_synchronous=( mode ) click to toggle source

    # File lib/sqlite3/pragmas.rb, line 148
    def default_synchronous=( mode )
      set_enum_pragma "default_synchronous", mode, SYNCHRONOUS_MODES
    end

default_temp_store() click to toggle source

    # File lib/sqlite3/pragmas.rb, line 160
    def default_temp_store
      get_enum_pragma "default_temp_store"
    end

default_temp_store=( mode ) click to toggle source

    # File lib/sqlite3/pragmas.rb, line 164
    def default_temp_store=( mode )
      set_enum_pragma "default_temp_store", mode, TEMP_STORE_MODES
    end

foreign_key_list( table ) { |row| ... } click to toggle source

    # File lib/sqlite3/pragmas.rb, line 204
    def foreign_key_list( table, &block ) # :yields: row
      get_query_pragma "foreign_key_list", table, &block
    end

full_column_names() click to toggle source

    # File lib/sqlite3/pragmas.rb, line 176
    def full_column_names
      get_boolean_pragma "full_column_names"
    end

full_column_names=( mode ) click to toggle source

    # File lib/sqlite3/pragmas.rb, line 180
    def full_column_names=( mode )
      set_boolean_pragma "full_column_names", mode
    end

index_info( index ) { |row| ... } click to toggle source

    # File lib/sqlite3/pragmas.rb, line 208
    def index_info( index, &block ) # :yields: row
      get_query_pragma "index_info", index, &block
    end

index_list( table ) { |row| ... } click to toggle source

    # File lib/sqlite3/pragmas.rb, line 212
    def index_list( table, &block ) # :yields: row
      get_query_pragma "index_list", table, &block
    end

integrity_check() click to toggle source

Does an integrity check on the database. If the check fails, a SQLite3::Exception will be raised. Otherwise it returns silently.

    # File lib/sqlite3/pragmas.rb, line 98
    def integrity_check
      execute( "PRAGMA integrity_check" ) do |row|
        raise Exception, row[0] if row[0] != "ok"
      end
    end

parser_trace() click to toggle source

    # File lib/sqlite3/pragmas.rb, line 184
    def parser_trace
      get_boolean_pragma "parser_trace"
    end

parser_trace=( mode ) click to toggle source

    # File lib/sqlite3/pragmas.rb, line 188
    def parser_trace=( mode )
      set_boolean_pragma "parser_trace", mode
    end

schema_cookie() click to toggle source

    # File lib/sqlite3/pragmas.rb, line 112
    def schema_cookie
      get_int_pragma "schema_cookie"
    end

schema_cookie=( cookie ) click to toggle source

    # File lib/sqlite3/pragmas.rb, line 116
    def schema_cookie=( cookie )
      set_int_pragma "schema_cookie", cookie
    end

synchronous() click to toggle source

    # File lib/sqlite3/pragmas.rb, line 152
    def synchronous
      get_enum_pragma "synchronous"
    end

synchronous=( mode ) click to toggle source

    # File lib/sqlite3/pragmas.rb, line 156
    def synchronous=( mode )
      set_enum_pragma "synchronous", mode, SYNCHRONOUS_MODES
    end

table_info(table) { |new_row| ... } click to toggle source

Returns information about `table`. Yields each row of table information if a block is provided.

    # File lib/sqlite3/pragmas.rb, line 219
    def table_info table
      stmt    = prepare "PRAGMA table_info(#{table})"
      columns = stmt.columns

      needs_tweak_default =
        version_compare(SQLite3.libversion.to_s, "3.3.7") > 0

      result = [] unless block_given?
      stmt.each do |row|
        new_row = Hash[columns.zip(row)]

        # FIXME: This should be removed but is required for older versions
        # of rails
        if(Object.const_defined?(:ActiveRecord))
          new_row['notnull'] = new_row['notnull'].to_s
        end

        tweak_default(new_row) if needs_tweak_default

        if block_given?
          yield new_row
        else
          result << new_row
        end
      end
      stmt.close

      result
    end

temp_store() click to toggle source

    # File lib/sqlite3/pragmas.rb, line 168
    def temp_store
      get_enum_pragma "temp_store"
    end

temp_store=( mode ) click to toggle source

    # File lib/sqlite3/pragmas.rb, line 172
    def temp_store=( mode )
      set_enum_pragma "temp_store", mode, TEMP_STORE_MODES
    end

user_cookie() click to toggle source

    # File lib/sqlite3/pragmas.rb, line 120
    def user_cookie
      get_int_pragma "user_cookie"
    end

user_cookie=( cookie ) click to toggle source

    # File lib/sqlite3/pragmas.rb, line 124
    def user_cookie=( cookie )
      set_int_pragma "user_cookie", cookie
    end

vdbe_trace() click to toggle source

    # File lib/sqlite3/pragmas.rb, line 192
    def vdbe_trace
      get_boolean_pragma "vdbe_trace"
    end

vdbe_trace=( mode ) click to toggle source

    # File lib/sqlite3/pragmas.rb, line 196
    def vdbe_trace=( mode )
      set_boolean_pragma "vdbe_trace", mode
    end

### Private Instance Methods

get_boolean_pragma( name ) click to toggle source

Returns `true` or `false` depending on the value of the named pragma.

    # File lib/sqlite3/pragmas.rb, line 13
    def get_boolean_pragma( name )
      get_first_value( "PRAGMA #{name}" ) != "0"
    end

get_enum_pragma( name ) click to toggle source

Return the value of the given pragma.

    # File lib/sqlite3/pragmas.rb, line 58
    def get_enum_pragma( name )
      get_first_value( "PRAGMA #{name}" )
    end

get_int_pragma( name ) click to toggle source

Returns the value of the given pragma as an integer.

    # File lib/sqlite3/pragmas.rb, line 77
    def get_int_pragma( name )
      get_first_value( "PRAGMA #{name}" ).to_i
    end

get_query_pragma( name, *parms ) { |row| ... } click to toggle source

Requests the given pragma (and parameters), and if the block is given, each row of the result set will be yielded to it. Otherwise, the results are returned as an array.

    # File lib/sqlite3/pragmas.rb, line 47
    def get_query_pragma( name, *parms, &block ) # :yields: row
      if parms.empty?
        execute( "PRAGMA #{name}", &block )
      else
        args = "'" + parms.join("','") + "'"
        execute( "PRAGMA #{name}( #{args} )", &block )
      end
    end

set_boolean_pragma( name, mode ) click to toggle source

Sets the given pragma to the given boolean value. The value itself may be `true` or `false`, or any other commonly used string or integer that represents truth.

    # File lib/sqlite3/pragmas.rb, line 21
    def set_boolean_pragma( name, mode )
      case mode
        when String
          case mode.downcase
            when "on", "yes", "true", "y", "t"; mode = "'ON'"
            when "off", "no", "false", "n", "f"; mode = "'OFF'"
            else
              raise Exception,
                "unrecognized pragma parameter #{mode.inspect}"
          end
        when true, 1
          mode = "ON"
        when false, 0, nil
          mode = "OFF"
        else
          raise Exception,
            "unrecognized pragma parameter #{mode.inspect}"
      end

      execute( "PRAGMA #{name}=#{mode}" )
    end

set_enum_pragma( name, mode, enums ) click to toggle source

Set the value of the given pragma to `mode`. The `mode` parameter must conform to one of the values in the given `enum` array. Each entry in the array is another array comprised of elements in the enumeration that have duplicate values. See synchronous, default_synchronous, temp_store, and default_temp_store for usage examples.

    # File lib/sqlite3/pragmas.rb, line 68
    def set_enum_pragma( name, mode, enums )
      match = enums.find { |p| p.find { |i| i.to_s.downcase == mode.to_s.downcase } }
      raise Exception,
        "unrecognized #{name} #{mode.inspect}" unless match
      execute( "PRAGMA #{name}='#{match.first.upcase}'" )
    end

set_int_pragma( name, value ) click to toggle source

Set the value of the given pragma to the integer value of the `value` parameter.

    # File lib/sqlite3/pragmas.rb, line 84
    def set_int_pragma( name, value )
      execute( "PRAGMA #{name}=#{value.to_i}" )
    end

tweak_default(hash) click to toggle source

Since SQLite 3.3.8, the #table_info pragma has returned the default value of the row as a quoted SQL value. This method essentially unquotes those values.

    # File lib/sqlite3/pragmas.rb, line 268
    def tweak_default(hash)
      case hash["dflt_value"]
      when /^null$/i
        hash["dflt_value"] = nil
      when /^'(.*)'$/m
        hash["dflt_value"] = $1.gsub(/''/, "'")
      when /^"(.*)"$/m
        hash["dflt_value"] = $1.gsub(/""/, '"')
      end
    end

version_compare(v1, v2) click to toggle source

Compares two version strings

    # File lib/sqlite3/pragmas.rb, line 252
    def version_compare(v1, v2)
      v1 = v1.split(".").map { |i| i.to_i }
      v2 = v2.split(".").map { |i| i.to_i }
      parts = [v1.length, v2.length].max
      v1.push 0 while v1.length < parts
      v2.push 0 while v2.length < parts
      v1.zip(v2).each do |a,b|
        return -1 if a < b
        return  1 if a > b
      end
      return 0
    end