ruby-ladybug 0.1.0

data/lib/ladybug/connection.rb

@@ -0,0 +1,51 @@
+# -*- ruby -*-
+
+require 'loggability'
+
+require 'ladybug' unless defined?( Ladybug )
+
+
+# Kùzu connection class
+class Ladybug::Connection
+	extend Loggability
+
+
+	# Loggability API -- log to Ladybug's logger
+	log_to :ladybug
+
+
+	### Execute the given +query_string+ via the connection and return the
+	### Ladybug::Result. If a block is given, the result will instead be yielded to it,
+	### finished when it returns, and the return value of the block will be returned
+	### instead.
+	def query( query_string, &block )
+		result = self._query( query_string )
+		return Ladybug::Result.wrap_block_result( result, &block )
+	end
+
+
+	### Create a new Ladybug::PreparedStatement for the specified +query_string+.
+	def prepare( query_string )
+		return Ladybug::PreparedStatement.new( self, query_string )
+	end
+
+
+	### Executes the given +statement+ (a Ladybug::PreparedStatement) after binding
+	### the given +bound_variables+ to it.
+	def execute( statement, **bound_variables, &block )
+		statement.bind( **bound_variables )
+		return statement.execute
+	end
+
+
+	### Return a string representation of the receiver suitable for debugging.
+	def inspect
+		details = " threads:%d" % [
+			self.max_num_threads_for_exec,
+		]
+
+		default = super
+		return default.sub( />/, details + '>' )
+	end
+
+end # class Ladybug::Connection

data/lib/ladybug/database.rb

@@ -0,0 +1,53 @@
+# -*- ruby -*-
+
+require 'loggability'
+
+require 'ladybug' unless defined?( Ladybug )
+
+
+# Main Kùzu database class
+class Ladybug::Database
+	extend Loggability
+
+
+	# Loggability API -- log to Ladybug's logger
+	log_to :ladybug
+
+
+	### Return a connection to this database.
+	def connect
+		return Ladybug::Connection.new( self )
+	end
+
+
+	### Return +true+ if this database was created in read-only mode.
+	def read_only?
+		return self.config.read_only
+	end
+
+
+	### Returns +true+ if this database will automatically checkpoint when the size of
+	### the WAL file exceeds the `checkpoint_threshold`.
+	def auto_checkpointing?
+		return self.config.auto_checkpoint
+	end
+
+
+	### Returns +true+ if this database uses compression for data on disk.
+	def compression_enabled?
+		return self.config.enable_compression
+	end
+
+
+	### Return a string representation of the receiver suitable for debugging.
+	def inspect
+		details = " path:%p read-only:%p" % [
+			self.path,
+			self.read_only?,
+		]
+
+		default = super
+		return default.sub( />/, details + '>' )
+	end
+
+end # class Ladybug::Database

data/lib/ladybug/node.rb

@@ -0,0 +1,46 @@
+# -*- ruby -*-
+
+require 'forwardable'
+require 'loggability'
+
+require 'ladybug' unless defined?( Ladybug )
+
+
+# Ladybug node class
+class Ladybug::Node
+	extend Loggability,
+		Forwardable
+
+	# Loggability API -- log to Ladybug's logger
+	log_to :ladybug
+
+
+	### Create a new Node with the given +id+, +label+, and +properties+.
+	def initialize( id, label, **properties )
+		@id = id
+		@label = label
+		@properties = properties
+	end
+
+
+	######
+	public
+	######
+
+	##
+	# The internal id value of the given node
+	attr_reader :id
+
+	##
+	# The label value of the given node
+	attr_reader :label
+
+	##
+	# The Hash of the Node's properties, keyed by name as a Symbol
+	attr_reader :properties
+
+
+	# Allow direct access to properties
+	def_delegators :@properties, :[], :[]=, :dig
+
+end # class Ladybug::Node

data/lib/ladybug/prepared_statement.rb

