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.

var client = new FaunaClient(secret: "YOUR_FAUNA_SECRET");
client := f.NewFaunaClient("YOUR_FAUNA_SECRET")
FaunaClient client = FaunaClient.builder()
    .withSecret("YOUR_FAUNA_SECRET")
    .build();
const client = new faunadb.Client({ secret: 'YOUR_FAUNA_SECRET' })
client = FaunaClient(secret="YOUR_FAUNA_SECRET")
Connections are not possible using Shell syntax

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

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/

Since the introduction of Region Groups, three cloud URLs are available. Use the correct URL for the Region Group for your database Group.

  • Classic (US and EU): https://db.fauna.com/

  • United States (US): https://db.us.fauna.com/

  • Europe (EU): https://db.eu.fauna.com/

timeout

Number

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

httpClient

An httpClient-compatible client object

Optional - An instantiated HTTP client object that is compatible with the .Net Core httpClient. This is useful when your client application needs to use a custom HTTP client library.

httpVersion

HttpClient constant

Optional - When using the default httpClient, you can specify which version to use, which should correspond to the .Net Core version that your client application is using. The default is HttpVersion.Version11.

customHeaders

Dictionary<string, string>

Optional - A string dictionary with custom HTTP request headers and their associated values.

checkNewVersion

Boolean

Optional - When true, checks for a new NuGet package version of the driver. When false, no version check is performed. The default is true.
Most of the parameters listed below are function calls. Go does not support optional function parameters, so specifying optional values must be handled with function calls.
Parameter Type Definition and Requirements

secret

String

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.

f.Endpoint(<url>)

A function that accepts a String

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

Since the introduction of Region Groups, three cloud URLs are available. Use the correct URL for the Region Group for your database Group.

  • Classic (US and EU): https://db.fauna.com/

  • United States (US): https://db.us.fauna.com/

  • Europe (EU): https://db.eu.fauna.com/

f.HTTP(*http.Client)

A function that accepts a pointer to a replacement http.Client

Optional - A function to configure a replacement http.Client implementation. The replacement must have API compatibility with http.Client in the standard Go library.

f.Headers(map[string]string)

A function that accepts a list of HTTP headers to send with queries

Optional - A function to configure a list of HTTP headers to send with queries.

f.QueryTimeoutMS(number)

A function that accepts a Number

Optional - The function to configure a transaction timeout, expressed in milliseconds. The timeout applies all queries executed with the current client connection object. When the timeout has elapsed without a response from Fauna, the connection for the query is closed.

The default timeout is 60,000 milliseconds (60 seconds).

f.Observer(*ObserverCallback)

A function that accepts a pointer to an ObserverCallback function

Optional - A function to configure an ObserverCallback function. When the ObserverCallback is defined, it is called with the raw HTTP response object for every query executed.
The Java driver uses the Builder pattern to compose the options for the client connection object. Each option must be expressed as a builder function call.
Parameter Type Definition and Requirements

withSecret(String secret)

A function that accepts a String

The String 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.

withEndpoint(String endpoint)

String

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

Since the introduction of Region Groups, three cloud URLs are available. Use the correct URL for the Region Group for your database Group.

  • Classic (US and EU): https://db.fauna.com/

  • United States (US): https://db.us.fauna.com/

  • Europe (EU): https://db.eu.fauna.com/

withMetrics(MetricRegistry registry)

String

Optional - A function that accepts a MetricRegistry which registers and tracks connection-level metrics.

withQueryTimeout(Duration timeout)

String

Optional - A function that accepts a transaction timeout, expressed in milliseconds. The timeout applies to all queries executed with the current client connection object. When the timeout has elapsed without a response from Fauna, the connection for the query is closed.

The default timeout is 60,000 milliseconds (60 seconds).

withUserAgent(String userAgent)

String

Optional - A function that accepts a string to use in the HTTP User-Agent header.

withCustomHeaders(Map<String, String>)

Map<String, String>

Optional - A function that accepts a string map with custom HTTP request headers and their associated values.

withCheckNewVersion(boolean checkNewVersion)

