neo4j_bolt 0.4.5 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc5ccd396277de9c75f73bd338f89a2af476475940d53e0399cfbbeaa9589dc6
-  data.tar.gz: 90a393bb3f4819245613ca34206d24932487de5af4959b27e26232137766e15f
+  metadata.gz: f9f38fc0e16014ae13f2f31d2ba77f119185249821da7d4f7858fa0ef3f9010f
+  data.tar.gz: 5ab718f1dd9829aa1f118a6614f7d29d184d63eb20b4ce7d3e36fc92fea5f204
 SHA512:
-  metadata.gz: e4f8c0aa87b72f4081d19476dbb684ced5fed6851b729f7db4bb7d8b06f7e41f1607581498b1195043edc63433fe91b8ca7aadf0c58c3d8c7f14bf79dcae1395
-  data.tar.gz: '028fc3fc677e0a8d83f6f5554d851ff29b1ab7bf6b0c059ea646f18062f646e4c43554f612bb6c69055658af56e4f08bda30c5756b57899475b98178b91d6e87'
+  metadata.gz: df61ebc16c46698ccab04c94e9a8abd6120ef07d899b7e52e8e9a80d13bcc4b2f8d17bddff330f6d10ff794faabd705ebfba3d3531fdad311cb8ea5de02dbc8c
+  data.tar.gz: 6522b70e44f279f182c289ae3397dafd11d5dff4e72a3437247a5f25bd66d4185e6696b2aa2c96bce976f518d63a30c98c48ea86b2823d28383c3989df24b7eb

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.4.5` 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.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.
 
 ## Installation
 
 For this prerelease, specify the version explicitly:
 
 ```ruby
-gem "neo4j_bolt", "0.4.5"
+gem "neo4j_bolt", "0.5.0"
 ```
 
 Then run `bundle install`. A running Neo4j database is required.
@@ -163,14 +163,31 @@ Managed entries retain the `neo4j_bolt_` prefix. Setup removes obsolete entries
 
 ## Dump and load
 
-The textual format is unchanged:
+The textual format remains line-oriented and backwards compatible. Dumps now include supported schema entries by default:
 
 ```text
-n {"id":0,"labels":["Person"],"properties":{"name":"Ada"}}
-n {"id":1,"labels":["Person"],"properties":{"name":"Grace"}}
+u {"name":"person_email","entity_type":"NODE","label_or_type":"Person","properties":["email"]}
+k {"name":"person_id","entity_type":"NODE","label_or_type":"Person","properties":["id"]}
+i {"name":"person_name","entity_type":"NODE","label_or_type":"Person","properties":["name"]}
+n {"id":0,"labels":["Person"],"properties":{"id":1,"name":"Ada","email":"ada@example.test"}}
+n {"id":1,"labels":["Person"],"properties":{"id":2,"name":"Grace","email":"grace@example.test"}}
 r {"from":0,"to":1,"type":"KNOWS","properties":{"since":2024}}
 ```
 
+The record prefixes are:
+
+- `u` — property uniqueness constraint
+- `k` — node or relationship key constraint
+- `i` — ordinary property index
+- `n` — node
+- `r` — relationship
+
+Schema records preserve the schema entry name, whether it belongs to nodes or relationships, the label or relationship type, and the indexed/constrained properties. Constraint-backing indexes are not written as separate `i` records. Ordinary Neo4j 4.4 `BTREE` indexes and modern `RANGE` indexes are treated as the same portable property-index concept, so a logical dump can move between supported Neo4j generations. Neo4j's token lookup indexes are intentionally omitted because they are database infrastructure rather than application property indexes.
+
+Other constraint or index types are not silently dropped. A schema dump fails with a clear error instead; use data-only dumping if the application intentionally needs only nodes and relationships.
+
+Key constraints are dumped when they exist. Loading a dump containing a `k` record requires a Neo4j edition/version that can create that key; otherwise the load fails instead of silently weakening the schema.
+
 ```ruby
 File.open("database.dump", "w") { |io| dump_database(io, progress_io: $stderr) }
 File.open("database.dump", "r") do |io|