@@ -0,0 +1,44 @@
+# -*- ruby -*-
+
+require 'loggability'
+
+require 'ladybug' unless defined?( Ladybug )
+
+
+# A parameterized query which can avoid planning the same query for repeated execution
+class Ladybug::PreparedStatement
+	extend Loggability
+
+	# Loggability API -- Use Ladybug's logger
+	log_to :ladybug
+
+
+	### Execute the statement against its connection and return a Ladybug::Result.
+	### If a +block+ is supplied, the result will be passed to it instead,
+	### then finished automatically, and the return value of the block returned
+	### instead.
+	def execute( **bound_variables, &block )
+		self.log.debug "Executing statement:\n%s\nwith variables:\n%p" %
+			[ self.query, bound_variables ]
+		self.bind( **bound_variables )
+		result = self._execute
+		return Ladybug::Result.wrap_block_result( result, &block )
+	end
+
+
+	### Execute the statement against its connection and return `true` if it
+	### succeeded.
+	def execute!( **bound_variables )
+		self.bind( **bound_variables )
+		return self._execute!
+	end
+
+
+	### Bind the variables in the specified +variable_map+ to the statement.
+	def	bind( **variable_map )
+		variable_map.each do |name, value|
+			self.bind_variable( name, value )
+		end
+	end
+
+end # class Ladybug::PreparedStatement

data/lib/ladybug/query_summary.rb

@@ -0,0 +1,28 @@
+# -*- ruby -*-
+
+require 'loggability'
+
+require 'ladybug' unless defined?( Ladybug )
+
+
+# Kùzu query summary class
+class Ladybug::QuerySummary
+	extend Loggability
+
+
+	# Loggability API -- log to Ladybug's logger
+	log_to :ladybug
+
+
+	### Return a string representation of the receiver suitable for debugging.
+	def inspect
+		details = " compiling: %0.3fs  execution: %0.3fs" % [
+			self.compiling_time,
+			self.execution_time,
+		]
+
+		default = super
+		return default.sub( />/, details + '>' )
+	end
+
+end # class Ladybug::QuerySummary

data/lib/ladybug/recursive_rel.rb

@@ -0,0 +1,37 @@
+# -*- ruby -*-
+
+require 'forwardable'
+require 'loggability'
+
+require 'ladybug' unless defined?( Ladybug )
+
+
+# Ladybug recursive relationship class
+class Ladybug::RecursiveRel
+	extend Loggability,
+		Forwardable
+
+	# Loggability API -- log to Ladybug's logger
+	log_to :ladybug
+
+
+	### Create a new RecursiveRel with the given +nodes+ and +rels+.
+	def initialize( nodes, rels )
+		@nodes = nodes
+		@rels = rels
+	end
+
+
+	######
+	public
+	######
+
+	##
+	# The Array of Ladybug::Nodes in the chain
+	attr_reader :nodes
+
+	##
+	# The Array of Ladybug::Rels connecting the Nodes in the chain
+	attr_reader :rels
+
+end # class Ladybug::RecursiveRel

data/lib/ladybug/rel.rb

@@ -0,0 +1,57 @@
+# -*- ruby -*-
+
+require 'forwardable'
+require 'loggability'
+
+require 'ladybug' unless defined?( Ladybug )
+
+
+# Ladybug rel (relationship) class
+class Ladybug::Rel
+	extend Loggability,
+		Forwardable
+
+	# Loggability API -- log to Ladybug's logger
+	log_to :ladybug
+
+
+	### Create a new Rel with the given +id+, +src_id+, +dst_id+,
+    ### +label+, and +properties+.
+	def initialize( id, src_id, dst_id, label, **properties )
+		@id = id
+		@src_id = src_id
+		@dst_id = dst_id
+		@label = label
+		@properties = properties
+	end
+
+
+	######
+	public
+	######
+
+	##
+	# The internal id value of the given rel
+	attr_reader :id
+
+	##
+	# The internal id value of the source node
+	attr_reader :src_id
+
+	##
+	# The internal id value of the destination node
+	attr_reader :dst_id
+
+	##
+	# The label value of the given node
+	attr_reader :label
+
+	##
+	# The Hash of the Rel's properties, keyed by name as a Symbol
+	attr_reader :properties
+
+
+	# Allow direct access to properties
+	def_delegators :@properties, :[], :[]=, :dig
+
+end # class Ladybug::Rel

