libsql 0.1.0

data/lib/libsql/function.rb

@@ -0,0 +1,61 @@
+require 'libsql/sqlite3/database/function'
+module ::Libsql
+  #
+  # A Base class to inherit from for creating your own SQL scalar functions
+  # in ruby.
+  #
+  # These are SQL functions similar to _abs(X)_, _length(X)_, _random()_.  Items
+  # that take parameters and return value.  They have no state between
+  # calls. Built in SQLite scalar functions are :
+  #
+  # * http://www.sqlite.org/lang_corefunc.html
+  # * http://www.sqlite.org/lang_datefunc.html
+  #
+  # Functions defined in ::Libsql databases conform to the Proc interface.
+  # Everything that is defined in an ::Libsql database using +define_function+
+  # has its +to_proc+ method called.  As a result, any Function must also
+  # conform to the +to_proc+ protocol.
+  #
+  # If you choose to use Function as a parent class of your SQL scalar function
+  # implementation you should only have implement +call+ with the appropriate
+  # _arity_.
+  #
+  # For instance to implement a _sha1(X)_ SQL function you could implement it as
+  #
+  #   class SQLSha1 < ::Libsql::Function
+  #     def initialize
+  #       super( 'md5', 1 )
+  #     end
+  #     def call( s )
+  #       ::Digest::MD5.hexdigest( s.to_s )
+  #     end
+  #   end
+  #
+  class Function
+    # The name of the SQL function
+    attr_accessor :name
+
+    # The arity of the SQL function
+    attr_accessor :arity
+
+    # Initialize the function with a name and arity
+    def initialize( name, arity )
+      @name = name
+      @arity = arity
+    end
+
+    # All SQL functions defined foloow the +to_proc+ protocol
+    def to_proc
+      self
+    end
+
+    # <b>Do Not Override</b>
+    #
+    # The function signature for use by the Amaglaite datase in tracking
+    # function definition and removal.
+    #
+    def signature
+      @signature ||= ::Libsql::SQLite3::Database::Function.signature( self.name, self.arity )
+    end
+  end
+end

data/lib/libsql/index.rb

@@ -0,0 +1,43 @@
+#--
+# Copyright (c) 2023 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+
+module ::Libsql
+  #
+  # a class representing the meta information about an SQLite index
+  #
+  class Index
+    # the name of the index
+    attr_reader   :name
+
+    # the sql statement that created the index
+    attr_reader   :sql
+
+    # the table the index is for
+    attr_accessor :table
+
+    # the columns that make up this index, in index order
+    attr_accessor :columns
+
+    # sqlite sequence number of the index
+    attr_accessor :sequence_number
+
+    # is the index unique
+    attr_writer   :unique
+
+    def initialize( name, sql, table ) 
+      @name             = name
+      @sql              = sql
+      @table            = table
+      @columns          = []
+      @sequence_number  = nil
+      @unique           = nil
+    end
+
+    def unique?
+      return @unique
+    end
+  end
+end
+

data/lib/libsql/memory_database.rb

@@ -0,0 +1,15 @@
+require 'libsql/database'
+module ::Libsql
+  #
+  # The encapsulation of a connection to an SQLite3 in-memory database.  
+  #
+  # Open an in-memory database:
+  #
+  #   db = ::Libsql::MemoryDatabase.new
+  #
+  class MemoryDatabase < Database
+    def initialize
+      super( ":memory:" )
+    end
+  end
+end

data/lib/libsql/paths.rb

