ruby-kuzu 0.0.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9ef51b4e013cad8b7f0434db1a6fac89068681273f0d53981761c56a570628d
-  data.tar.gz: db7e93a8c4537f33cfa3bf77a6315ccb334f74d437869b2f053f1d479be7ee6b
+  metadata.gz: ffa06875d65096bb5bac251440d1f1ec56d233a7675f86b9e4d22a5039d91020
+  data.tar.gz: 4666b63219b97e6fcb8781995bbb71bbb486a09f8bdbbe763e6f4b225101750a
 SHA512:
-  metadata.gz: 2b70df49dbb9038ea0d02c0d6edb1e00c19ccfce943c464fd05efc55f6e848f110732aee64ce2910fc11107f1942fcfe5d8f19efd868bbffa5ceaeab8aaa7eae
-  data.tar.gz: 6633c48dd7c4cfad5b13de88b6123b7c7226dabcc2323a59831519db29b992f5efff9b48c946311934b96a3fffe8fe0ef17ca38afe3ba8f79094cc195ba2d880
+  metadata.gz: fd651f4b5f1267a5e1725cc692ca3554842d58c4cb71bb63498172de7d6fcef6df3d7855bbdba2aadd2f35a01482e73104ef2a9647bf4a8221b3dba63e821096
+  data.tar.gz: b65eb14735f2d06883cc4392e67e4cb208fb415ac9de62a24d1e686bad95fa7fb0412124ef01908ce587a223bc1bcb37688d8cb4df10564f888acde3192171bd

data/History.md

@@ -2,6 +2,31 @@
 
 ---
 
+## v0.2.0 [2025-07-16] Michael Granger <ged@FaerieMUD.org>
+
+Enhancements:
+
+- Add support for the SERIAL type.
+- Add Kuzu.is_database? method
+- Flesh out documentation
+
+Bugfixes:
+
+- Fixups for Linux and Kuzu 0.11
+- Fix storage version check (0.11+)
+- Fix a bug in Result#next
+- Fix Date type conversion
+
+
+## v0.1.0 [2025-06-17] Michael Granger <ged@FaerieMUD.org>
+
+Enhancements:
+
+- Add Connection#database
+- Squelch some warnings
+- Add Result#tuples and Result#[].
+
+
 ## v0.0.3 [2025-05-22] Michael Granger <ged@FaerieMUD.org>
 
 Fixes:

data/README.md

@@ -47,15 +47,129 @@ Once you have a Kuzu::Database object, you need a connection to actually use it:
     # => #<Kuzu::Connection:0x0000000122a41f28 threads:16>
 
 
-
 ### Querying
 
+There are two ways of running queries, immediate execution and via a prepared
+statement. Either method returns one or more results as Kuzu::Result objects.
+
+
 ### Results
 
