sagastume / boltx

Neo4j driver for Elixir

Boltx

Boltx is an Elixir driver for Neo4j/Bolt Protocol.

• Supports Neo4j versions: 3.0.x/3.1.x/3.2.x/3.4.x/3.5.x/4.x/5.9 -5.13.0
• Supports Bolt version: 1.0/2.0/3.0/4.x/5.0/5.1/5.2/5.3/5.4
• Supports transactions, prepared queries, streaming, pooling and more via DBConnection
• Automatic decoding and encoding of Elixir values

Documentation: https://hexdocs.pm/boltx

Features

Feature	Implemented
Querys	YES
Transactions	YES
Stream capabilities	NO
Routing	NO

Usage

Add :boltx to your dependencies:

def deps() do
  [
    {:boltx, "~> 0.0.6"}
  ]
end

Using the latest version.

opts = [
    hostname: "127.0.0.1",
    auth: [username: "neo4j", password: ""],
    user_agent: "boltxTest/1",
    pool_size: 15,
    max_overflow: 3,
    prefix: :default
]

iex> {:ok, conn} = Boltx.start_link(opts)
{:ok, #PID<0.237.0>}

iex> Boltx.query!(conn, "return 1 as n") |> Boltx.Response.first()
%{"n" => 1}

# Commit is performed automatically if everythings went fine
Boltx.transaction(conn, fn conn ->
  result = Boltx.query!(conn, "CREATE (m:Movie {title: "Matrix"}) RETURN m")
end)

Set it up in an app

Add the configuration to the corresponding files for each environment or to your config/config.ex.

Name of process

The process name must be defined in your configuration

import Config

config :boltx, Bolt,
  uri: "bolt://localhost:7687",
  auth: [username: "neo4j", password: "password"],
  user_agent: "boltxTest/1",
  pool_size: 15,
  max_overflow: 3,
  prefix: :default,
  name: Bolt

Add Boltx to the application's main monitoring tree and let OTP manage it.

# lib/n4_d/application.ex

defmodule N4D.Application do
  @moduledoc false

  use Application

  def start(_type, _args) do
    children = [
      %{
        id: Boltx,
        start: {Boltx, :start_link, [Application.get_env(:boltx, Bolt)] },
      }
    ]

    opts = [strategy: :one_for_one, name: N4D.Supervisor]
    Supervisor.start_link(children, opts)
  end
end

Or

children = [
  {Boltx, Application.get_env(:boltx, Bolt)}
]

Now you can run query with the name you set

iex> Boltx.query!(Bolt, "return 1 as n") |> Boltx.Response.first()
%{"n" => 1}

URI schemes

By default the scheme is bolt+s

URI	Description	TLSOptions
neo4j	Unsecured	[]
neo4j+s	Secured with full certificate	[verify: :verify_none]
neo4j+ssc	Secured with self-signed certificate	[verify: :verify_peer]
bolt	Unsecured	[]
bolt+s	Secured with full certificate	[verify: :verify_none]
bolt+ssc	Secured with self-signed certificate	[verify: :verify_peer]

Contributing

Getting Started

Neo4j uses the Bolt protocol for communication and query execution. You can find the official documentation for Bolt here: Bolt Documentation.

It is crucial to grasp various concepts before getting started, with the most important ones being:

• PackStream: The syntax layer for the Bolt messaging protocol.
• Bolt Protocol: The application protocol for database queries via a database query language.
  • Bolt Protocol handshake specification
  • Bolt Protocol message specification
  • Structure Semantics

It is advisable to use the specific terminology from the official documentation and official drivers to ensure consistency with this implementation.

Test

As certain versions of Bolt may be compatible with specific functionalities while others can undergo significant changes, tags are employed to facilitate version-specific testing. Some of these tags include:

• :core (Included in all executions).
• :bolt_version_{{specific version}} (Tag to run the test on a specific version, for example, for 5.2: :bolt_version_5_2, for version 1: :bolt_version_1_0).
• bolt_{major version}_x (Tag to run on all minor versions of a major version, for example, for 5: :bolt_5_x, for all minor versions of 4:: :bolt_4_x).
• :last_version (Tag to run the test only on the latest version).

By default, all tags are disabled except the :core tag. To enable the tags, it is necessary to configure the following environment variables:

• BOLT_VERSIONS: This variable is used for Bolt version configuration but is also useful for testing. You can specify a version, for example, BOLT_VERSIONS="1.0".
• BOLT_TCP_PORT: You can configure the port with the environment variable (BOLT_TCP_PORT=7688).

Help script

To simplify test execution, the test-runner.sh script is available. You can find the corresponding documentation here: Help script

boltx's Issues

Document the new configuration settings

Standardize server response error handling

Cooperation

First of all, thank you for your great work on boltx.

In my organization EnBW we are working on a project where we use Elixir and Neo4j. This week we switched to boltx.

We have been thinking about how we can support the development of boltx (e.g. contributing or co-maintaining). Do you have any thoughts on this?

Kind regards

Tests for databases with SSL

Complete the DBConnection interface

Enable query execution

Remove agent-related code and other unused elements in encoding

Tests for servers without connection

Delete legacy protocol files

Error querying all nodes after buffering change in 4.0

I am getting this error while querying using Boltx. The same query works if I try it on the Neo4j Browser.

** (DBConnection.ConnectionError) bad return value: {:error, %{code: :failure, message: %MatchError{term: << 101, 91, 100,  102, 81, 101, 107, 111, 109, 111, 42, ...>>}}}
    (db_connection 2.6.0) lib/db_connection.ex:1366: DBConnection.handle_common_result/3
    (db_connection 2.6.0) lib/db_connection.ex:1607: DBConnection.run/6
    (db_connection 2.6.0) lib/db_connection.ex:743: DBConnection.parsed_prepare_execute/5
    (db_connection 2.6.0) lib/db_connection.ex:735: DBConnection.prepare_execute/4
    (boltx 0.0.5) lib/boltx.ex:149: Boltx.do_query/4

Can you please check this?

Error getting a node with a Datetime field

I got the following error while running the query.
Boltx.query(Boltx, "MATCH(n) RETURN n")

After debugging more, I found out if the query has MATCH command in it, then it throws error.

** (DBConnection.ConnectionError) bad return value: {:error, %{code: :failure, message: %FunctionClauseError{module: Boltx.PackStream.Unpacker, function: :unpack, arity: 1, kind: nil, args: nil, clauses: nil}}}
    (db_connection 2.4.3) lib/db_connection.ex:1267: DBConnection.handle_common_result/3
    (db_connection 2.4.3) lib/db_connection.ex:1508: DBConnection.run/6
    (db_connection 2.4.3) lib/db_connection.ex:644: DBConnection.parsed_prepare_execute/5
    (db_connection 2.4.3) lib/db_connection.ex:636: DBConnection.prepare_execute/4
    (boltx 0.0.4) lib/boltx.ex:149: Boltx.do_query/4

Can you please help me?

Decouple Packstream from the Bolt version

Thank You

Great work here! Thank you for adding support for Neo4j v5!

I've created this library Ex4j recently to add support for better abstractions on Neo4j instead of writing strings manually to retrieve data (it reminds 1990's) as well as being able to wrap the response in a struct similar to ecto.