data/lib/ladybug/result.rb

@@ -0,0 +1,196 @@
+# -*- ruby -*-
+
+require 'loggability'
+
+require 'ladybug' unless defined?( Ladybug )
+
+
+# Kùzu query result class
+#
+# These objects contain one result set from either a Ladybug::Connection#query call
+# or Ladybug::PreparedStatement#execute. If there are multiple result sets, you can
+# fetch the next one by calling Ladybug::Result#next_set. You can use #has_next_set?
+# to test for a following set.
+#
+# Tuple values are converted to corresponding Ruby objects:
+#
+# | Ladybug Type       | Ruby Type                                       |
+# | --------------- | ----------------------------------------------- |
+# | +INT8+          | +Integer+                                       |
+# | +INT16+         | +Integer+                                       |
+# | +INT32+         | +Integer+                                       |
+# | +INT64+         | +Integer+                                       |
+# | +INT128+        | +Integer+                                       |
+# | +UINT8+         | +Integer+                                       |
+# | +UINT16+        | +Integer+                                       |
+# | +UINT32+        | +Integer+                                       |
+# | +UINT64+        | +Integer+                                       |
+# | +FLOAT+         | +Float+                                         |
+# | +DOUBLE+        | +Float+                                         |
+# | +DECIMAL+       | +Float+                                         |
+# | +BOOLEAN+       | +TrueClass+ or +FalseClass+                     |
+# | +UUID+          | +String+ (UTF-8 encoding)                       |
+# | +STRING+        | +String+ (UTF-8 encoding)                       |
+# | +NULL+          | +NilClass+                                      |
+# | +DATE+          | +Date+                                          |
+# | +TIMESTAMP+     | +Time+                                          |
+# | +INTERVAL+      | +Float+ (interval in seconds)                   |
+# | +STRUCT+        | +OpenStruct+ via the +ostruct+ standard library |
+# | +MAP+           | +Hash+                                          |
+# | +UNION+         | (not yet handled)                               |
+# | +BLOB+          | +String+ (+ASCII_8BIT+ encoding)                |
+# | +SERIAL+        | +Integer+                                       |
+# | +NODE+          | Ladybug::Node                                      |
+# | +REL+           | Ladybug::Rel                                       |
+# | +RECURSIVE_REL+ | Ladybug::RecursiveRel                              |
+# | +LIST+          | +Array+                                         |
+# | +ARRAY+         | +Array+                                         |
+#
+#
+class Ladybug::Result
+	extend Loggability
+
+
+	# Loggability API -- log to Ladybug's logger
+	log_to :ladybug
+
+
+	### Execute the given +query+ via the specified +connection+ and return the
+	### Ladybug::Result. If a block is given, the result will instead be yielded to it,
+	### finished when it returns, and the return value of the block will be returned
+	### instead.
+	def self::from_query( connection, query, &block )
+		return connection.query( query, &block )
+	end
+
+
+	### Execute the given +statement+ and return the Ladybug::Result. If a block is given,
+	### the result will instead be yielded to it, finished when it returns, and the
+	### return value of the block will be returned instead.
+	def self::from_prepared_statement( statement, &block )
+		return statement.execute( &block )
+	end
+
+
+	### If the +block+ is provided, yield +result+ to it and then call #finish on it,
+	### returning the +block+ result. If +block+ is not given, just return +result+.
+	def self::wrap_block_result( result, &block )
+		return result unless block
+
+		begin
+			rval = block.call( result )
+		ensure
+			result.finish
+		end
+
+		return rval
+	end
+
+
+	### Fetch the names of the columns in the result as an Array of Strings.
+	def	column_names
+		return @column_names ||= self.get_column_names
+	end
+
+
+	### Return a Ladybug::QuerySummary for the query that generated the Result.
+	def query_summary
+		return Ladybug::QuerySummary.from_result( self )
+	end
+
+
+	### Get the next tuple of the result as a Hash.
+	def next
+		values = self.get_next_values or return nil
+		pairs = self.column_names.zip( values )
+		return Hash[ pairs ]
+	end
+
+
+	### Iterate over each tuple of the result, yielding it to the +block+. If no
+	### +block+ is given, return an Enumerator that will yield them instead.
+	def	each( &block )
+		enum = self.tuple_enum
+		return enum.each( &block ) if block
+		return enum
+	end
+
+
+	### Return the tuples from the current result set. This method is memoized
+	### for efficiency.
+	def tuples
+		return @_tuples ||= self.to_a
+	end
+
+
+	### Index operator: fetch the tuple at +index+ of the current result set.
+	def []( index )
+		return self.tuples[ index ]
+	end
+
+
+	### Return the next result set after this one as a Ladybug::Result, or `nil`if
+	### there is no next set.
+	def next_set
+		return nil unless self.has_next_set?
+		return self.class.from_next_set( self )
+	end
+
+
+	### Iterate over each result set in the results, yielding it to the block. If
+	### no +block+ is given, return an Enumerator tht will yield each set as its own
+	### Result.
+	def each_set( &block )
+		enum = self.next_set_enum
+		return enum.each( &block ) if block
+		return enum
+	end
+
+
+	### Return a string representation of the receiver suitable for debugging.
+	def inspect
+		if self.finished?
+			details = " (finished)"
+		else
+			details = " success: %p (%d tuples of %d columns)" % [
+				self.success?,
+				self.num_tuples,
+				self.num_columns,
+			]
+		end
+
+		default = super
+		return default.sub( />/, details + '>' )
+	end
+
+
+	#########
+	protected
+	#########
+
+	### Return an Enumerator that yields result tuples as Hashes.
+	def tuple_enum
+		self.log.debug "Fetching a tuple Enumerator"
+		return Enumerator.new do |yielder|
+			self.reset_iterator
+			while self.has_next?
+				tuple = self.next
+				yielder.yield( tuple )
+			end
+		end
+	end
+
+
+	### Return an Enumerator that yields a Result for each set.
+	def next_set_enum
+		self.log.debug "Fetching a result set Enumerator"
+		result = self
+		return Enumerator.new do |yielder|
+			while result
+				yielder.yield( result )
+				result = result.next_set
+			end
+		end
+	end
+
+end # class Ladybug::Result