@@ -0,0 +1,80 @@
+#--
+# Copyright (c) 2023 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+module ::Libsql
+  #
+  # Paths contains helpful methods to determine paths of files inside the
+  # ::Libsql library
+  #
+  module Paths
+    #
+    # The root directory of the project is considered to be the parent directory
+    # of the 'lib' directory.
+    #
+    # returns:: [String] The full expanded path of the parent directory of 'lib'
+    #           going up the path from the current file.  Trailing
+    #           File::SEPARATOR is guaranteed.
+    #
+    def self.root_dir
+      @root_dir ||= (
+        path_parts = ::File.expand_path(__FILE__).split(::File::SEPARATOR)
+        lib_index  = path_parts.rindex("lib")
+        path_parts[0...lib_index].join(::File::SEPARATOR) + ::File::SEPARATOR
+      )
+      return @root_dir
+    end
+
+    # returns:: [String] The full expanded path of the +config+ directory
+    #           below _root_dir_.  All parameters passed in are joined onto the
+    #           result.  Trailing File::SEPARATOR is guaranteed if _args_ are
+    #           *not* present.
+    #
+    def self.config_path(*args)
+      self.sub_path("config", *args)
+    end
+
+    # returns:: [String] The full expanded path of the +data+ directory below
+    #           _root_dir_.  All parameters passed in are joined onto the
+    #           result. Trailing File::SEPARATOR is guaranteed if
+    #           _*args_ are *not* present.
+    #
+    def self.data_path(*args)
+      self.sub_path("data", *args)
+    end
+
+    # returns:: [String] The full expanded path of the +lib+ directory below
+    #           _root_dir_.  All parameters passed in are joined onto the
+    #           result. Trailing File::SEPARATOR is guaranteed if
+    #           _*args_ are *not* present.
+    #
+    def self.lib_path(*args)
+      self.sub_path("lib", *args)
+    end
+
+    # returns:: [String] The full expanded path of the +ext+ directory below
+    #           _root_dir_.  All parameters passed in are joined onto the
+    #           result. Trailing File::SEPARATOR is guaranteed if
+    #           _*args_ are *not* present.
+    #
+    def self.ext_path(*args)
+      self.sub_path("ext", *args)
+    end
+
+    # returns:: [String] The full expanded path of the +spec+ directory below
+    #           _root_dir_.  All parameters passed in are joined onto the
+    #           result. Trailing File::SEPARATOR is guaranteed if
+    #           _*args_ are *not* present.
+    #
+    def self.spec_path(*args)
+      self.sub_path("spec", *args)
+    end
+
+
+    def self.sub_path(sub,*args)
+      sp = ::File.join(root_dir, sub) + File::SEPARATOR
+      sp = ::File.join(sp, *args) if args
+    end
+  end
+end
+

data/lib/libsql/profile_tap.rb

