FaunaDB's Ruby driver is now "community-supported". If you are using this driver in production, it will continue to work as expected. However, new features won't be exposed in the driver unless the necessary changes are contributed by a community member. Please email [email protected] if you have any questions/concerns about the model or would like to take a more active role in the development of the driver (eg. partnering with us and operating as a "maintainer" for the driver).

The FaunaDB ruby driver is distributed as a gem. Install it via:

$ gem install fauna

Or if you use Bundler, add it to your application's Gemfile:

gem 'fauna'

And then execute:

$ bundle

The driver documentation is hosted on GitHub Pages.

Please see the FaunaDB Documentation for a complete API reference, or look in /test for more examples.

Tested and compatible with the following ruby versions:

• MRI 1.9.3
• MRI 2.2.3
• Jruby 1.7.19

First, require the gem:

require 'fauna'

All API requests pass through a Fauna::Client. Creating a client requires either an admin key, server key, client key, or a token.

server_key = 'ls8AkXLdakAAAALPAJFy3LvQAAGwDRAS_Prjy6O8VQBfQAlZzwAA'

Now we can make a database-level client:

$fauna = Fauna::Client.new(secret: server_key)

You can optionally configure an observer on the client. To ease debugging, we provide a simple logging observer at Fauna::ClientLogger.logger, which you can configure as such:

require 'logger'
logger = Logger.new(STDERR)
observer = Fauna::ClientLogger.logger { |log| logger.debug(log) }

$fauna = Fauna::Client.new(
  secret: server_key,
  observer: observer)

Now that we have a client, we can start performing queries:

# Create a class
$fauna.query { create ref('classes'), name: 'users' }

# Create an instance of the class
taran = $fauna.query do
  create ref('classes/users'), data: { email: '[email protected]' }
end

# Update the instance
taran = $fauna.query do
  update taran[:ref], data: {
    name: 'Taran',
    profession: 'Pigkeeper'
  }
end

# Page through a set
pigkeepers = Fauna::Query.expr { match(ref('indexes/users_by_profession'), 'Pigkeeper') }
oracles = Fauna::Query.expr { match(ref('indexes/users_by_profession'), 'Oracle') }

$fauna.query { paginate(union(pigkeepers, oracles)) }

# Delete the user
$fauna.query { delete taran[:ref] }

You can run tests against FaunaDB Cloud yourself. Create an admin key and set FAUNA_ROOT_KEY environment variable to it's secret. Then run rake spec:

export FAUNA_ROOT_KEY='kqnPAbijGhkgAAC03-36hjCvcTnWf4Pl8w97UE1HeWo'
rake spec

To run a single test, use e.g. ruby test/client_test.rb.

Coverage is automatically run as part of the tests. After running tests, check coverage/index.html for the coverage report. If using jruby, use JRUBY_OPTS="--debug" bundle exec rake spec to ensure coverage is generated correctly.

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

GitHub pull requests are very welcome.