@@ -178,6 +195,13 @@ File.open("database.dump", "r") do |io|
 end
 ```
 
+Schema dumping and restoration can be disabled explicitly:
+
+```ruby
+File.open("data.dump", "w") { |io| dump_database(io, schema: false) }
+File.open("database.dump", "r") { |io| load_database_dump(io, schema: false) }
+```
+
 Passing `progress_io:` is optional for the Ruby API. The CLI always reports dump/load progress on stderr, so dump data written to stdout remains safe to redirect or pipe. In `auto` mode a terminal gets a colored, in-place progress bar while redirected stderr receives periodic plain-text progress lines. Set `NEO4J_BOLT_PROGRESS=pretty` to force the terminal display through a container or other wrapper that hides the TTY, or `NEO4J_BOLT_PROGRESS=plain` to force log-friendly output. `NO_COLOR` disables colors without disabling the in-place display.
 
 Both `dump` and `load` accept `--color COLOR` to choose the spinner and filled progress-bar accent. The default is `cyan`. The Ruby API exposes the same setting as `progress_color:`. Available colors are `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `bright-red`, `bright-green`, `bright-yellow`, `bright-blue`, `bright-magenta`, `bright-cyan`, and `bright-white`.
@@ -187,13 +211,24 @@ neo4j_bolt dump --color magenta -o database.dump
 neo4j_bolt load --color bright-blue database.dump
 ```
 
-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 remain loadable.
+Both commands also accept `--data-only`. On `dump`, it omits `u`, `k`, and `i` records. On `load`, it accepts a full dump but ignores its schema records:
+
+```bash
+neo4j_bolt dump --data-only -o data.dump
+neo4j_bolt load --data-only database.dump
+```
+
+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.
 
 Loads start with batches of 5,000 records by default. This is an initial ceiling rather than a claimed optimum: if Neo4j returns a transaction-memory/resource error whose server semantics guarantee rollback, the loader halves the failed batch and retries it, then keeps the smaller size for the rest of that phase. Node and relationship phases adapt independently. Other errors are not retried, because a generic connection failure cannot safely prove that a `CREATE` transaction did not commit. Callers can change the initial ceiling with `initial_batch_size:`; the CLI exposes the same setting as `--batch-size`.
 
-Loading requires an empty database unless `force_append: true` is passed. `load_database_dump` owns its batch transactions and therefore rejects being called from inside `transaction`.
+Loading data requires an empty database unless `force_append: true` is passed. For a dump that contains `u`, `k`, or `i` records and is being loaded with schema enabled, the target must also have no application constraints or property indexes. Neo4j's built-in token lookup indexes do not count as application schema. Old `n`/`r`-only dumps, and loads using `schema: false` / `--data-only`, keep the old data-only emptiness rule and may load into a data-empty database that already has application schema.
+
+With a normal full restore, the schema preflight happens before any data is written and the saved schema is created strictly after the data load. With `force_append: true`, existing schema is allowed and restored schema entries use `IF NOT EXISTS`. Existing constraints and indexes are never removed by dump loading.
+
+Data is loaded before schema records are restored, so bulk loading does not pay constraint/index maintenance costs for every inserted record. `load_database_dump` owns its batch transactions and therefore rejects being called from inside `transaction`.
 
 ## CLI
 
@@ -203,8 +238,8 @@ The `neo4j_bolt` executable retains these commands:
 | --- | --- |
 | `neo4j_bolt console` | Open an IRB console with Neo4jBolt loaded |
 | `neo4j_bolt clear --srsly` | Delete all nodes and relationships |
-| `neo4j_bolt dump [--color COLOR]` | Write the textual database dump |
-| `neo4j_bolt load [--force] [--batch-size N] [--color COLOR] PATH` | Load a textual dump |
+| `neo4j_bolt dump [--data-only] [--color COLOR]` | Write the textual database dump |
+| `neo4j_bolt load [--force] [--data-only] [--batch-size N] [--color COLOR] PATH` | Load a textual dump |
 | `neo4j_bolt index ls` | List constraints and indexes |
 | `neo4j_bolt index rm --force` | Remove all constraints and indexes |
 | `neo4j_bolt visualize` | Generate a GraphViz document |
@@ -213,13 +248,18 @@ Use `--host HOST:PORT`, `--username USER`, `--password PASSWORD`, and `--databas
 
 ## Tested Neo4j versions
 
-The same complete integration suite is run against these exact Community images:
+The complete integration suite is run against both Community and Enterprise for each pinned Neo4j generation:
 
 - `neo4j:4.4.48-community`
+- `neo4j:4.4.48-enterprise`
 - `neo4j:5.26.28-community`
