How to use LocalStack with Neptune and OpenCypher?

The release notes for localstack 1.1x mention initial support for neo4j on Neptune but offer 0 additional information on that.
I’ve tried accessing my neptune instance using opencypher as mentioned here:

these endpoints do not work on my localstack.

I’ve also tried to somehow connect to my localstack instance using the bolt protocol. this also does not work.

is there are further information on that? thanks

Hi @panda,

thanks for reaching out! It seems the config information is missing from the docs, we will update that!

The support for neo4j is experimental, but you can activate the mode with the env NEPTUNE_DB_TYPE=neo4j

if neo4j is enabled, will i be able to create a neo4j endpoint based on the cluster address i create? also will i be to access these endpoints? note that these are openCypher, not neo4j per se


Hi @panda,

there is currently no support for a openCypher endpoint like you shared in your initial link to AWS. You can use the bolt protocol with neo4j though.

If you need such an endpoint, I would kindly ask you to create a feature/enhancement request on Github.

hey @stefanie
as u mentioned, the endpoint is not available and I cannot establish a connection with the database, neither with python drivers and neither with javascript, or the neo4j desktop client, how do i know that the DB is actually available? :slight_smile: thanks

When you create e.g. a neptune cluster, you will see the details and the status:

awslocal rds describe-db-clusters
    "DBClusters": [
            "AllocatedStorage": 1,
            "DatabaseName": "test",
            "DBClusterIdentifier": "c-0b3a2de1",
            "DBClusterParameterGroup": "default.neptune",
            "Status": "available",
            "Endpoint": "",
            "ReaderEndpoint": "",
            "MultiAZ": false,
            "Engine": "neptune",
            "Port": 4510,
            "MasterUsername": "test",
            "DBClusterMembers": [],
            "VpcSecurityGroups": [
                    "VpcSecurityGroupId": "sg-dd2a7c10dc10e8603",
                    "Status": "active"
            "StorageEncrypted": false,
            "DbClusterResourceId": "cluster-5083a747",
            "DBClusterArn": "arn:aws:rds:us-east-1:000000000000:cluster:c-0b3a2de1",
            "IAMDatabaseAuthenticationEnabled": false,
            "TagList": []

Once the status is “available” you can connect to the cluster (or instance), e.g. using the ReaderEndpoint and the Port.

You can then use the bolt protocol to connect, e.g.

from neo4j import GraphDatabase
driver = GraphDatabase.driver(f"bolt://{endpoint}:{port}", encrypted=False)

when creating the cluster with neo4j enabled, i get Status: Error on each cluster i create.
how can i see the error ?

Please set the DEBUG=1 flag and check the localstack logs, where you should see an error message or stack trace.
Also from your output I can tell you are not using the latest localstack version. Could you please update the images, either using using docker pull localstack/localstack-pro:latest or the localstack cli, e.g. localstack update docker-images.

first of all, i appreciate the fast responses.

i’m currently unable to update the version as im dependent on my organizations images and it needs to pass through the channels.

the version i receive when doing localstack --version
is 3.0.2

the error message appears to be

is this something i can resolve with some correction of the configuration?
many thanks

Could you share:

  • how you start localstack
  • how you try to create the neptune cluster or instance
  • a little bit more of the log output (I would like to see the logs starting from right before you send the request to localstack for creating neptune cluster/instance).
  • do you have any restrictions in your environment, e.g. you mentioned you can’t update due to organization policies - are there maybe other policies that would prevent opening a new port?
  • do you have any issues creating other resources, e.g. a RDS database, or starting neptune with tinkerpop?