@@ -0,0 +1,131 @@
+#--
+# Copyright (c) 2023 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+
+module ::Libsql
+  # 
+  # A ProfileSampler is a sampler of profile times.  It aggregates up profile
+  # events that happen for the same source.  It is based upon the RFuzz::Sampler 
+  # class from the rfuzz gem
+  #
+  class ProfileSampler
+    #
+    # create a new sampler with the given name
+    #
+    def initialize( name )
+      @name = name
+      reset!
+    end
+
+    ##
+    # reset the internal state so it may be used again
+    #
+    def reset!
+      @sum   = 0.0
+      @sumsq = 0.0
+      @n     = 0
+      @min   = 0.0
+      @max   = 0.0
+    end
+
+    ##
+    # add a sample to the calculations
+    #
+    def sample( value )
+      @sum   += value
+      @sumsq += (value * value)
+      if @n == 0 then
+        @min = @max = value
+      else
+        @min = value if value < @min
+        @max = value if value > @max
+      end
+      @n += 1
+    end
+
+    ##
+    # return the mean of the data 
+    #
+    def mean
+      @sum / @n
+    end
+
+    ##
+    # returns the standard deviation of the data
+    #
+    def stddev
+      begin
+        return 0.0 if ( 1 == @n )
+        Math.sqrt( (@sumsq - ( @sum * @sum / @n)) / (@n-1) )
+      rescue Errno::EDOM
+        return 0.0
+      end
+    end
+
+    ##
+    # return all the values as an array
+    #
+    def to_a
+      [ @name, @sum, @sumsq, @n, mean, stddev, @min, @max ]
+    end
+
+    ##
+    # return all the values as a hash
+    #
+    def to_h
+      { 'name'    => @name,  'n' => @n,
+        'sum'     => @sum,   'sumsq'   => @sumsq, 'mean'    => mean,
+        'stddev'  => stddev, 'min'     => @min,   'max'     => @max }
+    end
+
+    ##
+    # return a string containing the sampler summary
+    #
+    def to_s
+      "[%s] => sum: %d, sumsq: %d, n: %d, mean: %0.6f, stddev: %0.6f, min: %d, max: %d" % self.to_a
+    end
+
+  end
+
+  #
+  # A Profile Tap recives +profile+ events from SQLite  which involve the number of
+  # nanoseconds in wall-clock time it took for a particular thing to happen. In
+  # general this +thing+ is an SQL statement.
+  #
+  # It has a well known +profile+ method which when invoked will write the event
+  # to a delegate object.
+  #
+  #
+  class ProfileTap
+
+    attr_reader :samplers
+
+    #
+    # Create a new ProfileTap object that wraps the given object and calls the
+    # method named in +send_to+ ever time a profile event happens.
+    #
+    def initialize( wrapped_obj, send_to = 'profile' )
+      unless wrapped_obj.respond_to?( send_to ) 
+        raise ::Libsql::Error, "#{wrapped_obj.class.name} does not respond to #{send_to.to_s} "
+      end
+
+      @delegate_obj    = wrapped_obj
+      @delegate_method = send_to
+      @samplers        = {}
+    end
+
+    #
+    # Record the profile information and send the delegate object the msg and
+    # time information.
+    #
+    def profile( msg, time )
+      msg = msg.gsub(/\s+/,' ')
+      unless sampler = @samplers[msg]
+        sampler = @samplers[msg] = ProfileSampler.new( msg )
+      end
+      sampler.sample( time )
+      @delegate_obj.send( @delegate_method, msg, time )
+    end
+  end
+end

data/lib/libsql/progress_handler.rb

@@ -0,0 +1,21 @@
+module ::Libsql
+  ##
+  # A base class for use in creating your own progress handler classes
+  #
+  class ProgressHandler
+    def to_proc
+      self
+    end
+
+    # the arity of the call method
+    def arity() 0 ; end
+
+    ##
+    # Override this method, returning +false+ if the SQLite should act as if
+    # +interrupt!+ had been invoked.
+    # 
+    def call
+      raise NotImplementedError, "The progress handler call() method must be implemented"
+    end
+  end
+end

data/lib/libsql/schema.rb

