Amazon Neptune
User Guide (API Version 2017-11-29)

Connect to Neptune Using the Gremlin Console with Version 4 Signing

This section shows how to connect to Neptune using the Gremlin Console with Signature Version 4 authentication.


The maximum number of concurrent websocket connections per database instance is 60,000. When the limit is reached Neptune will throttle a request to open a new websocket connection.

If a client properly closes a connection then it will be reflected in the open connections count immediately. If the client does not close the connection then the connection will remain open until it is closed after a 60 minute idle timeout. The idle timeout is the time elapsed since the last message was received from the client.

WebSocket connections are disconnected 36 hours after the connection is established.


  • Java 8 or higher.

  • Apache Maven 3.3 or higher.

  • For information on installing these prerequisites on an EC2 instance running Amazon Linux, see Appendix: Prerequisites on Amazon Linux EC2.

  • IAM credentials to sign the requests. For more information, see Using the Default Credential Provider Chain.


    If you are using temporary credentials, they expire after a specified interval, including the session token.

    You will need to update your session token when you request new credentials. For more information, see Using Temporary Security Credentials to Request Access to AWS Resources.

  • Set the SERVICE_REGION variable to one of the following, indicating the region of your Neptune DB instance: us-east-1, us-east-2, us-west-2, eu-west-1, eu-west-2, eu-central-1, ap-southeast-1, ap-southeast-2. ap-northeast-1.

To connect to Neptune using the Gremlin Console with Version 4 signing

  1. Download Gremlin Console (version 3.3.2+) from the Apache Tinkerpop3 website on to your EC2 instance.

  2. Unzip the Gremlin Console zip file.

  3. Clone the sample repository from GitHub.

    git clone
  4. Change directory into amazon-neptune-gremlin-java-sigv4.

    cd amazon-neptune-gremlin-java-sigv4
  5. Build, package, and get the dependencies of the project.

    mvn package dependency:copy-dependencies
  6. Copy the package jar and all dependency jars to the Gremlin Console library directory.

    cp target/{*.jar,dependency/*.jar} ../apache-tinkerpop-gremlin-console-3.3.2/lib
  7. Remove conflicting dependency jars in the Gremlin Console library directory.

    rm ../apache-tinkerpop-gremlin-console-3.3.2/lib/netty-all-4.0.56.Final.jar
  8. Change directories into the unzipped Gremlin Console directory.

    cd ../apache-tinkerpop-gremlin-console-3.3.2
  9. In the conf subdirectory of the extracted directory, create a file named neptune-remote.yaml with the following text. Replace your-neptune-endpoint with the hostname or IP address of your Neptune DB instance. The square brackets ([ ]) are required.


    For information about finding the hostname of your Neptune DB instance, see the Connecting to Amazon Neptune Endpoints section.

    hosts: [your-neptune-endpoint] port: 8182 connectionPool: { channelizer: org.apache.tinkerpop.gremlin.driver.SigV4WebSocketChannelizer} serializer: { className: org.apache.tinkerpop.gremlin.driver.ser.GryoMessageSerializerV3d0, config: { serializeResultToString: true }}
  10. Important

    You must provide IAM credentials to sign the requests. Type the following commands to set your credentials as environment variables, replacing the relevant items with your credentials.

    export AWS_ACCESS_KEY_ID=access_key_id export AWS_SECRET_ACCESS_KEY=secret_access_key export SERVICE_REGION=us-east-1|us-east-2|us-west-2|eu-west-1|eu-west-2|eu-central-1|ap-southeast-1|ap-southeast-2|ap-northeast-1

    The Neptune Version 4 Signer uses the default credential provider chain. For additional methods of providing credentials, see Using the Default Credential Provider Chain.

    The SERVICE_REGION variable is required, even when using a credentials file.

  11. In a terminal, navigate to the Gremlin Console directory (apache-tinkerpop-gremlin-console-3.3.2), and then type the following command to run the Gremlin Console.


    You should see the following output:

    \,,,/ (o o) -----oOOo-(3)-oOOo----- plugin activated: tinkerpop.server plugin activated: tinkerpop.utilities plugin activated: tinkerpop.tinkergraph gremlin>

    You are now at the gremlin> prompt. You will type the remaining steps at this prompt.

  12. At the gremlin> prompt, type the following to connect to the Neptune DB instance.

    :remote connect tinkerpop.server conf/neptune-remote.yaml
  13. At the gremlin> prompt, type the following to switch to remote mode. This sends all Gremlin queries to the remote connection.

    :remote console