I intend to replace bolt.sips with your driver that seems better and support the newer versions.

Tests for servers rejecting connection in handshake

Find code improvements for protocol messages

(Mix) Could not start application, returned an error: shutdown: failed to start child: Boltx

I've added Boltx to my Supervision tree.

Config:

config :boltx, Bolt,
  uri: System.get_env("NEO4J_HOST") || "bolt://localhost:7687",
  auth: [username: "neo4j", password: System.get_env("NEO4J_PASSWORD") || "password"],
  user_agent: "boltxTest/1",
  pool_size: 15,
  max_overflow: 3,
  prefix: :default

application.ex

%{
       id: Boltx,
       start: {Boltx, :start_link, Application.get_env(:boltx, Bolt)}
}

While starting the server, I got the following error.

** (Mix) Could not start application accounts_service: AccountsService.Application.start(:normal, []) returned an error: shutdown: failed to start child: Boltx
    ** (EXIT) an exception was raised:
        ** (UndefinedFunctionError) function Boltx.start_link/6 is undefined or private
            (boltx 0.0.3) Boltx.start_link({:uri, "bolt://localhost:7687"}, {:auth, [username: "neo4j", password: "password"]}, {:user_agent, "boltxTest/1"}, {:pool_size, 15}, {:max_overflow, 3}, {:prefix, :default})
            (stdlib 3.17.2) supervisor.erl:414: :supervisor.do_start_child_i/3
            (stdlib 3.17.2) supervisor.erl:400: :supervisor.do_start_child/2
            (stdlib 3.17.2) supervisor.erl:384: anonymous fn/3 in :supervisor.start_children/2
            (stdlib 3.17.2) supervisor.erl:1250: :supervisor.children_map/4
            (stdlib 3.17.2) supervisor.erl:350: :supervisor.init_children/2
            (stdlib 3.17.2) gen_server.erl:423: :gen_server.init_it/2
            (stdlib 3.17.2) gen_server.erl:390: :gen_server.init_it/6
            (stdlib 3.17.2) proc_lib.erl:226: :proc_lib.init_p_do_apply/3

Can you please check this, and suggest a better way to add Boltx to the application supervisor?