4d3c0a2fa5
Reviewers: buda, mtomic Reviewed By: buda Differential Revision: https://phabricator.memgraph.io/D1526
9.4 KiB
Quick Start
This chapter outlines installing and running Memgraph, as well as executing basic queries against the database.
Installation
The Memgraph binary is offered as:
- Debian package for Debian 9 (Stretch);
- RPM package for CentOS 7 and
- Docker image.
After downloading the binary, proceed to the corresponding section below.
NOTE: Currently, newer versions of Memgraph are not backward compatible with older versions. This is mainly noticeable by unsupported loading of storage snapshots between different versions.
Docker Installation
Before proceeding with the installation, please install the Docker engine on
the system. Instructions on how to install Docker can be found on the
official Docker website.
Memgraph Docker image was built with Docker version 1.12 and should be
compatible with all later versions.
After installing and running Docker, download the Memgraph Docker image and import it with the following command.
docker load -i /path/to/memgraph-<version>-docker.tar.gz
Memgraph is then started with another docker command.
docker run -p 7687:7687 \
-v mg_lib:/var/lib/memgraph -v mg_log:/var/log/memgraph -v mg_etc:/etc/memgraph \
memgraph
On success, expect to see output similar to the following.
Starting 8 workers
Server is fully armed and operational
Listening on 0.0.0.0 at 7687
Memgraph is now ready to process queries, you may now proceed to
querying. To stop Memgraph, press Ctrl-c.
Memgraph configuration is available in Docker's named volume mg_etc. On
Linux systems it should be in
/var/lib/docker/volumes/mg_etc/_data/memgraph.conf. After changing the
configuration, Memgraph needs to be restarted.
Note about named volumes
In case named volumes are reused between different versions of Memgraph, a user has to be careful because Docker will overwrite a folder within the container with existing data from the host machine. In the case where a new file is introduced, or two versions of Memgraph are not compatible, the new feature won't work or Memgraph won't be able to work correctly. The easiest way to solve the issue is to use another named volume or to remove existing named volume from the host with the following command.
docker volume rm <volume_name>
Named Docker volumes used in this documentation are: mg_etc, mg_log and
mg_lib. E.g. to avoid any configuration issues between different Memgraph
versions, docker volume rm mg_etc can be executed before running a new
container.
Another valid option is to try to migrate your existing volume to a
newer version of Memgraph. In case of any issues, send an email to
tech@memgraph.com.
Note for OS X/macOS Users
Although unlikely, some OS X/macOS users might experience minor difficulties
after following the Docker installation instructions. Instead of running on
localhost, a Docker container for Memgraph might be running on a custom IP
address. Fortunately, that IP address can be found using the following
algorithm:
- Find out the container ID of the Memgraph container
By issuing the command docker ps the user should get an output similar to the
following:
CONTAINER ID IMAGE COMMAND CREATED ...
9397623cd87e memgraph "/usr/lib/memgraph/m…" 2 seconds ago ...
At this point, it is important to remember the container ID of the Memgraph
image. In our case, that is 9397623cd87e.
- Use the container ID to retrieve an IP of the container
docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' 9397623cd87e
The command above should yield the sought IP. If that IP does not correspond to
localhost, it should be used instead of localhost when firing up the
neo4j-client in the querying section.
Debian Package Installation
After downloading Memgraph as a Debian package, install it by running the following.
dpkg -i /path/to/memgraph_<version>.deb
If the installation was successful, Memgraph should already be running. To make sure that is true, start it explicitly with the command:
systemctl start memgraph
To verify that Memgraph is running, run the following command.
journalctl --unit memgraph
It is expected to see something like the following output.
Nov 23 13:40:13 hostname memgraph[14654]: Starting 8 BoltS workers
Nov 23 13:40:13 hostname memgraph[14654]: BoltS server is fully armed and operational
Nov 23 13:40:13 hostname memgraph[14654]: BoltS listening on 0.0.0.0 at 7687
Memgraph is now ready to process queries, you may now proceed to querying. To shutdown Memgraph server, issue the following command.
systemctl stop memgraph
Memgraph configuration is available in /etc/memgraph/memgraph.conf. After
changing the configuration, Memgraph needs to be restarted.
RPM Package Installation
If you downloaded the RPM package of Memgraph, you can install it by running the following command.
rpm -U /path/to/memgraph-<version>.rpm
After the successful installation, Memgraph can be started as a service. To do so, type the following command.
systemctl start memgraph
To verify that Memgraph is running, run the following command.
journalctl --unit memgraph
It is expected to see something like the following output.
Nov 23 13:40:13 hostname memgraph[14654]: Starting 8 BoltS workers
Nov 23 13:40:13 hostname memgraph[14654]: BoltS server is fully armed and operational
Nov 23 13:40:13 hostname memgraph[14654]: BoltS listening on 0.0.0.0 at 7687
Memgraph is now ready to process queries, you may now proceed to querying. To shutdown Memgraph server, issue the following command.
systemctl stop memgraph
Memgraph configuration is available in /etc/memgraph/memgraph.conf. After
changing the configuration, Memgraph needs to be restarted.
Querying
Memgraph supports the openCypher query language which has been developed by Neo4j. The language is currently going through a vendor-independent standardization process. It's a declarative language developed specifically for interaction with graph databases.
The easiest way to execute openCypher queries against Memgraph, is using
Neo4j's command-line tool. The command-line neo4j-client can be installed as
described on the official website.
After installing neo4j-client, connect to the running Memgraph instance by
issuing the following shell command.
neo4j-client -u "" -p "" localhost 7687
After the client has started it should present a command prompt similar to:
neo4j-client 2.1.3
Enter `:help` for usage hints.
Connected to 'neo4j://@localhost:7687'
neo4j>
At this point it is possible to execute openCypher queries on Memgraph. Each
query needs to end with the ; (semicolon) character. For example:
CREATE (u:User {name: "Alice"})-[:Likes]->(m:Software {name: "Memgraph"});
The above will create 2 nodes in the database, one labeled "User" with name "Alice" and the other labeled "Software" with name "Memgraph". It will also create an edge labeled "Likes". Those three graph elements jointly represent the fact that "Alice" likes "Memgraph".
To find created nodes and edges, execute the following query:
MATCH (u:User)-[r]->(x) RETURN u, r, x;
Supported Languages
If users wish to query Memgraph programmatically, they can do so using the Bolt protocol. Bolt was designed for efficient communication with graph databases and Memgraph supports Version 1 of the protocol. Bolt protocol drivers for some popular programming languages are listed below:
We have included some basic usage examples for some of the supported languages in the Drivers section.
Telemetry
Telemetry is an automated process by which some useful data is collected at a remote point. At Memgraph, we use telemetry for the sole purpose of improving our product, thereby collecting some data about the machine that executes the database (CPU, memory, OS and kernel information) as well as some data about the database runtime (CPU usage, memory usage, node and edge count).
Here at Memgraph, we deeply care about the privacy of our users and do not
collect any sensitive information. If users wish to disable Memgraph's telemetry
features, they can easily do so by either altering the line in
/etc/memgraph/memgraph.conf that enables telemetry (--telemetry-enabled=true)
into --telemetry-enabled=false, or by including the --telemetry-enabled=false
as a command-line argument when running the executable.
Where to Next
To learn more about the openCypher language, visit openCypher Query Language chapter in this document. For real-world examples of how to use Memgraph visit Examples chapter. Details on what can be stored in Memgraph are in Data Storage chapter.
We welcome and encourage your feedback!