+- `neo4j:5.26.28-enterprise`
 - `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.4.5`.
+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.
 
 Run one modern LTS target:
 
@@ -257,7 +297,7 @@ 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.4.5 migration notes
+## 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.
 - The exact prerelease upstream dependency is pinned while no stable `neo4j-ruby-driver` 6.2.x exists.

data/bin/neo4j_bolt

@@ -53,13 +53,20 @@ class App
     # --------------------------------------------
 
     desc 'Dump database'
-    long_desc 'Dump all nodes and relationships.'
+    long_desc 'Dump nodes, relationships, constraints, and property indexes.'
     command :dump do |c|
         c.flag [:o, 'out-file'.to_sym], :default_value => '/dev/stdout'
         c.flag [:color], :default_value => 'cyan', :desc => 'progress accent color'
+        c.switch ['data-only'.to_sym], :default_value => false, :negatable => false,
+                 :desc => 'dump nodes and relationships only'
         c.action do |global_options, options|
             File.open(options['out-file'.to_sym], 'w') do |f|
-                dump_database(f, progress_io: $stderr, progress_color: options[:color])
+                dump_database(
+                    f,
+                    progress_io: $stderr,
+                    progress_color: options[:color],
+                    schema: !options['data-only'.to_sym]
+                )
             end
         end
     end
@@ -67,13 +74,16 @@ class App
     # --------------------------------------------
 
     desc 'Load database dump'
-    long_desc 'Load nodes and relationships from a database dump.'
+    long_desc 'Load nodes, relationships, constraints, and property indexes from a database dump.'
     command :load do |c|
         # c.flag [:i, :in_file], :desc => 'input path', :required => true
-        c.switch [:f, :force], :default_value => false, :desc => 'force appending nodes even if the database is not empty'
+        c.switch [:f, :force], :default_value => false,
+                 :desc => 'force loading into a database that already contains data or application schema'
         c.flag [:b, 'batch-size'.to_sym], :default_value => Neo4jBolt::LOAD_INITIAL_BATCH_SIZE,
                :desc => 'initial batch size; automatically reduced on transaction-memory errors'
         c.flag [:color], :default_value => 'cyan', :desc => 'progress accent color'
+        c.switch ['data-only'.to_sym], :default_value => false, :negatable => false,
+                 :desc => 'ignore constraints and indexes stored in the dump'
         c.action do |global_options, options, args|
             help_now!('input path is required') if args.empty?
             path = args.shift
@@ -83,7 +93,8 @@ class App
                     force_append: options[:force],
                     progress_io: $stderr,
                     progress_color: options[:color],
-                    initial_batch_size: options['batch-size'.to_sym]
+                    initial_batch_size: options['batch-size'.to_sym],
+                    schema: !options['data-only'.to_sym]
                 )
             end
         end

data/lib/neo4j_bolt/version.rb

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

data/lib/neo4j_bolt.rb

@@ -594,11 +594,13 @@ module Neo4jBolt
     nil
   end
 
-  def dump_database(io, progress_io: nil, progress_color: "cyan")
+  def dump_database(io, progress_io: nil, progress_color: "cyan", schema: true)
     progress = ProgressReporter.new(progress_io, color: progress_color)
     dumped_nodes = 0
     dumped_relationships = 0
 
+    dump_schema(io) if schema
+
     transaction do
       identity_function = dump_identity_function
       total_nodes = neo4j_query_expect_one("MATCH (n) RETURN count(n) AS count")["count"]
@@ -655,7 +657,7 @@ module Neo4jBolt
   end
 
   def load_database_dump(io, force_append: false, progress_io: nil, progress_color: "cyan",
-                         initial_batch_size: LOAD_INITIAL_BATCH_SIZE)
+                         initial_batch_size: LOAD_INITIAL_BATCH_SIZE, schema: true)
     raise Error, "load_database_dump cannot run inside a transaction" if transaction_context
 
     initial_batch_size = Integer(initial_batch_size)
@@ -669,7 +671,12 @@ module Neo4jBolt
     progress = ProgressReporter.new(progress_io, color: progress_color)
     node_batches = Hash.new { |hash, key| hash[key] = [] }
     relationship_batches = Hash.new { |hash, key| hash[key] = [] }