data/lib/ladybug.rb

@@ -0,0 +1,89 @@
+# -*- ruby -*-
+
+require 'ostruct'
+require 'pathname'
+require 'loggability'
+
+require_relative 'ladybug_ext'
+
+#--
+# See also: ext/ladybug_ext/ladybug_ext.c
+module Ladybug
+	extend Loggability
+
+
+	# Library version
+	VERSION = '0.1.0'
+
+
+	# Set up a logger for Ladybug classes
+	log_as :ladybug
+
+
+	### Create and return a Ladybug::Database. If +path+ is +nil+, an empty string, or
+	### the Symbol :memory, creates an in-memory database. Valid options are:
+	###
+	### `:buffer_pool_size`
+	### :    Max size of the buffer pool in bytes.
+	###
+	### `:max_num_threads`
+	### :    The maximum number of threads to use during query execution.
+	###
+	### `:enable_compression`
+	### :    Whether or not to compress data on-disk for supported types
+	###
+	### `:read_only`
+	### :    If true, open the database in read-only mode. No write transaction is allowed on the
+	### Database object. If false, open the database read-write.
+	###
+	### `:max_db_size`
+	###	:    The maximum size of the database in bytes.
+	###
+	### `:auto_checkpoint`
+	### :    If true, the database will automatically checkpoint when the size of
+	### the WAL file exceeds the checkpoint threshold.
+	###
+	### `:checkpoint_threshold`
+	### :    The threshold of the WAL file size in bytes. When the size of the
+	### WAL file exceeds this threshold, the database will checkpoint if
+	### `auto_checkpoint` is true.
+	def self::database( path='', **config )
+		path = '' if path.nil? || path == :memory
+		self.log.info "Opening database %p" % [ path ]
+		return Ladybug::Database.new( path.to_s, **config )
+	end
+
+
+	### Returns +true+ if the specified +pathname+ appears to be a valid Ladybug database
+	### for the current version of the storage format.
+	def self::is_database?( pathname )
+		pathname = Pathname( pathname )
+		return false unless pathname.file?
+		magic = pathname.read( 5 )
+		return magic[0, 4] == 'LBUG' && magic[4, 1].ord == Ladybug.storage_version
+	end
+	singleton_class.alias_method( :is_ladybug_database?, :is_database? )
+
+
+	### Return a Time object from the given +milliseconds+ epoch time.
+	def self::timestamp_from_timestamp_ms( milliseconds )
+		seconds, subsec = milliseconds.divmod( 1_000 )
+		return Time.at( seconds, subsec, :millisecond )
+	end
+
+
+	### Return a Time object from the given +microseconds+ epoch time and
+	### optional timezone offset in seconds via the +zone+ argument.
+	def self::timestamp_from_timestamp_us( microseconds, zone=nil )
+		seconds, subsec = microseconds.divmod( 1_000_000 )
+		return Time.at( seconds, subsec, :microsecond, in: zone )
+	end
+
+
+	### Return a Time object from the given +nanoseconds+ epoch time.
+	def self::timestamp_from_timestamp_ns( nanoseconds )
+		seconds, subsec = nanoseconds.divmod( 1_000_000_000 )
+		return Time.at( seconds, subsec, :nanosecond )
+	end
+
+end # module Ladybug

