Documentation is unclear about when actual server connection occurs

[robross0606]

Unless I'm missing it, the documentation is very unclear about when initial connection to the database occurs. The documentation for new Database() implies a connection pool is created, but doesn't state if an actual network connection is initialized at that point. But initializing a network connection in a constructor feels like a bit of a code smell to me. Which API calls initialize an actual network connection?

[pluma4345]

As ArangoDB uses HTTP and the driver currently uses HTTP1, connections are only opened as necessary rather than in advance. With keep-alive (the default), the connections will however be reused and may remain open after the first use.

[pluma4345]

I'm converting this to a discussion as this is not really an bug or feature request.

[robross0606]

What does "as necessary" mean from a practical point of view though? Consider if the Arango instance were not available. Where would we expect connection errors to occur in that situation? Could they occur on new Database() invocations? Without knowing when/where to expect connection effort, it is difficult to manage our own application lifecycle properly. Consider, for example, random back-off policy in a microservices environment where an Arango server is not guaranteed to be up first. In that scenario, we have to have some idea of when the API will attempt first connection.

[robross0606]

Perhaps there is a better way to ask the question: What is the best way during application start-up to "check" if a connection is available to the Arango server using this library?

[pluma4345]

The short answer is that arangojs in Node uses the native http.Agent (or https.Agent) so its behavior is defined by that.

The long answer is that when you do a request for the first time, a TCP connection is opened, the request is sent and the connection is added to the pool. As I understand it, Node will add additional connections to the pool when all existing connections are busy. When using keepAlive, the server will be instructed to keep the connections open rather than closing them upon returning a response.

HTTP (1) is a one-shot protocol: a request is sent, the client waits for a response, the server responds and closes the connection. KeepAlive works around this by asking the server to please not close the connection but it may still time out eventually. This means there's no use in "pre-heating" the connection pool (i.e. opening all the connections in advance) as they may have timed out by the time you want to use them, resulting in unexpected errors.

If you want to know if the server is available, you can use something like db.version() to check if it responds - keep in mind that even this endpoint requires authentication to be set up first though.

[pluma4345]

Further adding to this: as a rule of thumb, if the method is marked as async or returns a promise, it involves a server request. Otherwise, it doesn't. new Database does not trigger a network request. db.collection does not trigger a network request. db.query does.

[robross0606]

Thank you for the advice.