neo4j_bolt 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9f38fc0e16014ae13f2f31d2ba77f119185249821da7d4f7858fa0ef3f9010f
-  data.tar.gz: 5ab718f1dd9829aa1f118a6614f7d29d184d63eb20b4ce7d3e36fc92fea5f204
+  metadata.gz: 865849878d27a8936cb83b5d6567b2ef5d4256f422dc716cc0d496fcdfa31657
+  data.tar.gz: e3d4d1b1a57214d0ef7f99c75cd6a76c9a0c2fbb187fb02bb815b821f5dbc4b2
 SHA512:
-  metadata.gz: df61ebc16c46698ccab04c94e9a8abd6120ef07d899b7e52e8e9a80d13bcc4b2f8d17bddff330f6d10ff794faabd705ebfba3d3531fdad311cb8ea5de02dbc8c
-  data.tar.gz: 6522b70e44f279f182c289ae3397dafd11d5dff4e72a3437247a5f25bd66d4185e6696b2aa2c96bce976f518d63a30c98c48ea86b2823d28383c3989df24b7eb
+  metadata.gz: 36b289414eaed0af1eb8b628863e7d2f8cd88155377c0104bff8dc4edfda3e12bdf6157ed61e832be04856bb7cffe37d8be96a5d7c6ae5dac01d50a4fb6a75c5
+  data.tar.gz: 2fe7a4858a2c03f1b96e9260d93d85e77bdfef60f05fe0c1a2793b7c125e3e0d3db35902ec07ba6fc9cec4ce15cc02d2b8bb7cfad75c7d73503bf612a890ed38

data/README.md

@@ -4,14 +4,14 @@ Neo4jBolt 0.4 is a small compatibility and convenience layer for Ruby applicatio
 
 Neo4jBolt no longer implements the Bolt wire protocol itself.
 
-`0.5.0` requires Ruby 3.4 or newer and pins `neo4j-ruby-driver` to `6.2.1.beta.4`. Applications on older Rubies can remain on the Neo4jBolt 0.3.x line; this prerelease is intentionally not an automatic upgrade for them.
+`0.5.1` requires Ruby 3.4 or newer and pins `neo4j-ruby-driver` to `6.2.1.beta.4`. Applications on older Rubies can remain on the Neo4jBolt 0.3.x line; this prerelease is intentionally not an automatic upgrade for them.
 
 ## Installation
 
 For this prerelease, specify the version explicitly:
 
 ```ruby
-gem "neo4j_bolt", "0.5.0"
+gem "neo4j_bolt", "0.5.1"
 ```
 
 Then run `bundle install`. A running Neo4j database is required.
@@ -218,6 +218,8 @@ neo4j_bolt dump --data-only -o data.dump
 neo4j_bolt load --data-only database.dump
 ```
 
+Property values that JSON cannot express keep their type: dates, datetimes, local datetimes, local times, times, durations and points are written as maps tagged with `"$neo4j"`, for example `{"$neo4j":"date","value":"1815-12-10"}`, carrying the driver's own fields so that loading restores the exact value, and a readable `value` where there is one. Neo4j properties are never maps, so a tagged map cannot clash with an ordinary value; older dumps, which wrote such values as strings, still load as before. A datetime with a named zone (`[Europe/Berlin]`) comes back with its offset only, as the driver reads it that way.
+
 The `0, 1, 2, ...` IDs are synthetic dump-local IDs. Database-internal IDs and element IDs are never written to the persistent format. Dumping keeps the count, node, and relationship reads in one transaction, so the driver-provided entity identity used to connect the two streamed result sets stays within Neo4j's transaction-scoped identity guarantee. To keep dump numbering deterministic, ordering uses `elementId()` on modern Neo4j and an internal `id()` fallback only on Neo4j 4.4, where `elementId()` does not exist. Old Neo4jBolt dumps containing only `n` and `r` records remain loadable.
 
 For relational loads, the adapter assigns a random temporary label and the fixed reserved property `__neo4j_bolt_load_id` to imported nodes. After the nodes are committed it builds a temporary `neo4j_bolt_` index on that property, uses indexed lookups while creating relationships, drops the index, and removes the temporary metadata in batches. The fixed property key is reused by every load instead of registering a new random property-key token each time. Neo4j can keep the property key registered after all values have been removed, so it may remain visible in Browser's property-key list; no imported node retains the property after successful cleanup. Relational loads refuse to run if the dump itself, or existing data during `force_append`, currently uses the reserved property. No database-internal identity is carried from one load transaction to another. Loading a relational dump therefore requires permission to create and drop an index.
@@ -257,7 +259,7 @@ The complete integration suite is run against both Community and Enterprise for
 - `neo4j:2026.06.0-community`
 - `neo4j:2026.06.0-enterprise`
 
-No compatibility beyond this matrix is claimed for `0.5.0`.
+No compatibility beyond this matrix is claimed for `0.5.1`.
 
 Enterprise test containers are started with `NEO4J_ACCEPT_LICENSE_AGREEMENT=yes`. The Community targets verify that Community-compatible features remain portable; the Enterprise targets additionally exercise successful node-key dump/load instead of merely observing that Community rejects node keys.
 
@@ -297,6 +299,10 @@ To point RSpec itself at an already disposable database, set `NEO4J_BOLT_TEST_HO
 | CLI commands | Preserved |
 | `BoltSocket`, `BoltBuffer`, protocol markers/state/parser/packer | Intentionally removed private implementation details |
 