+The each result of a query in a query string is returned as a Kuzu::Result. If
+there are more than one queries in the query string, the Results will be
+chained together so they can be iterated over.
+
+Each tuple in a Result can be fetched using Kuzu::Result#next, which returns a
+Hash of the variables in the `RETURN` clause, keyed by the column name as a
+`String`:
+
+    res = conn.query( 'MATCH (a:User)-[f:Follows]->(b:User) RETURN a.name, b.name, f.since;' )
+    # => #<Kuzu::Result:0x00000001268449d8 success: true (4 tuples of 3 columns)>
+    res.next
+    # => {"a.name" => "Adam", "b.name" => "Karissa", "f.since" => 2020}
+    res.next
+    # => {"a.name" => "Adam", "b.name" => "Zhang", "f.since" => 2020}
+
+The value's type will be determined by the Kuzu datatype of that column of the
+result. See Kuzu::Result for a mapping of the types.
+
+If there are more tuples to fetch, Kuzu::Result#has_next? will return `true`:
+
+    res.has_next?
+    # => true
+    res.next
+    # => {"a.name" => "Karissa", "b.name" => "Zhang", "f.since" => 2021}
+    res.next
+    # => {"a.name" => "Zhang", "b.name" => "Noura", "f.since" => 2022}
+    res.has_next?
+    # => false
+    res.next
+    # => nil
+
+Kuzu::Result is also Enumerable, so you can `#each` over its tuples:
+
+    res.each
+    # => #<Enumerator: ...>
+    res.map do |tuple|
+        "%s has followed %s since %s" % tuple.values_at('a.name', 'b.name', 'f.since')
+    end
+    # => ["Adam has followed Karissa since 2020",
+    #     "Adam has followed Zhang since 2020",
+    #     "Karissa has followed Zhang since 2021",
+    #     "Zhang has followed Noura since 2022"]
+
+If the query string has more than one query in it, a separate Kuzu::Result is
+linked to the previous one, and can be fetched using Kuzu::Result#next_set.
+
+For example:
+
+    res = conn.query( <<~END_OF_QUERY )
+        MATCH (a:User)-[f:Follows]->(b:User)
+        RETURN a.name, b.name, f.since;
+        MATCH (u:User) RETURN *
+    END_OF_QUERY
+    # => #<Kuzu::Result:0x000000011e6faaf8 success: true (4 tuples of 3 columns)>
+    res.to_a
+    # => [{"a.name" => "Adam", "b.name" => "Karissa", "f.since" => 2020},
+    #     {"a.name" => "Adam", "b.name" => "Zhang", "f.since" => 2020},
+    #     {"a.name" => "Karissa", "b.name" => "Zhang", "f.since" => 2021},
+    #     {"a.name" => "Zhang", "b.name" => "Noura", "f.since" => 2022}]
+    res.has_next_set?
+    # => true
+    res2 = res.next_set
+    # => #<Kuzu::Result:0x000000011e338fa0 success: true (4 tuples of 1 columns)>
+    res2.to_a
+    # => [{"u" => #<Kuzu::Node:0x000000011e7553b8 @id=[0, 0], @label="User",
+    #       @properties={name: "Adam", age: 30}>},
+    #     {"u" => #<Kuzu::Node:0x000000011e7551b0 @id=[0, 1], @label="User",
+    #       @properties={name: "Karissa", age: 40}>},
+    #     {"u" => #<Kuzu::Node:0x000000011e755048 @id=[0, 2], @label="User",
+    #       @properties={name: "Zhang", age: 50}>},
+    #     {"u" => #<Kuzu::Node:0x000000011e754ee0 @id=[0, 3], @label="User",
+    #       @properties={name: "Noura", age: 25}>}]
+    res2.has_next_set?
+    # => false
+    res2.next_set
+    # => nil
+
+
 ### Prepared Statements
 
-### Datatypes
+An alternative to using strings to query the database is to used *prepared statements*. These have a number of advantages, such as reusability and using parameters for queries instead of string interpolation.
+
+You can create a Kuzu::PreparedStatement by calling Kuzu::Connection#prepare, then execute it one or more times with parameters using Kuzu::PreparedStatement#execute:
+
+    stmt = conn.prepare( <<~END_OF_QUERY )
+      MATCH (a:User)-[f:Follows]->(b:User)
+      WHERE a.name = $name
+      RETURN a.name, b.name, f.since'
+    END_OF_QUERY
+    # => #<Kuzu::PreparedStatement:0x000000011e919b68>
+    res = stmt.execute( name: "Karissa" )
+    # => #<Kuzu::Result:0x000000011ee8df90 success: true (1 tuples of 3 columns)>
+    res.to_a
+    # => [{"a.name" => "Karissa", "b.name" => "Zhang", "f.since" => 2021}]
+
 
+### Result Memory Management
+
+Because of the way Ruby frees memory when it's shutting down (i.e., the order is indeterminate), Kuzu::Result objects may not be freed immediately when they go out of scope. To provide some way to manage this, the Kuzu::Result#finish call is provided as a way to explicitly destroy the underlying Kuzu data structure so the Result can be freed. Since this is somewhat inconvenient to manage, there are two forms of Kuzu::Connection#query and Kuzu::PreparedStatement#execute, one which returns a Result and a "bang" equivalent one which just returns success or failure. Additionally, passing a block to either method will yield the Result to the block and then immediately `finish` the Result for you and return the block's value.
+
+    query_string = 'MATCH (a:User)-[f:Follows]->(b:User) RETURN a.name, b.name, f.since'
+    conn.query!( query_string )
+    # => true
+    conn.query( query_string ) {|res| res.tuples }
+    # => [{"a.name" => "Adam", "b.name" => "Karissa", "f.since" => 2020},
+    #     {"a.name" => "Adam", "b.name" => "Zhang", "f.since" => 2020},
+    #     {"a.name" => "Karissa", "b.name" => "Zhang", "f.since" => 2021},
+    #     {"a.name" => "Zhang", "b.name" => "Noura", "f.since" => 2022}]
+
+    stmt = conn.prepare( "CREATE (:User {name: $name, age: $age})" )
+    # => #<Kuzu::PreparedStatement:0x000000010bc7cfe8>
+    stmt.execute!( name: 'David', age: 19 )
+    # => true
+    stmt.execute!( name: 'Agnes', age: 28 )
+    # => true
 
 
 ## Examples
