Crate bolt_client

An asynchronous client for Bolt-compatible servers.

Example

The below example demonstrates how to communicate with a Neo4j server using Bolt protocol version 4.

use std::collections::HashMap;
use std::convert::TryFrom;
use std::env;
use std::iter::FromIterator;

use tokio::prelude::*;

use bolt_client::*;
use bolt_proto::{message::*, value::*, Message, Value};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a new connection to the server and perform a handshake to establish a
    // protocol version. In this example, all connection/authentication details are
    // stored in environment variables. A domain is optional - including it will
    // create a client that uses a TLS-secured connection.
    let mut client = Client::new(env::var("BOLT_TEST_ADDR")?,
                                 env::var("BOLT_TEST_DOMAIN").ok()).await?;
    // This example demonstrates usage of the v4 protocol
    let handshake_result = client.handshake(&[4, 0, 0, 0]).await;
     
    // Send a HELLO message with authorization details to the server to initialize
    // the session.
    let response: Message = client.hello(
        Some(Metadata::from_iter(vec![
            ("user_agent", "my-client-name/1.0"),
            ("scheme", "basic"),
            ("principal", &env::var("BOLT_TEST_USERNAME")?),
            ("credentials", &env::var("BOLT_TEST_PASSWORD")?),
        ]))).await?;
    assert!(Success::try_from(response).is_ok());

    // Run a query on the server
    let response = client.run_with_metadata("RETURN 1 as num;", None, None).await?;

    // Successful responses will include a SUCCESS message with related metadata
    // Consuming these messages is optional and will be skipped for the rest of the example
    assert!(Success::try_from(response).is_ok());

    // Use PULL to retrieve results of the query, organized into RECORD messages
    // We get a (Message, Vec<Record>) returned from a PULL
    let pull_meta = Metadata::from_iter(vec![("n", 1)]);
    let (response, records) = client.pull(Some(pull_meta.clone())).await?;

    assert_eq!(records[0].fields(), &[Value::from(1)]);

    // Run a more complex query with parameters
    let params = Params::from_iter(vec![("name", "Rust")]);
    client.run_with_metadata(
        "CREATE (:Client)-[:WRITTEN_IN]->(:Language {name: $name});",
        Some(params), None).await?;
    client.pull(Some(pull_meta.clone())).await?;

    // Grab a node from the database and convert it to a native type
    client.run_with_metadata("MATCH (rust:Language) RETURN rust;", None, None).await?;
    let (response, records) = client.pull(Some(pull_meta.clone())).await?;
    let node = Node::try_from(records[0].fields()[0].clone())?;

    // Access properties from returned values
    assert_eq!(node.labels(), &[String::from("Language")]);
    assert_eq!(node.properties(),
               &HashMap::from_iter(vec![(String::from("name"), Value::from("Rust"))]));

    // End the connection with the server
    client.goodbye().await?;

    Ok(())
}

For version 3 of the protocol, the above example would simply use Client::pull_all instead of Client::pull. In version 4, note that we must pass metadata to PULL to indicate how many records we wish to consume, but in version 3 this metadata is not required (i.e. all records are consumed).

let (response, records) = client.pull_all().await?;

For versions 1 and 2 of the protocol, the changes are more involved:

// For the handshake we want to support versions 1 and 2 only, preferring version 2.
let handshake_result = client.handshake(&[2, 1, 0, 0]).await;
     
// Instead of `hello`, we call `init`, and the user agent string is provided separately.
let response: Message = client.init(
    "my-client-name/1.0",
    Metadata::from_iter(vec![
        ("scheme", "basic"),
        ("principal", &env::var("BOLT_TEST_USERNAME")?),
        ("credentials", &env::var("BOLT_TEST_PASSWORD")?),
    ])).await?;

// Instead of `run_with_metadata`, we call `run`, and there is no third parameter for metadata.
let response = client.run("RETURN 1 as num;", None).await?;

// We also use Client::pull_all here.
let (response, records) = client.pull_all().await?;

// There is no call to `goodbye`

See the documentation of the Client struct for information on transaction management, error handling, and more.

Modules

error

Structs

Client	A tokio-based client for Bolt servers, compatible with versions 1 through 4 of the protocol.
Metadata	A map from Strings to Values used primarily to provide supplementary information to Client methods.
Params	A map from Strings to Values used primarily to provide supplementary information to Client methods.