+## 0.5.1
+
+- Dumps keep dates, datetimes, local datetimes, local times, times, durations and points; before, they were written as text and came back as strings. Older dumps load as before.
+
 ## 0.5.0 migration notes
 
 - Ruby 3.4 or newer is required; Ruby 2.x/3.0–3.3 applications should stay on 0.3.x until upgraded.

data/lib/neo4j_bolt/version.rb

@@ -1,3 +1,3 @@
 module Neo4jBolt
-    VERSION = "0.5.0"
+    VERSION = "0.5.1"
 end

data/lib/neo4j_bolt.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
+require "date"
 require "json"
 require "securerandom"
 require "set"
 require "thread"
+require "time"
 require "uri"
 require "neo4j/driver"
 require "neo4j_bolt/version"
@@ -20,6 +22,10 @@ module Neo4jBolt
   LOAD_PROGRESS_STEP = 5_000
   DUMP_PROGRESS_STEP = 1_000
   LOAD_ID_PROPERTY = "__neo4j_bolt_load_id"
+  # Dumps write temporal and spatial property values as maps tagged with
+  # this key. Neo4j properties are never maps, so a tagged map cannot be an
+  # ordinary value, and dumps without such values read as before.
+  DUMP_TYPE_KEY = "$neo4j"
   private_constant :LOAD_MEMORY_ERROR_CODES, :LOAD_MEMORY_GQL_STATUSES,
                    :LOAD_PROGRESS_STEP, :DUMP_PROGRESS_STEP, :LOAD_ID_PROPERTY
 
@@ -618,7 +624,7 @@ module Neo4jBolt
         "ORDER BY #{identity_function}(n)"
       ) do |row|
         dump_ids[row["identity"].to_s] = dumped_nodes if dump_ids
-        io.puts "n #{JSON.generate(id: dumped_nodes, labels: row["labels"], properties: row["properties"])}"
+        io.puts "n #{JSON.generate(id: dumped_nodes, labels: row["labels"], properties: encode_dump_properties(row["properties"]))}"
         dumped_nodes += 1
         if (dumped_nodes % DUMP_PROGRESS_STEP).zero?
           progress.update(progress_message(
@@ -638,7 +644,7 @@ module Neo4jBolt
             from: dump_ids.fetch(row["from_identity"].to_s),
             to: dump_ids.fetch(row["to_identity"].to_s),
             type: row["type"],
-            properties: row["properties"]
+            properties: encode_dump_properties(row["properties"])
           )}"
           dumped_relationships += 1
           if (dumped_relationships % DUMP_PROGRESS_STEP).zero?
@@ -1098,6 +1104,73 @@ module Neo4jBolt
     version.to_s.split(".").first.to_i >= 5 ? "elementId" : "id"
   end
 
