Connections

Fauna’s database service provides an HTTP endpoint where client applications can send their queries and expect to receive 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 specific Fauna database. Multiple asynchronous queries can be active at once via the CCO, where query-specific 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 specific database and specific permissions, which determine 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 your database’s Region Group.
Classic (US and EU): https://db.fauna.com:443
United States (US): https://db.us.fauna.com:443
Europe (EU): https://db.eu.fauna.com:443

timeout

Number

Optional - A query timeout expressed in milliseconds. After a query has been sent, if the timeout period elapses without a response from Fauna, the query’s connection 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 specific 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 containing 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 actually 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 your database’s Region Group.
Classic (US and EU): https://db.fauna.com:443
United States (US): https://db.us.fauna.com:443
Europe (EU): https://db.eu.fauna.com:443

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 via the current client connection object. When the timeout has elapsed without a response from Fauna, the query’s connection 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 your database’s Region Group.
Classic (US and EU): https://db.fauna.com:443
United States (US): https://db.us.fauna.com:443
Europe (EU): https://db.eu.fauna.com:443

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 via the current client connection object. When the timeout has elapsed without a response from Fauna, the query’s connection 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 connection’s User-Agent header.

withCustomHeaders(Map<String, String>)

Map<String, String>

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

withCheckNewVersion(boolean checkNewVersion)

String

Optional - A function that accepts a boolean. When true, the driver checks to see whether a new package has been published. 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.

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 your database’s Region Group.
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, a query’s connection is closed when the response has been 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 has been 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. This is most useful for event streaming clients.
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.

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 your database’s Region Group.
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 has been 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 your database’s Region Group.
Classic (US and EU): https://db.fauna.com:443
United States (US): https://db.us.fauna.com:443
Europe (EU): https://db.eu.fauna.com:443

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 has been sent, if the timeout period elapses without a response from Fauna, the query’s connection is closed.

userAgent

String

Optional - Specifies a custom HTTP User-Agent header.

customHeaders

Map[String, String]

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

checkNewVersion

Boolean

Optional - When true, the driver checks to see whether a new driver package has been published. When false, the version check does not occur.

The default is true.

Multiple connections

Whenever 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

Was this article helpful? 

We're sorry to hear that.
Tell us how we can improve!
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!