README

This repository contains unofficial patterns, sample code, or tools to help developers build more effectively with Fauna. All Fauna Labs repositories are provided “as-is” and without support. By using this repository or its contents, you agree that this repository may never be officially supported and moved to the Fauna organization.

Serverless Fauna

This Serverless Framework plugin allows you to manage Fauna databases and resources directly in your serverless.yml file. You can integrate it in your test and CI/CD pipeliness to keep your databases in sync across multiple environments. Visit [this repository][serverless-fauna-example] for a sample application that demonstrates how to create, update, and delete collections, indexes, roles, and user-defined functions (UDFs).

Serverless Fauna

Installation

$ npm install @fauna-labs/serverless-fauna --save-dev

or using yarn

$ yarn add @fauna-labs/serverless-fauna

Commands

This plugin listens to hooks from default serverless commands, and runs its own logic:

command	description
serverless deploy	sync Fauna resources specified a config. All resources created by the plugin has boolean property `created_by_serverless_plugin` set to `true`
serverless remove	sync Fauna resources created by plugin read more about deleting policy

If you would like to run only the Fauna plugin logic, you can just add fauna before the command. (ex: serverless fauna deploy)

Configuration

plugins:
  - "@fauna-labs/serverless-fauna"
fauna:
  client:
    secret: ${env:FAUNA_ROOT_KEY}
    # domain: db.fauna.com
    # port: 433
    # scheme: https
  collections:
    Movies: 
      name: Movies
      data:
        some_data_key: some_data_value

  functions:
    double:
      name: double
      body: ${file(./double.fql)}

  indexes:
    movies_by_type:
      name: movies_by_type
      source: ${self:fauna.collections.Movies.name}
      terms:
        fields: 
          - data.type

    movies_by_category:
      name: movies_by_category
      source: ${self:fauna.collections.Movies.name}
      data:
        some_data_key: some_data_value
      terms:
        fields: 
          - data.category

    sort_by_year:
      name: sort_by_year
      source: ${self:fauna.collections.Movies.name}
      values:
        fields:
          - data.type
          - ref

Collection configuration

Accepts the same params as Fauna's CreateCollection query

collections:
  Movies: 
    name: Movies
    history_days: 30
    ttl_days: 10
    data:
      some_data_key: some_data_value

Function configuration

Accepts the same params as Fauna's CreateFunction query

  functions:
    double:
      name: double
      body: ${file(./double.fql)}
      role: admin
      data:
        desc: double number

Index configuration

Accepts the same params as Fauna's CreateIndex query.

In Fauna's indexes, terms, values and source can only be set during index creation. If you try to modify those fields in an existing index, the plugin will throw an error.

search_by_category_and_sort_by_year:
  name: search_by_category_and_sort_by_year
  source: 
    collection: ${self:fauna.collections.Movies.name}
    fields: 
      is_current_year: ${file(./IsCurrentYear.fql)}
  terms:
    fields:
      -data.category
  values:
    fields:
      - path: data.type
        reverse: true
      - ref
    bindings:
      - is_current_year

Index source

The index source could be a string, and will be interpreted as collection reference.

source: Movie

Or it could be a source object

source:
  collection: Movie

Or it could be an array of objects:

source:
  - collection: Movies
  - collection: Cartoons
  - collection: Series

Index terms

Index terms describe the fields that should be searchable.

terms:
  fields:
    - data.search
  bindings:
    - binding

Index values

Index values describe the fields returned, and have a similar structure to terms, but with an additional reverse field to define sort order.

values:
  fields:
    - path: data.field
      reverse: true
  bindings:
    - binding

Index binding

Index bindings allow you to compute fields for a source while the document is being indexed.

You can specify multiline FQL:

source:
  collection: Movies
  fields:
    is_current_year: >
      Equals([
        Year(Now()),
        ToInteger(Select(['data', 'release_year'], Var('doc')))
      ])

Or you can create file with the .fql extension, and use the Fauna VSCode plugin to handle your .fql files.

source:
  collection: Movies
  fields:
    is_current_year: ${file(./IsCurrentYear.fql)}

Role configuration

Accepts the same params as Fauna's CreateRole query.

  roles:
    movies_reader:
      name: movies_reader
      privileges:
        - collection: ${self:fauna.collections.movies.name}
          actions:
            read: true
        - index: ${self:fauna.indexes.movies_by_type.name}
          actions:
            read: true
        - function: ${self:fauna.functions.double.name}
          actions:
            call: true

Role schema privileges

Read more about the privilege configuration object

For schema privileges, just specify a field key without a value:

roles:
  read_collections_and indexes:
    name: read_collections
    privileges:
      - collections:
        actions:
          read: true
      - indexes:
        actions:
          read: true

You can also pass action predicates:

editors:
  name: editors
  membership:
    - ${self:fauna.collections.scriptwriters.name}
    - ${self:fauna.collections.directors.name}
  privileges:
    - collection: ${self:fauna.collections.movies.name}
      actions:
        read: true
        write: ${file(./CanModifyMovie.fql)}

Role membership

A membership configuration object dynamically defines which authenticated resources are members of a given role.

It could be a string:

roles:
  actor:
    name: actor
    membership: actor

Or it could be an array:

roles:
  actor:
    name: participant
    membership: 
      - actor
      - directors

Or you could pass the full membership object

roles:
  only_active:
    name: only_active
    membership:
      resource: ${self:fauna.collections.users.name}
      predicate: ${file(./IsActiveUser.fql)}

Or even an array of membership objects:

roles:
  only_active:
    name: only_granted
    membership:
      - resource: ${self:fauna.collections.users.name}
        predicate: ${file(./IsGranted.fql)}
      - resource: ${self:fauna.collections.managers.name}
        predicate: ${file(./IsGranted.fql)}

Deletion policy

This plugin keeps your Fauna database in sync with your serverless configuration file. Therefore, the plugin will remove any resources that currently exist in Fauna, but are not declared in your serverless.com configuration file.

If there are resources that you absolutely do not want deleted, even though they might not be in your serverless.com configuration, you can set deletion_policy to retain (the default being destroy) in the top level fauna configuration. In example below, Fauna resources will not be deleted:

fauna: 
  deletion_policy: retain

Please note that if you specify the deletion_policy at both the top level and the resource level, the resource level deletion_policy will override it. For example, in the following configuration, the collection logs would be removed and the rest of the resources would be saved:

fauna:
  deletion_policy: retain
collections:
  Movies: 
    name: Movies
  logs:
    name: logs
    deletion_policy: destroy

Usage no npm install needed!