Connections

The Fauna database service provides an HTTP endpoint where client applications can send their queries and expect to get responses for those queries.

Each connection is a standard lightweight HTTP connection that typically lasts for the duration that a query is executing. Some drivers support persisting a connection using HTTP keep-alive.

Each driver implements its own connection management, so your client applications do not need to implement connection pools, or other connection management strategies.

The client connection object

Each driver implements a client connection object (CCO), which represents a logical connection to a Fauna database. Multiple asynchronous queries can be active at once using the CCO, where HTTP connections are established as needed.

Copied!
const client = new faunadb.Client({ secret: 'YOUR_FAUNA_SECRET' })

The string YOUR_FAUNA_SECRET needs to be replaced with the secret from a key, token, or with the JWT provided by a third-party identity provider.

The secret is an authentication+authorization token that is associated with a database and its role, which decide whether the query should be executed. See the Security section for details.

Connection options

Parameter Type Definition and Requirements

secret

String

This is the authorization token which is associated with the database that you want to query. It can be the secret from a key, token, or it can be a JWT from the third-party identity provider.

endpoint

String

Optional - The endpoint URL to connect to. The default is https://db.fauna.com:443/

domain

String

Optional - The domain name of the target endpoint. The default is db.fauna.com.

port

Number

Optional - The port of the target endpoint. The default is 443.

scheme

Number

Optional - The HTTP scheme of the target endpoint. The default is https. Only http and https work.

observer

A callback function

Optional - When defined, the callback function is called with the raw HTTP response object for every query executed.

keepAlive

Boolean

Optional - When true, the drivers applies the HTTP Keep-Alive header to persist connections as long as possible. When false, the connection is closed when the response is received.

The default is true.

headers

Object

Optional - An object that is used to define custom HTTP headers.

fetch

A function

Optional - A function that provides a custom implementation of fetch.

queryTimeout

Number

Optional - A query timeout expressed in milliseconds. After a query is sent, if the timeout period elapses without a response from Fauna, the HTTP connection is closed and the result is abandoned.

http2SessionIdleTime

Number

Optional - A timeout expressed in milliseconds. It specifies the maximum time that an HTTP/2 session can remain active with no activity. The timeout only applies to query connections. Streaming connections are intended to be held open indefinitely.

The default is 500 milliseconds. The maximum accepted value is 5000 milliseconds.

Multiple connections

When you need to connect to Fauna using different secrets, endpoints, or other settings, create a new client connection object for each different kind of connection that you need to use.

Examples

  1. Connect to Fauna using default values. The secret is associated with your database in its Region Group, with the privileges of its key, token, or JWT.

    Copied!
    const client = new faunadb.Client({
  secret: 'YOUR_FAUNA_SECRET',
})

  2. Connect to a Fauna Dev instance running on localhost on port 8443:

    Copied!
    const client = new faunadb.Client({
  secret: 'YOUR_FAUNA_SECRET',
  endpoint: 'http://localhost:8443/',
})

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!