-    total_nodes, total_relationships = parse_dump(io, node_batches, relationship_batches, progress)
+    total_nodes, total_relationships, schema_entries =
+      parse_dump(io, node_batches, relationship_batches, progress)
+
+    if !force_append && schema && !schema_entries.empty?
+      ensure_database_has_no_application_schema!
+    end
 
     temporary_token = SecureRandom.hex(12)
     temporary_label = "__neo4j_bolt_load_#{temporary_token}"
@@ -802,6 +809,10 @@ module Neo4jBolt
       raise cleanup_error if original_error.nil? && cleanup_error
     end
 
+    if schema && !schema_entries.empty?
+      restore_dump_schema(schema_entries, progress, if_not_exists: force_append)
+    end
+
     progress.finish("Loaded: #{loaded_nodes} nodes, #{loaded_relationships} relationships")
     nil
   ensure
@@ -927,6 +938,157 @@ module Neo4jBolt
     "`#{identifier.to_s.gsub("`", "``")}`"
   end
 
+  def dump_schema(io)
+    entries = []
+    constraint_names = Set.new
+
+    neo4j_query("SHOW CONSTRAINTS").each do |row|
+      kind = dump_constraint_kind(row["type"])
+      value = schema_dump_value(row, kind)
+      constraint_names << value.fetch(:name)
+      entries << [kind, value]
+    end
+
+    neo4j_query("SHOW INDEXES").each do |row|
+      next unless dumpable_property_index?(row, constraint_names)
+
+      entries << ["i", schema_dump_value(row, "i")]
+    end
+
+    kind_order = { "u" => 0, "k" => 1, "i" => 2 }
+    entries.sort_by { |kind, value| [kind_order.fetch(kind), value.fetch(:name)] }.each do |kind, value|
+      io.puts "#{kind} #{JSON.generate(value)}"
+    end
+  end
+
+  def dump_constraint_kind(type)
+    case type
+    when "UNIQUENESS", "NODE_PROPERTY_UNIQUENESS", "RELATIONSHIP_PROPERTY_UNIQUENESS"
+      "u"
+    when "NODE_KEY", "RELATIONSHIP_KEY"
+      "k"
+    else
+      raise Error,
+            "Cannot dump #{type.inspect} constraint; use schema: false (or --data-only in the CLI)"
+    end
+  end
+
+  def dumpable_property_index?(row, constraint_names)
+    return false if row["owningConstraint"]
+    return false if row["uniqueness"] == "UNIQUE"
+    return false if constraint_names.include?(row["name"])
+    return false if row["type"] == "LOOKUP"
+    return true if %w[BTREE RANGE].include?(row["type"])
+
+    raise Error,
+          "Cannot dump #{row['type'].inspect} index #{row['name'].inspect}; " \
+          "use schema: false (or --data-only in the CLI)"
+  end
+
+  def schema_dump_value(row, kind)
+    name = row["name"]
+    entity_type = row["entityType"]
+    labels_or_types = row["labelsOrTypes"]
+    properties = row["properties"]
+
+    unless name.is_a?(String) && !name.empty? &&
+           %w[NODE RELATIONSHIP].include?(entity_type) &&
+           labels_or_types.is_a?(Array) && labels_or_types.size == 1 &&
+           properties.is_a?(Array) && !properties.empty? &&
+           properties.all? { |property| property.is_a?(String) && !property.empty? }
+      raise Error, "Cannot dump #{kind} schema entry #{name.inspect}: unsupported schema shape"
+    end
+
+    {
+      name: name,
+      entity_type: entity_type,
+      label_or_type: labels_or_types.first,
+      properties: properties
+    }
+  end
+
+  def restore_dump_schema(entries, progress, if_not_exists: false)
+    progress&.note("Restoring schema: #{entries.size} entries...")
+    entries.each do |kind, value|
+      neo4j_query(schema_create_statement(kind, value, if_not_exists: if_not_exists))
+    end
+  end
+
+  def schema_create_statement(kind, value, if_not_exists: false)
+    validate_schema_dump_value!(kind, value)
+
+    name = quote_identifier(value.fetch("name"))
+    if_not_exists_clause = if_not_exists ? " IF NOT EXISTS" : ""
+    entity_type = value.fetch("entity_type")
+    label_or_type = quote_identifier(value.fetch("label_or_type"))
+    properties = value.fetch("properties")
+    variable = entity_type == "NODE" ? "n" : "r"
+    pattern = if entity_type == "NODE"
+                "(#{variable}:#{label_or_type})"
+              else
+                "()-[#{variable}:#{label_or_type}]-()"
+              end
+    property_expressions = properties.map { |property| "#{variable}.#{quote_identifier(property)}" }
+
+    case kind
+    when "u", "k"
+      property_expression = if property_expressions.one?
+                              property_expressions.first
+                            else
+                              "(#{property_expressions.join(', ')})"
+                            end
+      constraint_type = if kind == "u"
+                          "UNIQUE"
+                        elsif entity_type == "NODE"
+                          "NODE KEY"
+                        else
+                          "RELATIONSHIP KEY"
+                        end
+      "CREATE CONSTRAINT #{name}#{if_not_exists_clause} FOR #{pattern} " \
+        "REQUIRE #{property_expression} IS #{constraint_type}"
+    when "i"
+      "CREATE INDEX #{name}#{if_not_exists_clause} FOR #{pattern} ON (#{property_expressions.join(', ')})"
+    else
+      raise Error, "Unexpected schema dump kind: #{kind}"
+    end
+  end
+
+  def validate_schema_dump_value!(kind, value)
+    unless %w[u k i].include?(kind) && value.is_a?(Hash)
+      raise Error, "Invalid #{kind} schema dump entry"
+    end
+
+    name = value.fetch("name")
+    entity_type = value.fetch("entity_type")
+    label_or_type = value.fetch("label_or_type")
+    properties = value.fetch("properties")
+
+    return if name.is_a?(String) && !name.empty? &&
+              %w[NODE RELATIONSHIP].include?(entity_type) &&
+              label_or_type.is_a?(String) && !label_or_type.empty? &&
+              properties.is_a?(Array) && !properties.empty? &&
+              properties.all? { |property| property.is_a?(String) && !property.empty? }
+
+    raise Error, "Invalid #{kind} schema dump entry"
+  end
+
+  def ensure_database_has_no_application_schema!
+    constraints = neo4j_query("SHOW CONSTRAINTS").filter_map { |row| row["name"] }
+    indexes = neo4j_query("SHOW INDEXES").filter_map do |row|
+      next if row["type"] == "LOOKUP"
+      next if row["owningConstraint"]
+      next if row["uniqueness"] == "UNIQUE"
+
+      row["name"]
+    end
+    schema_names = constraints + indexes
+    return if schema_names.empty?
+
+    raise Error,
+          "There are constraints or indexes in this database, exiting now: " \
+          "#{schema_names.sort.join(', ')}"
+  end
+
   # Neo4j 4.4 has no elementId() function. Its id() fallback is used only for
   # deterministic in-process ordering; those database IDs never enter a dump.
   def dump_identity_function
