Initializes this connection with the given URL string and SSL flag.

connection = Neo4j::Bolt::Connection.new("bolt://neo4j:password@localhost", ssl: false)

Initializes this connection with the given URI and SSL flag. SSL defaults to true so that, if you omit it by mistake, you aren't sending your database credentials in plaintext.

uri = URI.parse("bolt://neo4j:password@localhost")
connection = Neo4j::Bolt::Connection.new(uri, ssl: false)

Execute the given query with the given parameters, returning an array containing the results cast into the given types.

struct User
  Neo4j.map_node(
    id: UUID,
    email: String,
  )
end
connection.exec_cast(<<-CYPHER, { email: "[email protected]" }, {User})
  MATCH (user:User { email: $email })
  RETURN user
CYPHER

Execute the given query with the given parameters, returning an array containing the results cast into the given types.

struct User
  Neo4j.map_node(
    id: UUID,
    email: String,
  )
end
connection.exec_cast(<<-CYPHER, Neo4j::Map { "email" => "[email protected]" }, {User})
  MATCH (user:User { email: $email })
  RETURN user
CYPHER
# => [{User(@id="4478440e-1897-41a9-812d-91f6d21b994b", @email="[email protected]")}]

Execute the given query with the given parameters, yielding a tuple containing the results cast into the given types.

struct User
  Neo4j.map_node(
    id: UUID,
    email: String,
  )
end
connection.exec_cast(<<-CYPHER, { email: "[email protected]" }, {User}) do |(user)|
  MATCH (user:User { email: $email })
  RETURN user
CYPHER
  process user
end

Execute the given query with the given parameters, yielding a tuple containing the results cast into the given types.

struct User
  Neo4j.map_node(
    id: UUID,
    email: String,
  )
end
connection.exec_cast(<<-CYPHER, Neo4j::Map { "email" => "[email protected]" }, {User}) do |(user)|
  MATCH (user:User { email: $email })
  RETURN user
CYPHER
  process user
end

Execute the given query with the given parameters, returning a single result cast to the given type.

struct User
  Neo4j.map_node(
    id: UUID,
    email: String,
  )
end
connection.exec_cast_scalar(<<-CYPHER, Neo4j::Map { "email" => "[email protected]" }, User)
  MATCH (user:User { email: $email })
  RETURN user
  LIMIT 1
CYPHER
# => User(@id="4478440e-1897-41a9-812d-91f6d21b994b", @email="[email protected]")

Execute the given query with the given parameters, returning an array containing the results cast into the given types.

struct User
  Neo4j.map_node(
    id: UUID,
    email: String,
  )
end
connection.exec_cast_single(<<-CYPHER, Neo4j::Map { "email" => "[email protected]" }, {User})
  MATCH (user:User { email: $email })
  RETURN user
  LIMIT 1
CYPHER
# => {User(@id="4478440e-1897-41a9-812d-91f6d21b994b", @email="[email protected]")}

Executes the given query with the given parameters and executes the block once for each result returned from the database.

connection.execute <<-CYPHER, Neo4j::Map { "id" => 123 } do |(user)|
  MATCH (user:User { id: $id })
  RETURN user
CYPHER
  process User.new(user.as Neo4j::Node)
end

In the example above, we used () in the block arguments to destructure the list of RETURNed values. Also note that we need to cast it down to a Neo4j::Node. All values in results have the compile-time type of Neo4j::Value and so will need to be cast down to its specific type.

Execute the given query with the given parameters, returning a Result object containing query metadata and the query results in an array.

connection.execute(query, Neo4j::Map { "id" => 123 })

Execute the given query with the given parameters, returning a Result object containing query metadata and the query results in an array.

This method provides a convenient shorthand for providing a Neo4j::Map of query parameters.

connection.execute(query, id: 123)

If the connection gets into a wonky state, this method tells the server to reset it back to a normal state, but you lose everything you haven't pulled down yet.

Returns a streaming iterator that consumes results lazily from the Neo4j server. This can be used when the result set is very large so that your application does not need to retain the full result set in memory.

results = connection.stream(query, Neo4j::Map { "user_id" => user.id })

results.each do |(user)|
  process User.new(user.as(Neo4j:Node))
end

This example yields each result as it comes back from the database, but makes the query metadata available immediately.

NOTE: You can only consume these results once. Anything that calls Enumerable#each(&block) will fully consume all results. This means calls like Enumerable#first and Enumerable#size are destructive. This is a side effect of using the streaming iterator.

NOTE: If you are using a connection pool, you must consume all of the results before the connection goes back into the pool. Otherwise, the connection will be in an inconsistent state and you will need to manually Neo4j::Bolt::Connection#reset it.

pool.connection do |connection|
  results = connection.stream(query)
  results.each do |(user)|
    process User.new(user.as Neo4j::Node)
  end
ensure
  results.each {} # Finish consuming the results
end

Returns a streaming iterator that consumes results lazily from the Neo4j server. This can be used when the result set is very large so that your application does not need to retain the full result set in memory.

results = connection.stream(query, user_id: user.id)

results.each do |(user)|
  process User.new(user.as(Neo4j:Node))
end

This example yields each result as it comes back from the database, but makes the query metadata available immediately.

NOTE: You can only consume these results once. Anything that calls Enumerable#each(&block) will fully consume all results. This means calls like Enumerable#first and Enumerable#size are destructive. This is a side effect of using the streaming iterator.

NOTE: If you are using a connection pool, you must consume all of the results before the connection goes back into the pool. Otherwise, the connection will be in an inconsistent state and you will need to manually Neo4j::Bolt::Connection#reset it.

pool.connection do |connection|
  results = connection.stream(query)
  results.each do |(user)|
    process User.new(user.as Neo4j::Node)
  end
ensure
  results.each {} # Finish consuming the results
end

Wrap a group of queries into an atomic transaction. Yields a Neo4j::Bolt::Transaction.

connection.transaction do |txn|
  connection.execute query1
  connection.execute query2
end

Exceptions raised within the block will roll back the transaction. To roll back the transaction manually and exit the block, call txn.rollback.