Client driver quick start

Fauna has drivers for popular programming languages for programmatic database operations.

This quick start guides you through driver installation setup and shows how to programmatically submit an FQL query.

Create a database

  1. Sign up for a free account at https://dashboard.fauna.com/register and log in to your account.

  2. Click CREATE DATABASE to create a database.

  3. Give your database a Name.

  4. Choose your preferred Region Group.

  5. If you enable Backups, select the Backup Retention interval.

  6. Click the CREATE button.

    Your new database is listed on the Home page.

Get a database access token

You need an access token for your application code to access this database.

  1. In the Databases list, select your newly created database. This takes you to the Explorer page with your database highlighted.

  2. Hover over the database name to reveal the Keys icon. Click the key icon.

  3. In the Keys dialog, click CREATE KEY.

  4. The Database name is already populated. Choose Admin or Server Role and enter an optional Key Name.

  5. Click the SAVE button.

  6. Copy the KEY’S SECRET. This is the database access token that you must make available to your application.

Make sure you copy and save the secret and associate it with this database. This is the only time the secret is displayed.

Build and run an application

Fauna provides drivers for the supported programming languages, which make it easy to query your database. These steps are a simple, working setup and application that show you the basic programming requirements. To adapt an application to your programming environment, see the Supported drivers repositories for detailed setup options and driver capabilities.

Choose your programming language:

GoJavaScriptPython

 

  1. The drivers recognize the Fauna environment variables. Set the FAUNA_SECRET environment variable to your previously saved secret:

    export FAUNA_SECRET=<savedSecret>

  2. Install the Fauna driver:

    mkdir app
cd app
go mod init app
go get github.com/fauna/fauna-go
    npm install fauna
    pip install fauna

  3. This application creates a collection named myCollection and adds a People document to the collection.

    Learn more about the Collection Collection.create() and create() methods.

    Create an app.go file and add the following code:

    Create an app.mjs file and add the following code:

    Create an app.py file and add the following code:

    package main

import (
    "fmt"
    "github.com/fauna/fauna-go"
)

func main() {
    client, clientErr := fauna.NewDefaultClient()
    if clientErr != nil {
        panic(clientErr)
    }

    createColl, _ := fauna.FQL(`Collection.create({ name: "myCollection" })`, nil)
    if _, err := client.Query(createColl); err != nil {
        panic(err)
    }

    createPeople, _ := fauna.FQL(`myCollection.create({ name: ${name}})`, map[string]any{"name": "People"})
    res, err := client.Query(createPeople)
    if err != nil {
        panic(err)
    }

    fmt.Println(res.Data.(*fauna.Document).Data["name"])
}
    import { Client, fql } from "fauna";
//const fauna = require("fauna");

// configure your client
const client = new Client();

try {
  // build queries using the fql function
  const collection_query = fql`Collection.create({ name: "myCollection" })`;
  // execute the query
  const collection_result = await client.query(collection_query);

  // define some data in your app
  const people = { name: "People" };

  // query using your app's local variables
  const document_query = fql`
    myCollection.create(${people}) {
      id,
      ts,
      name
    }
  `;
  const document_result = await client.query(document_query);
  console.log(document_result);
} catch (error) {
  console.log(error)
}
    # Import the driver, and other required packages
from fauna import fql
from fauna.client import Client
from fauna.errors import FaunaException

# Instantiate a client
client = Client()

# Create a collection called 'myCollection'
try:
    # create a collection
    create_col = fql('Collection.create({ name: "myCollection" })')
    result = client.query(create_col)
    # Show the result
    print(result)
except FaunaException as e:
    # handle errors
    print(e)

  4. Run the application:

    go install .
app
    node app.mjs
    python app.py

    You should see the People document response:

    map[name:People]
    {
  data: {
    id: '361023370020520517',
    ts: TimeStub { isoString: '2023-04-03T21:32:45.610Z' },
    name: 'People'
  },
  summary: '',
  txn_ts: 1680557565610000,
  stats: {
    compute_ops: 1,
    read_ops: 1,
    write_ops: 1,
    query_time_ms: 75,
    contention_retries: 1,
    storage_bytes_read: 22,
    storage_bytes_write: 204
  }
}
    QuerySuccess(query_tags={},static_type=None,stats=QueryStats(stats={'compute_ops': 1, 'read_ops': 1, 'write_ops': 1, 'query_time_ms': 193, 'storage_bytes_read': 664, 'storage_bytes_write': 380, 'contention_retries': 0}),summary='',traceparent='00-d9575336f25822a9bbdb350b151eb408-b2a589f10cab38df-00',txn_ts=1682964369620000,data=NamedDocument(name='myCollection',coll=Module(name='Collection'),ts=datetime.datetime(2023, 5, 1, 18, 6, 9, 620000, tzinfo=datetime.timezone.utc),data={'indexes':{},'constraints':[]}))

    If myCollection already exists, Fauna returns a descriptive message that illuminates the cause of the error. You can create another database or change the name of the myCollection collection in this example application and try again.

    If an authentication error occurs, try creating another key and go through the quick start again.

Next step

Visit Fauna sample applications for more tutorials, code examples, and videos demonstrating how to use FQL in actual applications.

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!