data/spec/ladybug/config_spec.rb

@@ -0,0 +1,98 @@
+# -*- ruby -*-
+
+require_relative '../spec_helper'
+
+require 'ladybug/config'
+
+
+RSpec.describe( Ladybug::Config ) do
+
+	it "can be created with defaults" do
+		result = described_class.new
+
+		expect( result ).to be_a( described_class )
+
+		expect( result.buffer_pool_size ).to be_a( Integer )
+		expect( result.max_num_threads ).to be_a( Integer )
+		expect( result.enable_compression ).to eq( true )
+		expect( result.read_only ).to eq( false )
+		expect( result.max_db_size ).to be_a( Integer )
+		expect( result.auto_checkpoint ).to eq( true )
+		expect( result.checkpoint_threshold ).to be_a( Integer )
+	end
+
+
+	it "can set its buffer_pool_size" do
+		instance = described_class.new
+
+		expect {
+			instance.buffer_pool_size = 2 ** 11
+		}.to change { instance.buffer_pool_size }.to( 2 ** 11 )
+	end
+
+
+	it "can set its max_num_threads" do
+		instance = described_class.new
+
+		expect {
+			instance.max_num_threads = 4
+		}.to change { instance.max_num_threads }.to( 4 )
+	end
+
+
+	it "can disable compression" do
+		instance = described_class.new
+
+		expect {
+			instance.enable_compression = false
+		}.to change { instance.enable_compression }.to( false )
+	end
+
+
+	it "can set read-only mode" do
+		instance = described_class.new
+
+		expect {
+			instance.read_only = true
+		}.to change { instance.read_only }.to( true )
+	end
+
+
+	it "can set read-only mode using a truthy value" do
+		instance = described_class.new
+
+		expect {
+			instance.read_only = :yep
+		}.to change { instance.read_only }.to( true )
+	end
+
+
+	it "can set its max_db_size" do
+		instance = described_class.new
+
+		expect {
+			instance.max_db_size = 2 ** 21
+		}.to change { instance.max_db_size }.to( 2 ** 21 )
+	end
+
+
+	it "can disable auto-checkpointing" do
+		instance = described_class.new
+
+		expect {
+			instance.auto_checkpoint = false
+		}.to change { instance.auto_checkpoint }.to( false )
+	end
+
+
+	it "can set its checkpoint threshold" do
+		instance = described_class.new
+
+		expect {
+			instance.checkpoint_threshold = 2 ** 22
+		}.to change { instance.checkpoint_threshold }.to( 2 ** 22 )
+	end
+
+
+end
+