sqlite3 1.4.2 → 1.7.2

data/faq/faq.yml

@@ -1,426 +0,0 @@
----
-- "How do I do a database query?":
-  - "I just want an array of the rows...": >-
-
-      Use the Database#execute method. If you don't give it a block, it will
-      return an array of all the rows:
-
-
-      <pre>
-        require 'sqlite3'
-
-        db = SQLite3::Database.new( "test.db" )
-        rows = db.execute( "select * from test" )
-      </pre>
-
-  - "I'd like to use a block to iterate through the rows...": >-
-
-      Use the Database#execute method. If you give it a block, each row of the
-      result will be yielded to the block:
-
-
-      <pre>
-        require 'sqlite3'
-
-        db = SQLite3::Database.new( "test.db" )
-        db.execute( "select * from test" ) do |row|
-          ...
-        end
-      </pre>
-
-  - "I need to get the column names as well as the rows...": >-
-
-      Use the Database#execute2 method. This works just like Database#execute;
-      if you don't give it a block, it returns an array of rows; otherwise, it
-      will yield each row to the block. _However_, the first row returned is
-      always an array of the column names from the query:
-
-
-      <pre>
-        require 'sqlite3'
-
-        db = SQLite3::Database.new( "test.db" )
-        columns, *rows = db.execute2( "select * from test" )
-
-        # or use a block:
-
-        columns = nil
-        db.execute2( "select * from test" ) do |row|
-          if columns.nil?
-            columns = row
-          else
-            # process row
-          end
-        end
-      </pre>
-
-  - "I just want the first row of the result set...": >-
-
-      Easy. Just call Database#get_first_row:
-
-
-      <pre>
-        row = db.get_first_row( "select * from table" )
-      </pre>
-
-
-      This also supports bind variables, just like Database#execute
-      and friends.
-
-  - "I just want the first value of the first row of the result set...": >-
-
-      Also easy. Just call Database#get_first_value:
-
-
-      <pre>
-        count = db.get_first_value( "select count(*) from table" )
-      </pre>
-
-
-      This also supports bind variables, just like Database#execute
-      and friends.
-
-- "How do I prepare a statement for repeated execution?": >-
-    If the same statement is going to be executed repeatedly, you can speed
-    things up a bit by _preparing_ the statement. You do this via the
-    Database#prepare method. It returns a Statement object, and you can
-    then invoke #execute on that to get the ResultSet:
-
-    
-    <pre>
-      stmt = db.prepare( "select * from person" )
-
-      1000.times do
-        stmt.execute do |result|
-          ...
-        end
-      end
-
-      stmt.close
-
-      # or, use a block
-
-      db.prepare( "select * from person" ) do |stmt|
-        1000.times do
-          stmt.execute do |result|
-            ...
-          end
-        end
-      end
-    </pre>
-
-
-    This is made more useful by the ability to bind variables to placeholders
-    via the Statement#bind_param and Statement#bind_params methods. (See the
-    next FAQ for details.)
-
-- "How do I use placeholders in an SQL statement?": >-
-    Placeholders in an SQL statement take any of the following formats:
-
-
-    * @?@
-
-    * @?_nnn_@
-
-    * @:_word_@
-
-
-    Where _n_ is an integer, and _word_ is an alpha-numeric identifier (or
-    number). When the placeholder is associated with a number, that number
-    identifies the index of the bind variable to replace it with. When it
-    is an identifier, it identifies the name of the correponding bind
-    variable. (In the instance of the first format--a single question
-    mark--the placeholder is assigned a number one greater than the last
-    index used, or 1 if it is the first.)
-
-
-    For example, here is a query using these placeholder formats:
-
-
-    <pre>
-      select *
-        from table
-       where ( c = ?2 or c = ? )
-         and d = :name
-         and e = :1
-    </pre>
-
-
-    This defines 5 different placeholders: 1, 2, 3, and "name".
-
-
-    You replace these placeholders by _binding_ them to values. This can be
-    accomplished in a variety of ways.
-
-
-    The Database#execute, and Database#execute2 methods all accept additional
-    arguments following the SQL statement. These arguments are assumed to be
-    bind parameters, and they are bound (positionally) to their corresponding
-    placeholders:
-
-
-    <pre>
-      db.execute( "select * from table where a = ? and b = ?",
-                  "hello",
-                  "world" )
-    </pre>
-
-
-    The above would replace the first question mark with 'hello' and the
-    second with 'world'. If the placeholders have an explicit index given, they
-    will be replaced with the bind parameter at that index (1-based).
-
-
-    If a Hash is given as a bind parameter, then its key/value pairs are bound
-    to the placeholders. This is how you bind by name:
-
-
-    <pre>
-      db.execute( "select * from table where a = :name and b = :value",
-                  "name" => "bob",
-                  "value" => "priceless" )
-    </pre>
-
-
-    You can also bind explicitly using the Statement object itself. Just pass
-    additional parameters to the Statement#execute statement:
-    
-
-    <pre>
-      db.prepare( "select * from table where a = :name and b = ?" ) do |stmt|
-        stmt.execute "value", "name" => "bob"
-      end
-    </pre>
-
-
-    Or do a Database#prepare to get the Statement, and then use either
-    Statement#bind_param or Statement#bind_params:
-
-
-    <pre>
-      stmt = db.prepare( "select * from table where a = :name and b = ?" )
-
-      stmt.bind_param( "name", "bob" )
-      stmt.bind_param( 1, "value" )
-
-      # or
-
-      stmt.bind_params( "value", "name" => "bob" )
-    </pre>
-
-- "How do I discover metadata about a query?": >-
-  
-    If you ever want to know the names or types of the columns in a result
-    set, you can do it in several ways.
-
-
-    The first way is to ask the row object itself. Each row will have a
-    property "fields" that returns an array of the column names. The row
-    will also have a property "types" that returns an array of the column
-    types:
-
-
-    <pre>
-      rows = db.execute( "select * from table" )
-      p rows[0].fields
-      p rows[0].types
-    </pre>
-
-
-    Obviously, this approach requires you to execute a statement that actually
-    returns data. If you don't know if the statement will return any rows, but
-    you still need the metadata, you can use Database#query and ask the
-    ResultSet object itself:
-
-
-    <pre>
-      db.query( "select * from table" ) do |result|
-        p result.columns
-        p result.types
-        ...
-      end
-    </pre>
-
-
-    Lastly, you can use Database#prepare and ask the Statement object what
-    the metadata are:
-
-
-    <pre>
-      stmt = db.prepare( "select * from table" )
-      p stmt.columns
-      p stmt.types
-    </pre>
-
-- "I'd like the rows to be indexible by column name.": >-
-    By default, each row from a query is returned as an Array of values. This
-    means that you can only obtain values by their index. Sometimes, however,
-    you would like to obtain values by their column name.
-
-
-    The first way to do this is to set the Database property "results_as_hash"
-    to true. If you do this, then all rows will be returned as Hash objects,
-    with the column names as the keys. (In this case, the "fields" property
-    is unavailable on the row, although the "types" property remains.)
-
-
-    <pre>
-      db.results_as_hash = true
-      db.execute( "select * from table" ) do |row|
-        p row['column1']
-        p row['column2']
-      end
-    </pre>
-
-
-    The other way is to use Ara Howard's
-    "ArrayFields":http://rubyforge.org/projects/arrayfields
-    module. Just require "arrayfields", and all of your rows will be indexable
-    by column name, even though they are still arrays!
-
-
-    <pre>
-      require 'arrayfields'
-
-      ...
-      db.execute( "select * from table" ) do |row|
-        p row[0] == row['column1']
-        p row[1] == row['column2']
-      end
-    </pre>
-
-- "I'd like the values from a query to be the correct types, instead of String.": >-
-    You can turn on "type translation" by setting Database#type_translation to
-    true:
-
-
-    <pre>
-      db.type_translation = true
-      db.execute( "select * from table" ) do |row|
-        p row
-      end
-    </pre>
-
-
-    By doing this, each return value for each row will be translated to its
-    correct type, based on its declared column type.
-
-
-    You can even declare your own translation routines, if (for example) you are
-    using an SQL type that is not handled by default:
-
-
-    <pre>
-      # assume "objects" table has the following schema:
-      #   create table objects (
-      #     name varchar2(20),
-      #     thing object
-      #   )
-
-      db.type_translation = true
-      db.translator.add_translator( "object" ) do |type, value|
-        db.decode( value )
-      end
-
-      h = { :one=>:two, "three"=>"four", 5=>6 }
-      dump = db.encode( h )
-
-      db.execute( "insert into objects values ( ?, ? )", "bob", dump )
-
-      obj = db.get_first_value( "select thing from objects where name='bob'" )
-      p obj == h
-    </pre>
-
-- "How do I insert binary data into the database?": >-
-    Use blobs. Blobs are new features of SQLite3. You have to use bind
-    variables to make it work:
-
-
-    <pre>
-      db.execute( "insert into foo ( ?, ? )",
-        SQLite3::Blob.new( "\0\1\2\3\4\5" ),
-        SQLite3::Blob.new( "a\0b\0c\0d ) )
-    </pre>
-
-
-    The blob values must be indicated explicitly by binding each parameter to
-    a value of type SQLite3::Blob.
-
-- "How do I do a DDL (insert, update, delete) statement?": >-
-    You can actually do inserts, updates, and deletes in exactly the same way
-    as selects, but in general the Database#execute method will be most
-    convenient:
-
-    
-    <pre>
-      db.execute( "insert into table values ( ?, ? )", *bind_vars )
-    </pre>
-
-- "How do I execute multiple statements in a single string?": >-
-    The standard query methods (Database#execute, Database#execute2,
-    Database#query, and Statement#execute) will only execute the first
-    statement in the string that is given to them. Thus, if you have a
-    string with multiple SQL statements, each separated by a string,
-    you can't use those methods to execute them all at once.
-
-
-    Instead, use Database#execute_batch:
-
-
-    <pre>
-      sql = <<SQL
-        create table the_table (
-          a varchar2(30),
-          b varchar2(30)
-        );
-
-        insert into the_table values ( 'one', 'two' );
-        insert into the_table values ( 'three', 'four' );
-        insert into the_table values ( 'five', 'six' );
-      SQL
-
-      db.execute_batch( sql )
-    </pre>
-
-
-    Unlike the other query methods, Database#execute_batch accepts no
-    block. It will also only ever return +nil+. Thus, it is really only
-    suitable for batch processing of DDL statements.
-
-- "How do I begin/end a transaction?":
-    Use Database#transaction to start a transaction. If you give it a block,
-    the block will be automatically committed at the end of the block,
-    unless an exception was raised, in which case the transaction will be
-    rolled back. (Never explicitly call Database#commit or Database#rollback
-    inside of a transaction block--you'll get errors when the block
-    terminates!)
-
-
-    <pre>
-      database.transaction do |db|
-        db.execute( "insert into table values ( 'a', 'b', 'c' )" )
-        ...
-      end
-    </pre>
-
-
-    Alternatively, if you don't give a block to Database#transaction, the
-    transaction remains open until you explicitly call Database#commit or
-    Database#rollback.
-
-
-    <pre>
-      db.transaction
-      db.execute( "insert into table values ( 'a', 'b', 'c' )" )
-      db.commit
-    </pre>
-
-
-    Note that SQLite does not allow nested transactions, so you'll get errors
-    if you try to open a new transaction while one is already active. Use
-    Database#transaction_active? to determine whether a transaction is
-    active or not.
-
-#- "How do I discover metadata about a table/index?":
-#
-#- "How do I do tweak database settings?":

data/rakelib/faq.rake

@@ -1,9 +0,0 @@
-# Generate FAQ
-desc "Generate the FAQ document"
-task :faq => ['faq/faq.html']
-
-file 'faq/faq.html' => ['faq/faq.rb', 'faq/faq.yml'] do
-  cd 'faq' do
-    ruby "faq.rb > faq.html"
-  end
-end

data/rakelib/gem.rake

@@ -1,40 +0,0 @@
-begin
-  require 'hoe'
-rescue LoadError
-  # try with rubygems?
-  require 'rubygems'
-  require 'hoe'
-end
-
-Hoe.plugin :debugging, :doofus, :git, :minitest, :bundler, :gemspec
-
-HOE = Hoe.spec 'sqlite3' do
-  developer           'Jamis Buck', 'jamis@37signals.com'
-  developer           'Luis Lavena', 'luislavena@gmail.com'
-  developer           'Aaron Patterson', 'aaron@tenderlovemaking.com'
-
-  license             "BSD-3-Clause"
-
-  self.readme_file   = 'README.rdoc'
-  self.history_file  = 'CHANGELOG.rdoc'
-  self.extra_rdoc_files  = FileList['*.rdoc', 'ext/**/*.c']
-
-  require_ruby_version ">= 1.8.7"
-  require_rubygems_version ">= 1.3.5"
-
-  spec_extras[:extensions] = ["ext/sqlite3/extconf.rb"]
-  spec_extras[:metadata] = {'msys2_mingw_dependencies' => 'sqlite3'}
-
-  extra_dev_deps << ['rake-compiler', "~> 1.0"]
-  extra_dev_deps << ['rake-compiler-dock', "~> 0.6.0"]
-  extra_dev_deps << ["mini_portile", "~> 0.6.2"]
-  extra_dev_deps << ["minitest", "~> 5.0"]
-  extra_dev_deps << ["hoe-bundler", "~> 1.0"]
-  extra_dev_deps << ["hoe-gemspec", "~> 1.0"]
-
-  clean_globs.push('**/test.db')
-end
-
-Hoe.add_include_dirs '.'
-
-# vim: syntax=ruby

data/rakelib/native.rake

@@ -1,56 +0,0 @@
-# use rake-compiler for building the extension
-require 'rake/extensiontask'
-require 'rake/extensioncompiler'
-
-# NOTE: version used by cross compilation of Windows native extension
-# It do not affect compilation under other operating systems
-# The version indicated is the minimum DLL suggested for correct functionality
-BINARY_VERSION = "3.8.11.1"
-URL_VERSION    = "3081101"
-URL_PATH       = "/2015"
-
-task :devkit do
-  begin
-    require "devkit"
-  rescue LoadError => e
-    abort "Failed to activate RubyInstaller's DevKit required for compilation."
-  end
-end
-
-# build sqlite3_native C extension
-RUBY_EXTENSION = Rake::ExtensionTask.new('sqlite3_native', HOE.spec) do |ext|
-  # where to locate the extension
-  ext.ext_dir = 'ext/sqlite3'
-
-  # where native extension will be copied (matches makefile)
-  ext.lib_dir = "lib/sqlite3"
-
-  # clean binary folders always
-  CLEAN.include("#{ext.lib_dir}/?.?")
-
-  # automatically add build options to avoid need of manual input
-  if RUBY_PLATFORM =~ /mswin|mingw/ then
-    # define target for extension (supporting fat binaries)
-    RUBY_VERSION =~ /(\d+\.\d+)/
-    ext.lib_dir = "lib/sqlite3/#{$1}"
-  else
-
-    # detect cross-compiler available
-    begin
-      Rake::ExtensionCompiler.mingw_host
-      ext.cross_compile = true
-      ext.cross_platform = ['i386-mswin32-60', 'i386-mingw32', 'x64-mingw32']
-      ext.cross_compiling do |spec|
-        # The fat binary gem doesn't depend on the sqlite3 package, since it bundles the library.
-        spec.metadata.delete('msys2_mingw_dependencies')
-      end
-    rescue RuntimeError
-      # noop
-    end
-  end
-end
-
-# ensure things are compiled prior testing
-task :test => [:compile]
-
-# vim: syntax=ruby

data/rakelib/vendor_sqlite3.rake

@@ -1,97 +0,0 @@
-require "rake/clean"
-require "rake/extensioncompiler"
-require "mini_portile"
-
-CLOBBER.include("ports")
-
-directory "ports"
-
-def define_sqlite_task(platform, host)
-  recipe = MiniPortile.new "sqlite3", BINARY_VERSION
-  recipe.files << "http://sqlite.org#{URL_PATH}/sqlite-autoconf-#{URL_VERSION}.tar.gz"
-  recipe.host = host
-
-  desc "Compile sqlite3 for #{platform} (#{host})"
-  task "ports:sqlite3:#{platform}" => ["ports"] do |t|
-    checkpoint = "ports/.#{recipe.name}-#{recipe.version}-#{recipe.host}.installed"
-
-    unless File.exist?(checkpoint)
-      cflags = "-O2 -DSQLITE_ENABLE_COLUMN_METADATA"
-      cflags << " -fPIC" if recipe.host && recipe.host.include?("x86_64")
-      recipe.configure_options << "CFLAGS='#{cflags}'"
-      recipe.cook
-      touch checkpoint
-    end
-  end
-
-  recipe
-end
-
-# native sqlite3 compilation
-recipe = define_sqlite_task(RUBY_PLATFORM, RbConfig::CONFIG["host"])
-
-# force compilation of sqlite3 when working natively under MinGW
-if RUBY_PLATFORM =~ /mingw/
-  RUBY_EXTENSION.config_options << "--with-opt-dir=#{recipe.path}"
-
-  # also prepend DevKit into compilation phase
-  Rake::Task["compile"].prerequisites.unshift "devkit", "ports:sqlite3:#{RUBY_PLATFORM}"
-  Rake::Task["native"].prerequisites.unshift "devkit", "ports:sqlite3:#{RUBY_PLATFORM}"
-end
-
-# trick to test local compilation of sqlite3
-if ENV["USE_MINI_PORTILE"] == "true"
-  # fake recipe so we can build a directory to it
-  recipe = MiniPortile.new "sqlite3", BINARY_VERSION
-  recipe.host = RbConfig::CONFIG["host"]
-
-  RUBY_EXTENSION.config_options << "--with-opt-dir=#{recipe.path}"
-
-  # compile sqlite3 first
-  Rake::Task["compile"].prerequisites.unshift "ports:sqlite3:#{RUBY_PLATFORM}"
-end
-
-# iterate over all cross-compilation platforms and define the proper
-# sqlite3 recipe for it.
-if RUBY_EXTENSION.cross_compile
-  config_path = File.expand_path("~/.rake-compiler/config.yml")
-  if File.exist?(config_path)
-    # obtains platforms from rake-compiler's config.yml
-    config_file = YAML.load_file(config_path)
-
-    Array(RUBY_EXTENSION.cross_platform).each do |platform|
-      # obtain platform from rbconfig file
-      config_key = config_file.keys.sort.find { |key|
-        key.start_with?("rbconfig-#{platform}-")
-      }
-      rbfile = config_file[config_key]
-
-      # skip if rbconfig cannot be read
-      next unless File.exist?(rbfile)
-
-      host = IO.read(rbfile).match(/CONFIG\["CC"\] = "(.*)"/)[1].sub(/\-gcc/, '')
-      recipe = define_sqlite_task(platform, host)
-
-      RUBY_EXTENSION.cross_config_options << {
-        platform => "--with-opt-dir=#{recipe.path}"
-      }
-
-      # pre-compile sqlite3 port when cross-compiling
-      task :cross => "ports:sqlite3:#{platform}"
-    end
-  else
-    warn "rake-compiler configuration doesn't exist, but is required for ports"
-  end
-end
-
-task :cross do
-  ["CC", "CXX", "LDFLAGS", "CPPFLAGS", "RUBYOPT"].each do |var|
-    ENV.delete(var)
-  end
-end
-
-desc "Build windows binary gems per rake-compiler-dock."
-task "gem:windows" do
-  require "rake_compiler_dock"
-  RakeCompilerDock.sh "bundle && rake cross native gem MAKE='nice make -j`nproc`'"
-end