Local Amazon Neptune Development with G.V() and LocalStack, the AWS Cloud Emulator

This article will cover how to connect your locally running Amazon Neptune database powered by LocalStack using G.V() – Gremlin IDE. To support this, we’ll use the AWS CLI to create a Neptune database on your local machine and start a connection while loading and querying data interactively on G.V().


Before we start, let’s quickly introduce LocalStack, Amazon Neptune, and G.V().

LocalStack is a cloud development framework which powers a core cloud emulator that allows you to run your cloud & serverless applications locally. It helps developers work faster by supporting them to build, test, and launch applications locally — while reducing costs and improving agility. The emulator supports various AWS services like S3, Lambda, DynamoDB, ECS, and Kinesis. LocalStack also works with tools and frameworks like AWS CLI, CDK, and Terraform, making it easy for users to connect to the emulator when building and testing cloud apps.

Amazon Neptune is a managed graph database service designed to handle complex datasets with many connections. It’s schema-free and uses the Neptune Analytics engine to quickly analyze large amounts of graph data, providing insights and trends with minimal latency. Users can control access using AWS IAM and query data using languages like TinkerPop Gremlin and RDF 1.1 / SPARQL 1.1.

LocalStack supports Amazon Neptune as part of its core cloud emulator. Using LocalStack, you can use Neptune APIs in your local environment supporting both property graphs and RDF graph models.

G.V() is a Gremlin IDE – its purpose is to complement the Apache TinkerPop database ecosystem with software that is easy to use and install, and provides essential facilities to query, visualize, and model the graph data. If you want to find out more about G.V(), check out From Gremlin Console to Gremlin IDE with G.V().


gdotv and LocalStack have partnered to offer a free trial of both LocalStack’s core cloud emulation and G.V() that you can take advantage of now if you haven’t already!

To get started, you’ll need the following:

Once you’ve done all the above, you’ll be ready to connect G.V() to your database and run queries.

Connecting G.V() to your LocalStack Neptune Database

Connecting G.V() to your LocalStack Neptune Graph database is quick and easy.

To create a LocalStack Neptune Graph database, follow these steps:

  • Start your LocalStack instance using either localstack CLI or a Docker/Docker-Compose setup.
  • Create a LocalStack Neptune cluster using Amazon’s CreateDBCl3uster API with the AWS CLI:
awslocal neptune create-db-cluster \ 
--engine neptune \
--db-cluster-identifier my-neptune-db
  • Add a LocalStack Neptune instance using Amazon’s CreateDBInstance API with the AWS CLI:
awslocal neptune create-db-instance \ 
--db-cluster-identifier my-neptune-db \
--db-instance-identifier my-neptune-instance \
--engine neptune \
--db-instance-class db.t3.medium

After starting the LocalStack Neptune database, you can see the Address and Port in the Endpoint field. Navigate to the G.V() IDE and follow the instructions:

  • Click on New Database Connection.
  • Choose the Graph Technology Type as LocalStack.
  • Enter localhost.localstack.cloud as the hostname and 4510 as the port. Customize the values if you have a different hostname and port.
  • Click on Test Connection. G.V() will make sure it can connect to your LocalStack Neptune database. It will then present a final screen summarizing your connection details, which you can now save by clicking Submit.

This will transition to a new query window. Now that your LocalStack Neptune database is up and running in G.V(), let’s run some Gremlin queries:

g.addV('person').property('name', 'Alice').property('age', 30)

Once complete, you can see the summary, results, vertices, graph, and more in the G.V() IDE.

For a more in depth look at using G.V() and LocalStack Neptune together, check out LocalStack’s announcement blog post and this LocalStack Neptune development presentation.


We’re only beginning to see the potential of LocalStack Neptune and G.V() when used together. This post shows how you can easily start working with setting up LocalStack Neptune on G.V() and running basic Gremlin queries. LocalStack also supports other AWS services, which allows you to test integrations supported by Neptune and shift left your database development without maintaining additional dependencies or mocks.