+  # Property values for a dump: JSON values as they are; dates, times,
+  # durations and points as maps tagged with DUMP_TYPE_KEY that carry the
+  # driver's own fields (so that loading restores the exact value) and, for
+  # people reading the dump, the value as text.
+  def encode_dump_properties(properties)
+    return properties unless properties.is_a?(Hash)
+
+    properties.to_h { |key, value| [key, encode_dump_value(value)] }
+  end
+
+  def encode_dump_value(value)
+    tagged = ->(type, fields) { { DUMP_TYPE_KEY => type }.merge(fields) }
+    case value
+    when Array
+      value.map { |item| encode_dump_value(item) }
+    when Time
+      tagged.call("datetime", "value" => value.iso8601(9))
+    when DateTime
+      tagged.call("datetime", "value" => value.to_time.iso8601(9))
+    when Date
+      tagged.call("date", "value" => value.iso8601)
+    when Neo4j::Driver::Types::LocalDateTime
+      tagged.call("local_datetime", "epoch_seconds" => value.epoch_seconds, "nanoseconds" => value.nanoseconds,
+                  "value" => value.to_s)
+    when Neo4j::Driver::Types::LocalTime
+      tagged.call("local_time", "nanoseconds" => value.nanoseconds, "value" => value.to_s)
+    when Neo4j::Driver::Types::OffsetTime
+      tagged.call("time", "nanoseconds" => value.nanoseconds, "tz_offset_seconds" => value.tz_offset_seconds,
+                  "value" => value.to_s)
+    when Neo4j::Driver::Types::Duration
+      tagged.call("duration", "months" => value.months, "days" => value.days, "seconds" => value.seconds,
+                  "nanoseconds" => value.nanoseconds, "value" => value.to_s)
+    when Neo4j::Driver::Types::Point
+      tagged.call("point", { "srid" => value.srid, "x" => value.x, "y" => value.y, "z" => value.z }.compact)
+    else
+      value
+    end
+  end
+
+  def decode_dump_properties(properties)
+    return properties unless properties.is_a?(Hash)
+
+    properties.to_h { |key, value| [key, decode_dump_value(value)] }
+  end
+
+  def decode_dump_value(value)
+    return value.map { |item| decode_dump_value(item) } if value.is_a?(Array)
+    return value unless value.is_a?(Hash) && value.key?(DUMP_TYPE_KEY)
+
+    case value[DUMP_TYPE_KEY]
+    when "datetime" then Time.iso8601(value.fetch("value"))
+    when "date" then Date.iso8601(value.fetch("value"))
+    when "local_datetime"
+      Neo4j::Driver::Types::LocalDateTime.new(value.fetch("epoch_seconds"), value.fetch("nanoseconds"))
+    when "local_time" then Neo4j::Driver::Types::LocalTime.new(value.fetch("nanoseconds"))
+    when "time" then Neo4j::Driver::Types::OffsetTime.new(value.fetch("nanoseconds"), value.fetch("tz_offset_seconds"))
+    when "duration"
+      Neo4j::Driver::Types::Duration.new(value.fetch("months"), value.fetch("days"), value.fetch("seconds"),
+                                         value.fetch("nanoseconds"))
+    when "point"
+      Neo4j::Driver::Types::Point.new(srid: value.fetch("srid"), x: value.fetch("x"), y: value.fetch("y"),
+                                      z: value["z"])
+    else
+      raise Error, "Unknown value type in dump: #{value[DUMP_TYPE_KEY].inspect}"
+    end
+  end
+
   def parse_dump(io, node_batches, relationship_batches, progress = nil)
     node_count = 0
     relationship_count = 0
@@ -1116,10 +1189,12 @@ module Neo4jBolt
       value = JSON.parse(json)
       case kind
       when "n"
+        value["properties"] = decode_dump_properties(value["properties"])
         labels = value.fetch("labels")
         node_batches[labels.sort] << value
         node_count += 1
       when "r"
+        value["properties"] = decode_dump_properties(value["properties"])
         relationship_batches[value.fetch("type")] << value
         relationship_count += 1
       else

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: neo4j_bolt
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Michael Specht