@@ -0,0 +1,225 @@
+#--
+# Copyright (c) 2023 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+
+require 'libsql/table'
+require 'libsql/index'
+require 'libsql/column'
+require 'libsql/view'
+
+module ::Libsql
+  #
+  # An object view of the schema  in the SQLite database.  If the schema changes
+  # after this class is created, it has no knowledge of that.
+  #
+  class Schema
+
+    # The internal database that this schema is for. Most of the time this will
+    # be 'main' for the main database. For the temp tables, this will be 'temp'
+    # and for any attached databsae, this is the name of attached database.
+    attr_reader :catalog
+
+    # The schema_version at the time this schema was taken.
+    attr_reader :schema_version
+
+    # The Amalagalite::Database this schema is associated with.
+    attr_reader :db
+
+    #
+    # Create a new instance of Schema
+    #
+    def initialize( db, catalog = 'main', master_table = 'sqlite_master' )
+      @db             = db
+      @catalog        = catalog
+      @schema_version = nil
+      @tables         = {}
+      @views          = {}
+      @master_table   = master_table
+
+      if @master_table == 'sqlite_master' then
+        @temp_schema = ::Libsql::Schema.new( db, 'temp', 'sqlite_temp_master')
+      else
+        @temp_schema = nil
+      end
+      load_schema!
+    end
+
+    def catalog_master_table
+      "#{catalog}.#{@master_table}"
+    end
+
+    def temporary?
+      catalog == "temp"
+    end
+
+    def dirty?()
+      return true  if (@schema_version != self.current_version)
+      return false unless @temp_schema
+      return @temp_schema.dirty?
+    end
+
+    def current_version
+      @db.first_value_from("PRAGMA #{catalog}.schema_version")
+    end
+
+    #
+    # load the schema from the database
+    def load_schema!
+      load_tables
+      load_views
+      if @temp_schema then
+        @temp_schema.load_schema!
+      end
+      @schema_version = self.current_version
+      nil
+    end
+
+    ##
+    # return the tables, reloading if dirty.
+    # If there is a temp table and a normal table with the same name, then the
+    # temp table is the one that is returned in the hash.
+    def tables
+      load_schema! if dirty?
+      t = @tables
+      if @temp_schema then
+        t = @tables.merge( @temp_schema.tables )
+      end
+      return t
+    end
+
+    ##
+    # load all the tables
+    #
+    def load_tables
+      @tables = {}
+      @db.execute("SELECT tbl_name FROM #{catalog_master_table} WHERE type = 'table' AND name != 'sqlite_sequence'") do |table_info|
+        table = load_table( table_info['tbl_name'] )
+        table.indexes = load_indexes( table )
+        @tables[table.name] = table
+      end
+      return @tables
+    end
+
+    ##
+    # Load a single table
+    def load_table( table_name )
+      rows = @db.execute("SELECT tbl_name, sql FROM #{catalog_master_table} WHERE type = 'table' AND tbl_name = ?", table_name)
+      table_info = rows.first
+      table = nil
+      if table_info then
+        table = ::Libsql::Table.new( table_info['tbl_name'], table_info['sql'] )
+        table.schema = self
+        table.columns = load_columns( table )
+        table.indexes = load_indexes( table )
+        @tables[table.name] = table
+      end
+      return table
+    end
+
+    ##
+    # load all the indexes for a particular table
+    #
+    def load_indexes( table )
+      indexes = {}
+
+      @db.prepare("SELECT name, sql FROM #{catalog_master_table} WHERE type ='index' and tbl_name = $name") do |idx_stmt|
+        idx_stmt.execute( "$name" => table.name) do |idx_info|
+          indexes[idx_info['name']] = ::Libsql::Index.new( idx_info['name'], idx_info['sql'], table )
+        end
+      end
+
+      @db.execute("PRAGMA index_list( #{@db.quote(table.name)} );") do |idx_list|
+        idx = indexes[idx_list['name']]
+
+        # temporary indexes do not show up in the previous list
+        if idx.nil? then
+          idx = ::Libsql::Index.new( idx_list['name'], nil, table )
+          indexes[idx_list['name']] = idx
+        end
+
+        idx.sequence_number = idx_list['seq']
+        idx.unique          = Boolean.to_bool( idx_list['unique'] )
+
+        @db.execute("PRAGMA index_info( #{@db.quote(idx.name)} );") do |col_info|
+          idx.columns << table.columns[col_info['name']]
+        end
+      end
+      return indexes
+    end
+
+    ##
+    # load all the columns for a particular table
+    #
+    def load_columns( table )
+      cols = {}
+      idx = 0
+      @db.execute("PRAGMA #{catalog}.table_info(#{@db.quote(table.name)})") do |row|
+        col = ::Libsql::Column.new( catalog,  table.name, row['name'], row['cid'])
+
+        col.default_value       = row['dflt_value']
+
+        col.declared_data_type  = row['type']
+        col.not_null_constraint = row['notnull']
+        col.primary_key         = row['pk']
+
+        # need to remove leading and trailing ' or " from the default value
+        if col.default_value and col.default_value.kind_of?( String ) and ( col.default_value.length >= 2 ) then
+          fc = col.default_value[0].chr
+          lc = col.default_value[-1].chr
+          if fc == lc and ( fc == "'" || fc == '"' ) then
+            col.default_value = col.default_value[1..-2]
+          end
+        end
+
+        unless table.temporary? then
+          # get more exact information
+          @db.api.table_column_metadata( catalog, table.name, col.name ).each_pair do |key, value|
+            col.send("#{key}=", value)
+          end
+        end
+        col.schema = self
+        cols[col.name] = col
+        idx += 1
+      end
+      return cols
+    end
+
+    ##
+    # return the views, reloading if dirty
+    #
+    # If there is a temp view, and a regular view of the same name, then the
+    # temporary view is the one that is returned in the hash.
+    #
+    def views
+      reload_schema! if dirty?
+      v = @views
+      if @temp_schema then
+        v = @views.merge( @temp_schema.views )
+      end
+      return v
+    end
+
+    ##
+    # load a single view
+    #
+    def load_view( name )
+      rows = @db.execute("SELECT name, sql FROM #{catalog_master_table} WHERE type = 'view' AND name = ?", name )
+      view_info = rows.first
+      view = ::Libsql::View.new( view_info['name'], view_info['sql'] )
+      view.schema = self
+      return view
+    end
+
+    ##
+    # load all the views for the database
+    #
+    def load_views
+      @db.execute("SELECT name, sql FROM #{catalog_master_table} WHERE type = 'view'") do |view_info|
+        view = load_view( view_info['name'] )
+        @views[view.name] = view
+      end
+      return @views
+    end
+  end
+end

