Repository files navigation

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 emailproduct@fauna.com 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'sGemfile:

gem 'fauna'

And then execute:

$ bundle

The driver documentation ishosted on GitHub Pages.

Please see theFaunaDB Documentation fora complete API reference, or look in/test for moreexamples.

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 aFauna::Client. Creating a clientrequires 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 anobserver on the client. To easedebugging, we provide a simple logging observer atFauna::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{createref('classes'),name:'users'}# Create an instance of the classtaran= $fauna.querydocreateref('classes/users'),data:{email:'taran@example.com'}end# Update the instancetaran= $fauna.querydoupdatetaran[:ref],data:{name:'Taran',profession:'Pigkeeper'}end# Page through a setpigkeepers=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{deletetaran[:ref]}

You can run tests against FaunaDB Cloud yourself.Create an admin key and setFAUNA_ROOT_KEY environment variable to it's secret. Then runrake 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, checkcoverage/index.html for the coverage report. If using jruby, useJRUBY_OPTS="--debug" bundle exec rake spec to ensure coverage is generatedcorrectly.

Tests can also be run via a Docker container withFAUNA_ROOT_KEY="your-cloud-secret" make docker-test (an alternateAlpine-based Ruby image can be provided viaRUNTIME_IMAGE).

GitHub pull requests are very welcome.

Copyright 2017Fauna, Inc.

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

http://mozilla.org/MPL/2.0/

Unless required by applicable law or agreed to in writing, softwaredistributed under the License is distributed on an "AS IS" BASIS,WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express orimplied. See the License for the specific language governingpermissions and limitations under the License.