String

Optional - A function that accepts a boolean. When true, the driver checks for a new package version. When false, the version check does not occur.

The default is true.
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/

Since the introduction of Region Groups, three cloud URLs are available. Use the correct URL for the Region Group for your database Group.

  • Classic (US and EU): https://db.fauna.com/

  • United States (US): https://db.us.fauna.com/

  • Europe (EU): https://db.eu.fauna.com/

domain

String

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

Since the introduction of Region Groups, three cloud domains are available. Use the correct domain for the Region Group for your database.

  • Classic (US and EU): db.fauna.com

  • United States (US): db.us.fauna.com

  • Europe (EU): db.eu.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.
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/

Since the introduction of Region Groups, three cloud URLs are available. Use the correct URL for the Region Group for your database Group.

  • Classic (US and EU): https://db.fauna.com/

  • United States (US): https://db.us.fauna.com/

  • Europe (EU): https://db.eu.fauna.com/

domain

String

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

Since the introduction of Region Groups, three cloud domains are available. Use the correct domain for the Region Group for your database.

  • Classic (US and EU): db.fauna.com

  • United States (US): db.us.fauna.com

  • Europe (EU): db.eu.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.

timeout

Number

Optional - A query timeout expressed in seconds. 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.

observer

A function

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

pool_connections

Number

Optional - The number of HTTP connections to save in the connection pool.

pool_maxsize

Number

Optional - The maximum number of HTTP connections to save in the pool.
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/

Since the introduction of Region Groups, three cloud URLs are available. Use the correct URL for the Region Group for your database Group.

  • Classic (US and EU): https://db.fauna.com/

  • United States (US): https://db.us.fauna.com/

  • Europe (EU): https://db.eu.fauna.com/

metrics

A MetricRegistry function

Optional - A MetricRegistry function that registers and tracks connection-level metrics.

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 connection for the query is closed.

userAgent

String

Optional - Specifies a custom HTTP User-Agent header.

customHeaders

Map[String, String]

Optional - A string map with custom HTTP request headers and their associated values.

checkNewVersion

Boolean

Optional - When true, the driver checks for a new driver package. When false, the version check does not occur.

The default is true.

There are no connection options available for the Dashboard’s Shell.

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

The following example demonstrates how to connect to a Fauna instance running in the United States (US) Region Group:

var client = new FaunaClient(
    secret: "YOUR_FAUNA_SECRET",
    endpoint: "https://db.us.fauna.com:443/"
);
client := f.NewFaunaClient(
	"YOUR_FAUNA_SECRET",
	f.Endpoint("https://db.us.fauna.com:443/"),
)
FaunaClient client = FaunaClient.builder()
    .withSecret("YOUR_FAUNA_SECRET")
    .withEndpoint("https://db.us.fauna.com:443/")
    .build();
const client = new faunadb.Client({
  secret: 'YOUR_FAUNA_SECRET',
  domain: 'db.us.fauna.com',
  port: 443,
  scheme: 'https',
})
client = FaunaClient(
  secret="YOUR_FAUNA_SECRET",
  domain="db.us.fauna.com",
  port=443,
  scheme="https"
)
Connections are not possible using Shell syntax

The following example demonstrates how to connect to a Fauna Dev instance running on localhost on port 8443:

var client = new FaunaClient(
    secret: "YOUR_FAUNA_SECRET",
    endpoint: "http://localhost:8443/"
);
client := f.NewFaunaClient(
	"YOUR_FAUNA_SECRET",
	f.Endpoint("http://localhost:8443/"),
)
FaunaClient client = FaunaClient.builder()
    .withSecret("YOUR_FAUNA_SECRET")
    .withEndpoint("http://localhost:8443/")
    .build();
const client = new faunadb.Client({
  secret: 'YOUR_FAUNA_SECRET',
  domain: 'localhost',
  port: 8443,
  scheme: 'http',
})
client = FaunaClient(
  secret="YOUR_FAUNA_SECRET",
  domain="localhost",
  port=8443,
  scheme="http"
)
Connections are not possible using Shell syntax

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!