@@ -64,26 +178,36 @@ Once you have a Kuzu::Database object, you need a connection to actually use it:
 
     db = Kuzu.database
     conn = db.connect
-    conn.query("CREATE NODE TABLE User(name STRING, age INT64, PRIMARY KEY (name))")
-    conn.query("CREATE NODE TABLE City(name STRING, population INT64, PRIMARY KEY (name))")
-    conn.query("CREATE REL TABLE Follows(FROM User TO User, since INT64)")
-    conn.query("CREATE REL TABLE LivesIn(FROM User TO City)")
+    conn.run("CREATE NODE TABLE User(name STRING, age INT64, PRIMARY KEY (name))")
+    conn.run("CREATE NODE TABLE City(name STRING, population INT64, PRIMARY KEY (name))")
+    conn.run("CREATE REL TABLE Follows(FROM User TO User, since INT64)")
+    conn.run("CREATE REL TABLE LivesIn(FROM User TO City)")
 
     # Load data.
-    conn.query("COPY User FROM \"user.csv\"")
-    conn.query("COPY City FROM \"city.csv\"")
-    conn.query("COPY Follows FROM \"follows.csv\"")
-    conn.query("COPY LivesIn FROM \"lives-in.csv\"")
+    conn.run("COPY User FROM \"user.csv\"")
+    conn.run("COPY City FROM \"city.csv\"")
+    conn.run("COPY Follows FROM \"follows.csv\"")
+    conn.run("COPY LivesIn FROM \"lives-in.csv\"")
 
     # Execute a simple query.
     result = conn.query("MATCH (a:User)-[f:Follows]->(b:User) RETURN a.name, f.since, b.name;")
 
     # Output query result.
     result.each do |tuple|
-        name, since, name2 = tuple.values_at( :a_name, :f_since, :b_name )
+        name, since, name2 = tuple.values_at( 'a.name', 'f.since', 'b.name' )
         puts "%s follows %s since %lld", [ name, name2, since ]
     end
 
+    result.finish
+
+
+## To-Do List
+
+- `UNION` result type.
+- `JSON` result type from the JSON extension
+- Better memory management for Kuzu::Results
+
+
 ## Requirements
 
 - Ruby >= 3

data/ext/kuzu_ext/connection.c

@@ -170,7 +170,10 @@ rkuzu_connection_do_query( VALUE self, VALUE query )
 		rkuzu_connection_do_query_without_gvl, (void *)&qcall,
 		rkuzu_connection_cancel_query, (void *)&conn->conn );
 
+	_Pragma("GCC diagnostic push")
+	_Pragma("GCC diagnostic ignored \"-Wvoid-pointer-to-enum-cast\"")
 	query_state = (kuzu_state)result_ptr;
+	_Pragma("GCC diagnostic pop")
 
 	if ( query_state != KuzuSuccess ) {
 		char *err_detail = kuzu_query_result_get_error_message( &result );
@@ -278,6 +281,21 @@ rkuzu_connection_query_timeout_eq( VALUE self, VALUE timeout )
 }
 
 
