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

Amazon Neptune Endpoints

You can connect to DB instances in an Amazon Neptune DB cluster by using an endpoint. An endpoint is a URL that contains a host address and a port. The following endpoints are available from a Neptune DB cluster.

Cluster endpoint

A cluster endpoint is an endpoint for a Neptune DB cluster that connects to the current primary DB instance for that DB cluster. Each Neptune DB cluster has a cluster endpoint and one primary DB instance.

The cluster endpoint provides failover support for read/write connections to the DB cluster. Use the cluster endpoint for all write operations on the DB cluster, including inserts, updates, deletes, and data definition language (DDL) changes. You can also use the cluster endpoint for read operations, such as queries.

If the current primary DB instance of a DB cluster fails, Neptune automatically fails over to a new primary DB instance. During a failover, the DB cluster continues to serve connection requests to the cluster endpoint from the new primary DB instance, with minimal interruption of service.

The following example illustrates a cluster endpoint for an Neptune DB cluster.

mydbcluster.cluster-123456789012.us-east-1.neptune.amazonaws.com:8182

Reader endpoint

A reader endpoint is an endpoint for a Neptune DB cluster that connects to one of the available Neptune Replicas for that DB cluster. Each Neptune DB cluster has a reader endpoint. If there is more than one Neptune Replica, the reader endpoint directs each connection request to one of the Neptune Replicas.

The reader endpoint provides round robin routing for read-only connections to the DB cluster. Use the reader endpoint for read operations, such as queries. You can't use the reader endpoint for write operations.

The reader endpoint round robin routing works by changing the host that the DNS entry points to.

Each time you resolve the DNS, you get a different IP and connections are opened against those IPs. Once a connection is established, all the requests for that connection are sent to the exact same host.

The client must create a new connection and resolve the DNS record again to get a connection to potentially different read replica.

Note

WebSockets connections are often kept alive for long periods. To get different read replicas you must:

  • Ensure your client resolves the DNS entry each time it connects.

  • Close the connection and reconnect.

Various client software may resolve DNS in different ways. For example, if your client resolves DNS and then uses the IP for every connection, it will direct all requests to a single host.

DNS caching for clients or proxies will resolve the DNS name to the same endpoint from the cache. This is a problem for both round robin routing and failover scenarios.

Note

Disable any DNS caching settings to force DNS resolution each time.

The DB cluster distributes connection requests to the reader endpoint among available Neptune Replicas. If the DB cluster contains only a primary DB instance, the reader endpoint serves connection requests from the primary DB instance. If a Neptune Replica is created for that DB cluster, the reader endpoint continues to serve connection requests to the reader endpoint from the new Neptune Replica, with minimal interruption in service.

The following example illustrates a reader endpoint for a Neptune DB cluster.

mydbcluster.cluster-ro-123456789012.us-east-1.neptune.amazonaws.com:8182

Instance endpoint

An instance endpoint is an endpoint for a DB instance in a Neptune DB cluster that connects to that specific DB instance. Each DB instance in a DB cluster, regardless of instance type, has its own unique instance endpoint. So, there is one instance endpoint for the current primary DB instance of the DB cluster, and there is one instance endpoint for each of the Neptune Replicas in the DB cluster.

The instance endpoint provides direct control over connections to the DB cluster, for scenarios where using the cluster endpoint or reader endpoint might not be appropriate. For example, your client application might require fine-grained load balancing based on workload type. In this case, you can configure multiple clients to connect to different Neptune Replicas in a DB cluster to distribute read workloads.

The following example illustrates an instance endpoint for a DB instance in a Neptune DB cluster.

mydbinstance.123456789012.us-east-1.neptune.amazonaws.com:8182

Endpoint Considerations

Some considerations for working with Neptune endpoints are as follows:

  • Before using an instance endpoint to connect to a specific DB instance in a DB cluster, consider using the cluster endpoint or reader endpoint for the DB cluster instead.

    The cluster endpoint and reader endpoint provide support for high-availability scenarios. If the primary DB instance of a DB cluster fails, Neptune automatically fails over to a new primary DB instance. It does so by either promoting an existing Neptune Replica to a new primary DB instance or creating a new primary DB instance. If a failover occurs, you can use the cluster endpoint to reconnect to the newly promoted or created primary DB instance, or use the reader endpoint to reconnect to one of the other Neptune Replicas in the DB cluster.

    If you don't take this approach, you can still make sure that you're connecting to the right DB instance in the DB cluster for the intended operation. To do so, you can manually or programmatically discover the resulting set of available DB instances in the DB cluster and confirm their instance types after failover, before using the instance endpoint of a specific DB instance.

    For more information about failovers, see Fault Tolerance for a Neptune DB Cluster.

  • The reader endpoint only directs connections to available Neptune Replicas in a Neptune DB cluster. It does not direct specific queries.

    Important

    Neptune does not load balance.

    If you want to load-balance queries to distribute the read workload for a DB cluster, you need to manage that in your application and use instance endpoints to connect directly to Neptune Replicas to balance the load.

  • The reader endpoint round robin routing works by changing the host that the DNS entry points to. The client must create a new connection and resolve the DNS record again to get a connection to potentially new read replica.

  • During a failover, the reader endpoint might direct connections to the new primary DB instance of a DB cluster for a short time, when a Neptune Replica is promoted to the new primary DB instance.

On this page: