View a markdown version of this page

Manage connection pools and lifecycle in containerized environments - Amazon Neptune
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Manage connection pools and lifecycle in containerized environments

Managing connections to Neptune effectively is essential in containerized environments where containers (pods in Kubernetes) start, stop, and scale frequently. Neptune enforces several WebSocket connection limits:

  • Each instance type has a maximum number of concurrent WebSocket connections

  • Idle connections are closed after 20–25 minutes of inactivity

  • With IAM authentication, connections are force-closed after 10 days regardless of activity (see WebSocket connection limits)

Some drivers support periodic keep-alive heartbeats to prevent idle disconnects. For example, the Gremlin Java driver's keepAliveInterval sends a periodic ping to the server. Consult your specific driver's configuration options to determine what keep-alive settings are available and how they interact with Neptune's idle timeout.

Understanding these limits helps you design connection handling that works well with container orchestration patterns like rolling deployments, autoscaling, and container recycling. For general guidance on connection management with the Java Gremlin driver, see Close the client to avoid the connections limit and Create a new connection after failover.

Close connections on container shutdown

Implement a graceful shutdown by adding a SIGTERM handler that closes your graph client before the container exits. For example, call Gremlin Java's cluster.close(), Gremlin's driverRemoteConnection.close() in Go or Python, or Bolt's driver.close() for the Neo4j driver. In Kubernetes, use a preStop hook to drain connections before SIGTERM is sent, especially during rolling updates.

Note

Docker and Amazon ECS only deliver SIGTERM to PID 1 in the container. Use the exec form in your Dockerfile (for example, ENTRYPOINT ["java", "-jar", "app.jar"] not ENTRYPOINT java -jar app.jar) or an init process like tini to ensure your application receives the signal.

Use a single client instance per container

Creating multiple Gremlin DriverRemoteConnection or Bolt neo4j.Driver instances in the same container multiplies connection usage. Share a single client instance across all threads in the container. The client objects are thread-safe.

Size connection pools relative to your fleet

Set maxConnectionPoolSize so that the total connections across all containers don't exceed the Neptune instance connection limit. For example, if you run 20 containers with 8 threads each, calculate the per-container pool size so that 20 × pool size stays within the instance limit for your instance type. For more information about configuring connection pool sizes, see Set maxInProcessPerConnection and maxSimultaneousUsagePerConnection to the same value.

Set a connection wait timeout

In the Java Gremlin driver, configure maxWaitForConnection to a reasonable value such as 5–10 seconds. The default is often infinite or very long, which causes threads to hang when the pool is exhausted rather than failing fast with a clear error. Not all language drivers support this setting—check your driver's documentation for the equivalent configuration option.