+/*
+ * call-seq:
+ *    connection.database              -> database
+ *
+ * Return the database object the connection belongs to (a Kuzu::Database).
+ *
+ */
+static VALUE
+rkuzu_connection_database( VALUE self )
+{
+	rkuzu_connection *ptr = CHECK_CONNECTION( self );
+	return ptr->database;
+}
+
+
 
 /*
  * Document-class: Kuzu::Connection
@@ -306,5 +324,8 @@ rkuzu_init_connection( void )
 
 	rb_define_method( rkuzu_cKuzuConnection, "query_timeout=", rkuzu_connection_query_timeout_eq, 1 );
 
+	rb_define_method( rkuzu_cKuzuConnection, "database", rkuzu_connection_database, 0 );
+	rb_define_alias( rkuzu_cKuzuConnection, "db", "database" );
+
 	rb_require( "kuzu/connection" );
 }

data/ext/kuzu_ext/kuzu_ext.h

@@ -28,8 +28,10 @@
 #ifdef HAVE_STDARG_PROTOTYPES
 #include <stdarg.h>
 #define va_init_list(a, b) va_start (a, b)
-void rkuzu_log_obj (VALUE, const char *, const char *, ...);
-void rkuzu_log (const char *, const char *, ...);
+void rkuzu_log_obj (VALUE, const char *, const char *, ...)
+	__attribute__ ((format (printf, 2, 0)));
+void rkuzu_log (const char *, const char *, ...)
+	__attribute__ ((format (printf, 1, 0)));
 #else
 #include <varargs.h>
 #define va_init_list(a, b) va_start (a)

data/ext/kuzu_ext/prepared_statement.c

@@ -43,7 +43,7 @@ rkuzu_get_prepared_statement( VALUE prepared_statement_obj )
  * Allocation function
  */
 static rkuzu_prepared_statement *
-rkuzu_prepared_statement_alloc()
+rkuzu_prepared_statement_alloc( void )
 {
 	rkuzu_prepared_statement *ptr = ALLOC( rkuzu_prepared_statement );
 
@@ -181,7 +181,11 @@ rkuzu_prepared_statement_do_execute( VALUE self )
 	result_ptr = rb_thread_call_without_gvl(
 		rkuzu_connection_do_execute_without_gvl, (void *)&qcall,
 		rkuzu_connection_cancel_execute, (void *)&conn->conn );
+
+	_Pragma("GCC diagnostic push")
+	_Pragma("GCC diagnostic ignored \"-Wvoid-pointer-to-enum-cast\"")
 	execute_state = (kuzu_state)result_ptr;
+	_Pragma("GCC diagnostic pop")
 
 	if ( execute_state != KuzuSuccess ) {
 		char *err_detail = kuzu_query_result_get_error_message( &result );

data/ext/kuzu_ext/query_summary.c

@@ -51,7 +51,7 @@ rkuzu_query_summary_s_allocate( VALUE klass )
  * call-seq:
  *    Kuzu::QuerySummary.from_result( result )   -> query_summary
  *
- * Return a Kuzu::QuerySummary from a Kuzu::QueryResult.
+ * Return a Kuzu::QuerySummary from a Kuzu::Result.
  *
  */
 static VALUE

data/ext/kuzu_ext/result.c

@@ -408,7 +408,7 @@ rkuzu_result_get_column_names( VALUE self )
 
 	for ( uint64_t i = 0 ; i < col_count ; i++ ) {
 		if ( kuzu_query_result_get_column_name(&result->result, i, &name) != KuzuSuccess ) {
-			rb_raise( rkuzu_eError, "couldn't fetch name of column %llu", i );
+			rb_raise( rkuzu_eError, "couldn't fetch name of column %lu", i );
 		}
 		rb_ary_push( rval, rb_str_new2(name) );
 	}

data/ext/kuzu_ext/types.c

@@ -165,8 +165,8 @@ rkuzu_convert_date( kuzu_value *value )
 
 	kuzu_date_to_tm( typed_value, &time );
 
-	argv[0] = INT2FIX( time.tm_year );
-	argv[1] = INT2FIX( time.tm_mon );
+	argv[0] = INT2FIX( time.tm_year + 1900 );
+	argv[1] = INT2FIX( time.tm_mon  + 1 );
 	argv[2] = INT2FIX( time.tm_mday );
 
 	return rb_class_new_instance( 3, argv, rkuzu_rb_cDate );
@@ -554,6 +554,9 @@ rkuzu_convert_kuzu_value_to_ruby( kuzu_data_type_id type_id, kuzu_value *value )
 		case KUZU_UINT8: return rkuzu_convert_uint8( value );
 		case KUZU_INT128: return rkuzu_convert_int128( value );
 
+		// Serials just come out as int64s
+		case KUZU_SERIAL: return rkuzu_convert_int64( value );
+
 		case KUZU_DOUBLE: return rkuzu_convert_double( value );
 		case KUZU_FLOAT: return rkuzu_convert_float( value );
 

data/lib/kuzu/prepared_statement.rb

@@ -18,6 +18,8 @@ class Kuzu::PreparedStatement
 	### 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 Kuzu::Result.wrap_block_result( result, &block )

data/lib/kuzu/result.rb

@@ -6,6 +6,47 @@ require 'kuzu' unless defined?( Kuzu )
 
 
 # Kùzu query result class
+#
+# These objects contain one result set from either a Kuzu::Connection#query call
+# or Kuzu::PreparedStatement#execute. If there are multiple result sets, you can
+# fetch the next one by calling Kuzu::Result#next_set. You can use #has_next_set?
+# to test for a following set.
+#
+# Tuple values are converted to corresponding Ruby objects:
+#
+# | Kuzu 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+          | Kuzu::Node                                      |
+# | +REL+           | Kuzu::Rel                                       |
+# | +RECURSIVE_REL+ | Kuzu::RecursiveRel                              |
+# | +LIST+          | +Array+                                         |
+# | +ARRAY+         | +Array+                                         |
+#
+#
 class Kuzu::Result
 	extend Loggability
 
@@ -60,7 +101,8 @@ class Kuzu::Result
 
 	### Get the next tuple of the result as a Hash.
 	def next
-		pairs = self.column_names.zip( self.get_next_values )
+		values = self.get_next_values or return nil
+		pairs = self.column_names.zip( values )
 		return Hash[ pairs ]
 	end
 
@@ -74,6 +116,19 @@ class Kuzu::Result
 	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 Kuzu::Result, or `nil`if
 	### there is no next set.
 	def next_set
@@ -97,11 +152,10 @@ class Kuzu::Result
 		if self.finished?
 			details = " (finished)"
 		else
-			details = " success: %p (%d tuples of %d columns): %s" % [
+			details = " success: %p (%d tuples of %d columns)" % [
 				self.success?,
 				self.num_tuples,
 				self.num_columns,
-				self.to_s,
 			]
 		end
 
@@ -116,6 +170,7 @@ class Kuzu::Result
 
 	### 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?
@@ -126,7 +181,9 @@ class Kuzu::Result
 	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

data/lib/kuzu.rb

@@ -1,5 +1,6 @@
 # -*- ruby -*-
 
+require 'pathname'
 require 'loggability'
 
 require_relative 'kuzu_ext'
@@ -11,7 +12,10 @@ module Kuzu
 
 
 	# Library version
-	VERSION = '0.0.3'
+	VERSION = '0.2.0'
+
+	# Name of the file to look for when testing a path to see if it's a Kuzu database.
+	KUZU_CATALOG_FILENAME = 'data.kz'
 
 
 	# Set up a logger for Kuzu classes
@@ -52,6 +56,23 @@ module Kuzu
 	end
 
 
+	### Returns +true+ if the specified +pathname+ appears to be a valid Kuzu database
+	### for the current version of the storage format.
+	def self::is_database?( pathname )
+		pathname = Pathname( pathname )
+		if Kuzu.storage_version <= 38
+			return false unless pathname.directory?
+			testfile = pathname / KUZU_CATALOG_FILENAME
+			return testfile.exist?
+		else
+			return false unless pathname.file?
+			magic = pathname.read( 5 )
+			return magic[0, 4] == 'KUZU' && magic[4, 1].ord == Kuzu.storage_version
+		end
+	end
+	singleton_class.alias_method( :is_kuzu_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 )
@@ -74,4 +95,3 @@ module Kuzu
 	end
 
 end # module Kuzu
-

data/spec/kuzu/connection_spec.rb

@@ -0,0 +1,36 @@
+# -*- ruby -*-
+
+require_relative '../spec_helper'
+
+require 'kuzu/connection'
+
+
+RSpec.describe( Kuzu::Connection ) do
+
+	let( :db ) { Kuzu.database }
+
+
+	it "can set the maximum number of threads for execution" do
+		connection = db.connect
+
+		expect {
+			connection.max_num_threads_for_exec += 1
+		}.to change { connection.max_num_threads_for_exec }.by( 1 )
+	end
+
+
+	it "shows the number of threads used for execution when inspected" do
+		connection = db.connect
+
+		expect( connection.inspect ).to match( /threads:\d+/i )
+	end
+
+
+	it "knows what database it's a connection for" do
+		connection = db.connect
+
+		expect( connection.database ).to eq( db )
+	end
+
+end
+

data/spec/kuzu/database_spec.rb

@@ -8,12 +8,18 @@ require 'kuzu/database'
 RSpec.describe( Kuzu::Database ) do
 
 	let( :spec_tmpdir ) do
-		tmpfile_pathname()
+		path = tmpfile_pathname()
+		path.mkpath
+		return path
 	end
 
 	let( :db_path ) { spec_tmpdir + 'spec_db' }
 
 
+	after( :each ) do
+		GC.start
+	end
+
 	it "can be created in-memory" do
 		instance = described_class.new( '' )
 		expect( instance ).to be_a( described_class )
@@ -21,7 +27,7 @@ RSpec.describe( Kuzu::Database ) do
 
 
 	it "can be created read-only from an existing on-disk database" do
-		original = described_class.new( db_path.to_s )
+		_original = described_class.new( db_path.to_s )
 
 		ro = described_class.new( db_path.to_s, read_only: true )
 		expect( ro ).to be_read_only

data/spec/kuzu/result_spec.rb

@@ -78,7 +78,7 @@ RSpec.describe( Kuzu::Result ) do
 			expect( result ).to be_success
 			expect( result.num_columns ).to eq( 3 )
 			expect( result.column_names ).to eq([ "a.name", "b.name", "f.since" ])
-			expect( result.each.to_a ).to eq([
+			expect( result.to_a ).to eq([
 				{ "a.name" => "Adam", "b.name" => "Karissa", "f.since" => 2020 },
 				{ "a.name" => "Adam", "b.name" => "Zhang", "f.since" => 2020 },
 				{ "a.name" => "Karissa", "b.name" => "Zhang", "f.since" => 2021 },
@@ -89,6 +89,41 @@ RSpec.describe( Kuzu::Result ) do
 		end
 
 
+		it "handles a #next after it finishes iteration over the current set" do
+			setup_demo_db()
+
+			result = described_class.from_query( connection, <<~END_OF_QUERY )
+				MATCH ( a:User )-[ f:Follows ]->( b:User )
+			    RETURN a.name, b.name, f.since;
+			END_OF_QUERY
+
+			result.tuples # Iterate over all tuples
+
+			expect( result.next ).to be_nil
+
+			result.finish
+		end
+
+
+		it "can fetch individual result tuples via the index operator" do
+			setup_demo_db()
+
+			result = described_class.from_query( connection, <<~END_OF_QUERY )
+				MATCH ( a:User )-[ f:Follows ]->( b:User )
+			    RETURN a.name, b.name, f.since;
+			END_OF_QUERY
+
+			tuples = result.to_a
+
+			expect( result[0] ).to eq( tuples[0] )
+			expect( result[1] ).to eq( tuples[1] )
+			expect( result[2] ).to eq( tuples[2] )
+			expect( result[3] ).to eq( tuples[3] )
+
+			result.finish
+		end
+
+
 		it "can iterate over result sets" do
 			result = described_class.from_query( connection, <<~END_QUERY )
 				return 1;
@@ -97,7 +132,7 @@ RSpec.describe( Kuzu::Result ) do
 			END_QUERY
 
 			rval = result.each_set.flat_map do |subset|
-				subset.each.to_a
+				subset.to_a
 			end
 
 			expect( rval ).to eq([

data/spec/kuzu/types_spec.rb

@@ -34,6 +34,25 @@ RSpec.describe( "data types" ) do
 	end
 
 
+	it "coverts DATE values to Date objects" do
+		result = connection.query( %{RETURN CAST('2025-07-14', 'DATE') as x;} )
+
+		expect( result ).to be_a( Kuzu::Result )
+		expect( result ).to be_success
+
+		value = result.first
+		expect( value ).to include( 'x' )
+
+		x = value['x']
+		expect( x ).to be_a( Date )
+		expect( x.year ).to eq( 2025 )
+		expect( x.month ).to eq( 7 )
+		expect( x.day ).to eq( 14 )
+
+		result.finish
+	end
+
+
 	it "converts STRUCT values to OpenStructs" do
 		result = connection.query( "RETURN {first: 'Adam', last: 'Smith'} AS record;" )
 
@@ -251,4 +270,15 @@ RSpec.describe( "data types" ) do
 	end
 
 
+	it "converts SERIAL types to Integer objects" do
+		result = connection.query( %{RETURN CAST(133, "SERIAL") AS s;} )
+		rval = result.first['s']
+
+		expect( rval ).to be_an( Integer )
+		expect( rval ).to eq( 133 )
+
+		result.finish
+	end
+
+
 end

data/spec/kuzu_spec.rb

@@ -7,7 +7,9 @@ require 'kuzu'
 RSpec.describe( Kuzu ) do
 
 	let( :spec_tmpdir ) do
-		tmpfile_pathname()
+		path = tmpfile_pathname()
+		path.mkpath
+		return path
 	end
 
 
@@ -49,7 +51,33 @@ RSpec.describe( Kuzu ) do
 		result = described_class.database( filename )
 
 		expect( result ).to be_a( Kuzu::Database )
-		expect( filename ).to be_a_directory
+		if Kuzu.storage_version <= 38
+			expect( filename ).to be_a_directory
+		else
+			expect( filename ).to be_a_file
+		end
+	end
+
+
+	it "can tell whether a string looks like a path to a Kuzu database" do
+		path = spec_tmpdir + 'spec_db'
+
+		expect {
+			described_class.database( path )
+		}.to change {
+			described_class.is_database?( path.to_s )
+		}.from( false ).to( true )
+	end
+
+
+	it "can tell whether a Pathname looks like a path to a Kuzu database" do
+		path = spec_tmpdir + 'spec_db'
+
+		expect {
+			described_class.database( path )
+		}.to change {
+			described_class.is_database?( path )
+		}.from( false ).to( true )
 	end
 
 end

data/spec/spec_helper.rb

@@ -54,7 +54,7 @@ module Kuzu::SpecHelpers
 
 	### Return a Pathname pointing to a temporary file.
 	def tmpfile_pathname( filetype='spec' )
-		Pathname(Dir::Tmpname.create(['kuzu-', '-test-' + filetype]) {})
+		return Pathname( Dir::Tmpname.create(['kuzu-', '-test-' + filetype]) {} )
 	end
 
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-kuzu
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Michael Granger
@@ -34,7 +34,7 @@ cert_chain:
   8qAqdfV+4u6Huu1KzAuDQCheyEyISsLST37sU/irV3czV6BiFipWag1XiJciRT3A
   wZqCfTNVHTdtsCbfdA1DsA3RdG2iEH3TOHzv1Rqzqh4=
   -----END CERTIFICATE-----
-date: 2025-05-22 00:00:00.000000000 Z
+date: 2025-07-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake-compiler
@@ -127,6 +127,7 @@ files:
 - lib/kuzu/rel.rb
 - lib/kuzu/result.rb
 - spec/kuzu/config_spec.rb
+- spec/kuzu/connection_spec.rb
 - spec/kuzu/database_spec.rb
 - spec/kuzu/prepared_statement_spec.rb
 - spec/kuzu/query_summary_spec.rb
@@ -157,7 +158,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A Ruby binding for the Kùzu embedded graph database.
 test_files: []

metadata.gz.sig

@@ -1,2 +1,3 @@
-zA���H_��8PT�%�9��T[:��l���mࡷ�a�U^��2��l�D��5�v�tv��O�h6f��E$"�ӡ���U�pWE�gCR7��.�鉐���蘩q���K��l��>#�m���~���C�*X+�0�R�mb��QĬ�	N���
o������T�{�J��%��eø6�v�3O��
�b>��§����i@���j����0>�)�}E�^�!$d�8y�h)�2�(~��"��4cO��wrB	�.m-��[��Ż��9;¹fa��3L{I���k���!-c�S͘L��A�^���� n��y��	��N�E��ٻ(��!Wl`�+Ǐ
-r��NS�Xt� 6P����U}ޅ�
�.dN
+J�DZ#\A3��K���&��E����Q���dEcߋM� 9��8S�����Y��"_���'����N����A'8S�V 8��(�u��y�}bO��ҹG�ņ���C˽h؇�4��S� \�.�)9
+���{��~86�#+�tu����R�����_�}x��<gx8�;)a����U��%��
+|��r�7˫�<}nVt�ml�SN�%Ѳ��4������j��F���n^M���������ZG��0N��D��󔹰���N���8�ϔU��u�����P�g�q��
qf�h�C��c�?2�A�owe�#�.