data/lib/libsql/sqlite3/constants.rb

@@ -0,0 +1,95 @@
+#--
+# Copyright (c) 2023 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+module ::Libsql::SQLite3
+  module Constants
+    module Helpers
+      #
+      # convert an integer value into the string representation of the associated
+      # constant. this is a helper method used by some of the other modules
+      #
+      def name_from_value( value )
+        unless defined? @const_map_from_value
+          @const_map_from_value = {}
+          constants.each do |const_name|
+            c_int = const_get( const_name )
+            @const_map_from_value[c_int] = const_name.to_s
+          end
+        end
+        return @const_map_from_value[ value ]
+      end
+
+      #
+      # convert a string into the constant value.  This is helper method used by
+      # some of the other modules
+      #
+      def value_from_name( name )
+        unless defined? @const_map_from_name
+          @const_map_from_name = {}
+          constants.each do |const_name|
+            c_int = const_get( const_name )
+            @const_map_from_name[ const_name.to_s ] = c_int
+          end
+        end
+        return @const_map_from_name[ name.upcase ]
+      end
+    end
+
+
+    ##
+    # DataType defines the namespace for all possible SQLite data types.
+    # 
+    module DataType
+      extend Helpers
+    end
+
+    ##
+    # Open defines the namespace for all possible flags to the Database.open
+    # method
+    #
+    module Open
+      extend Helpers
+    end
+
+    ##
+    # Status defines the namespace for all the possible status flags for
+    # ::Libsql::SQLite3::Status objects
+    #
+    module Status
+      extend Helpers
+    end
+
+    ##
+    # DBStatus defines the namespace for all the possible status codes for the
+    # ::Libsql::SQlite3::Database::Status objects.
+    #
+    module DBStatus
+      extend Helpers
+    end
+
+    ##
+    # ResultCode defines the namespace for all possible result codes from an
+    # SQLite API call.
+    #
+    module ResultCode
+      extend Helpers
+    end # end ResultCode
+
+    ##
+    # Config defines the namespace for all possible parameter for the
+    # sqlite config API.
+    #
+    module Config
+      extend Helpers
+    end
+
+    ##
+    # StatementStatus defines the namespace for all the possible status codes
+    # for the SQLite prepared statements
+    #
+    module StatementStatus
+      extend Helpers
+    end
+  end
+end