@@ -939,6 +1101,7 @@ module Neo4jBolt
   def parse_dump(io, node_batches, relationship_batches, progress = nil)
     node_count = 0
     relationship_count = 0
+    schema_entries = []
     progress&.update("Reading dump: 0 nodes, 0 relationships", force: true)
 
     io.each_line.with_index(1) do |line, line_number|
@@ -946,16 +1109,22 @@ module Neo4jBolt
       next if line.empty?
 
       kind, json = line.split(" ", 2)
-      raise Error, "Invalid dump entry on line #{line_number}" unless json && %w[n r].include?(kind)
+      unless json && %w[n r u k i].include?(kind)
+        raise Error, "Invalid dump entry on line #{line_number}"
+      end
 
       value = JSON.parse(json)
-      if kind == "n"
+      case kind
+      when "n"
         labels = value.fetch("labels")
         node_batches[labels.sort] << value
         node_count += 1
-      else
+      when "r"
         relationship_batches[value.fetch("type")] << value
         relationship_count += 1
+      else
+        validate_schema_dump_value!(kind, value)
+        schema_entries << [kind, value]
       end
       if ((node_count + relationship_count) % LOAD_PROGRESS_STEP).zero?
         progress&.update("Reading dump: #{node_count} nodes, #{relationship_count} relationships")
@@ -965,7 +1134,7 @@ module Neo4jBolt
     end
 
     progress&.finish("Read dump: #{node_count} nodes, #{relationship_count} relationships")
-    [node_count, relationship_count]
+    [node_count, relationship_count, schema_entries]
   end
 
   def adaptive_each_slice(items, batch_size, progress, kind)

metadata

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