Skip to main content

FaunaDB Python driver

Project description

Python driver for FaunaDB.


$ pip install faunadb


The following versions of Python are supported:

  • Python 3.5

  • Python 3.6

  • Python 3.7

  • Python 3.8

  • Python 3.9


Driver documentation is available at

See the FaunaDB Documentation for a complete API reference, or look in tests for more examples.

Basic Usage

from faunadb import query as q
from faunadb.objects import Ref
from faunadb.client import FaunaClient

client = FaunaClient(secret="your-secret-here")

indexes = client.query(q.paginate(q.indexes()))


Document Streaming

Fauna supports document streaming, where changes to a streamed document are pushed to all clients subscribing to that document.

The following section provides an example for managing a document stream.

The streaming API is blocking by default, the choice and mechanism for handling concurrent streams is left to the application developer:

from faunadb import query as q
from faunadb.objects import Ref
from faunadb.client import FaunaClient

client = FaunaClient(secret="your-secret-here")

coll = client.query(q.create_collection({"name":"sc"}))
doc  = client.query(q.create(coll["ref"], {"data":{"x": 0}}))

stream = None
def on_start(event):
    print("started stream at %s"%(event.txn))
    client.query(q.update(doc["ref"], {"data": {"x": "updated"}}))

def on_version(event):
    print("on_version event at %s"%(event.txn))
    print("    event: %s"%(event.event))

def on_error(event):
    print("Received error event %s"%(event))
options = {"fields": ["document", "diff"]}
stream =["ref"], options, on_start, on_error, on_version)

Observing Metrics

Its possible to observe each query’s metrics by providing an “observer” callback.

More information on query metrics is available in the FaunaDB Documentation.

Here is a simple example:

from faunadb import query as q
from faunadb.client import FaunaClient
from faunadb.errors import FaunaError

# The observer callback, which takes the HTTP response for a query
def observe(response):
    h = response.response_headers
    print('bytesOut:', h["x-compute-ops"])
    print('queryTime:', h["x-query-time"])
    print('readOps:', h["x-byte-read-ops"])
    print('writeOps:', h["x-byte-write-ops"])
    print('retries:', h["x-txn-retries"])

# Connect to a local Fauna Dev instance
client = FaunaClient(

    result = client.query(
except FaunaError as err:
    print("err: ", err)

Building it yourself


$ virtualenv venv
$ source venv/bin/activate
$ pip install .


To run the tests you must have a FaunaDB database available. Then set the environment variable FAUNA_ROOT_KEY to your database’s root key. If you use FaunaDB cloud, this is the password you log in with.

Tip: Setting the FAUNA_QUERY_TIMEOUT_MS environment variable will set a timeout in milliseconds for all queries.

Then run make test. To test a single test, use e.g. python -m unittest tests.test_client.ClientTest.test_ping.

Tests can also be run via a Docker container with FAUNA_ROOT_KEY="your-cloud-secret" make docker-test (an alternate Alpine-based Python image can be provided via RUNTIME_IMAGE).


To run the tests with coverage, install the coverage dependencies with pip install .[coverage], and then run make coverage. A summary will be displayed to the terminal, and a detailed coverage report will be available at htmlcov/index.html.


GitHub pull requests are very welcome.


Copyright 2020 Fauna, Inc.

Licensed under the Mozilla Public License, Version 2.0 (the “License”); you may not use this software except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release. See tutorial on generating distribution archives.

Built Distribution

faunadb-4.3.1-py2.py3-none-any.whl (27.3 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page