Boltkit
Boltkit is a package of utilities for Neo4j driver authors. The library exposes a set of command line tools as well as a full Python API for working with Neo4j-compatible clients and servers.
Installation
Installation is via github and can either run globally or within a virtualenv.
Installation makes available a versatile command line tool, called bolt.
$ python3 -m pip install --user git+https://github.com/neo4j-drivers/[email protected]#egg=boltkit
where x and y are replaced with major and minor versions respectively.
$ bolt --help
Usage: bolt [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
Commands:
client Run a Bolt client
dist List available Neo4j releases
get Download Neo4j
proxy Run a Bolt proxy server
server Run a Neo4j cluster or standalone server.
stub Run a Bolt stub server
Command Overview
bolt client
The bolt client command allows execution of a Cypher query against a Neo4j service.
Synopsis:
$ bolt client --help
Usage: bolt client [OPTIONS] [CYPHER]...
Run a Bolt client
Options:
-a, --auth AUTH
-b, --bolt-version INTEGER
-s, --server-addr ADDR
-t, --transaction
-v, --verbose
--help Show this message and exit.
Example:
$ bolt client "UNWIND range(1, 10) AS n RETURN n"
bolt dist
TODO
bolt get
TODO
bolt proxy
TODO
bolt server
Run a Neo4j cluster or standalone server in one or more local Docker containers.
Synopsis:
$ bolt server --help
Usage: bolt server [OPTIONS] [COMMAND]...
Run a Neo4j cluster or standalone server in one or more local Docker
containers.
If an additional COMMAND is supplied, this will be executed after startup,
with a shutdown occurring immediately afterwards. If no COMMAND is
supplied, the service will remain available until manually shutdown by
Ctrl+C.
A couple of environment variables will also be made available to any
COMMAND passed. These are:
- BOLT_SERVER_ADDR
- NEO4J_AUTH
Options:
-a, --auth AUTH Credentials with which to bootstrap the service.
These must be specified as a 'user:password' pair
and may alternatively be supplied via the
NEO4J_AUTH environment variable. These credentials
will also be exported to any COMMAND executed
during the service run.
-B, --bolt-port INTEGER A port number (standalone) or base port number
(cluster) for Bolt traffic.
-c, --n-cores INTEGER If specified, a cluster with this many cores will
be created. If omitted, a standalone service will
be created instead. See also -r for specifying the
number of read replicas.
-H, --http-port INTEGER A port number (standalone) or base port number
(cluster) for HTTP traffic.
-i, --image TEXT The Docker image tag to use for building
containers. The repository can also be included,
but will default to 'neo4j'. Note that a Neo4j
Enterprise Edition image is required for building
clusters.
-n, --name TEXT A Docker network name to which all servers will be
attached. If omitted, an auto-generated name will
be used.
-r, --n-replicas INTEGER The number of read replicas to include within the
cluster. This option will only take effect if -c
is also used.
-v, --verbose Show more detail about the startup and shutdown
process.
--help Show this message and exit.
bolt stub
The stub Bolt server can be used as a testing resource for client software. Scripts can be created against which unit tests can be run without the need for a full Neo4j server.
Synopsis:
$ bolt stub --help
Usage: bolt stub [OPTIONS] SCRIPT
Run a Bolt stub server.
The stub server process listens for an incoming client connection and will
attempt to play through a pre-scripted exchange with that client. Any
deviation from that script will result in a non-zero exit code. This
utility is primarily useful for Bolt client integration testing.
Options:
-l, --listen-addr ADDR The address on which to listen for incoming
connections in INTERFACE:PORT format, where
INTERFACE may be omitted for 'localhost'. If
completely omitted, this defaults to ':17687'. The
BOLT_LISTEN_ADDR environment variable may be used as
an alternative to this option.
-t, --timeout FLOAT The number of seconds for which the stub server will
wait for an incoming connection before automatically
terminating. If unspecified, the server will wait
indefinitely.
-v, --verbose Show more detail about the client-server exchange.
--help Show this message and exit.
A server script describes a conversation between client and server in terms of the messages
exchanged. An example can be seen in the test/scripts/count.bolt file.
When the server receives a client message, it will attempt to match that against the next client message in the script; if found, this line of the script will be consumed. Then, any server messages that follow will also be consumed and sent back. When the client closes its connection, the server will shut down. If any script lines remain, the server will exit with an error status; if none remain it will exit successfully. After 30 seconds of inactivity, the server will time out and shut down with an error status.
Scripting
Scripts generally consist of alternating client (C:) and server (S:) messages.
Each message line contains the message name followed by its fields, in JSON format.
Some messages, such as RESET, can be automatically (successfully) consumed if they are not relevant to the current test.
For this use a script line such as !: AUTO RESET.
An example:
!: BOLT 3
!: AUTO HELLO
!: AUTO RESET
C: RUN "RETURN {x}" {"x": 1} {}
PULL_ALL
S: SUCCESS {"fields": ["x"]}
RECORD [1]
SUCCESS {}