Barrel
FR GitHub

A database per customer

Give every customer their own database, encrypted under their own key. Queries never need a tenant filter, and offboarding deletes the database and revokes every token issued for it.

Built from barrel_spaces and barrel_crypto, through the Erlang API. Your key store stays yours; Barrel only asks it for a key at open.

The problem

Customer data mixed in shared tables needs a tenant filter on every query, one missed filter leaks data, and deleting a customer means hunting their rows across tables and backups.

How it fits together

  1. Your SaaS backend

    • Onboarding one space per customer
    • Offboarding drop the space
  2. create, grant, drop
  3. Barrel, in your Erlang node

    • sp_acme Acme’s database, its own key
    • sp_globex Globex’s database, its own key
  4. one key per space
  5. Your key store

    • tenant_keys key_for_db/1, your module
    • KMS or vault holds the keys, never on disk

Each customer is a space: a database with its own files and its own key. The key provider resolves the key from the space id, so no key is written next to the data; a cleartext key-check file lets a wrong key fail at open instead of reading garbage.

Build it

Five steps in your Erlang application. The same spaces are reachable over REST and MCP, but those open spaces with default options, so encrypted spaces stay on the Erlang API for now.

  1. Write a key provider

    Barrel asks the provider for a key each time it opens a database, by its keyspace (the space id). Return exactly 32 bytes. An error fails the open.

    Erlang
    -module(tenant_keys).
    -behaviour(barrel_keyprovider).
    -export([key_for_db/1]).
    
    key_for_db(Keyspace) ->
        %% my_kms is your code: fetch or derive the key
        {ok, my_kms:data_key(Keyspace)}.
  2. Create one space per customer

    Documents, attachments in the default store, vectors and disk index files are encrypted under that key. Keep the returned id with the customer record.

    Erlang
    {ok, _} = application:ensure_all_started(barrel_spaces),
    Enc = #{provider => tenant_keys},
    {ok, #{id := Acme, db := Db}} =
        barrel_spaces:create_space(#{label => <<"acme">>,
                                     encryption => Enc}),
    {ok, _} = barrel:put_doc(Db, #{<<"id">> => <<"inv-1">>,
                                   <<"total">> => 1200}).
  3. Issue tokens for the customer’s agents

    A grant is scoped to one space. barrel_server checks it on every request; your code can also verify it directly.

    Erlang
    {ok, Token, _Grant} = barrel_caps:grant(Acme,
        #{rights => [read, write],
          subject => <<"acme-support-bot">>}),
    {ok, _} = barrel_caps:verify(Token, Acme, write).
  4. Pass the key spec on every open

    Encryption is runtime configuration. Without the spec an encrypted space does not open; with the wrong key it fails closed.

    Erlang
    {error, db_is_encrypted} =
        barrel_spaces:open_space(Acme),
    {ok, Space} =
        barrel_spaces:open_space(Acme, #{encryption => Enc}).
    From a recorded run
    open encrypted space without spec: {error,db_is_encrypted}
    open encrypted space with spec: ok
  5. Offboard the customer

    Dropping the space deletes its database, marks it dropped in the registry and revokes every grant issued for it. An encrypted space needs its spec to be opened for deletion.

    Erlang
    ok = barrel_spaces:drop_space(Acme,
                                  #{encryption => Enc}),
    {error, space_dropped} = barrel_spaces:open_space(Acme).
    From a recorded run (grants listed after the drop)
    open dropped: {error,space_dropped}
    grants after drop: [true,true]   %% revoked_at > 0

What Barrel does

  • Keeps each customer in a separate database with its own files
  • Encrypts documents, blob-store attachments, vectors and disk indexes under that database’s key
  • Refuses to open with a missing or wrong key
  • Scopes tokens to one space and revokes them all on drop

What your application does

  • Maps customers to space ids
  • Holds the keys in a KMS or vault and serves them to the provider
  • Passes the encryption spec on every open
  • Decides when to offboard, and what happens to backups

Limits

  • Attachments stored in S3 with barrel_att_s3 are not encrypted by database encryption: they sit in the bucket in plaintext. Use bucket-side encryption, or keep sensitive files in the default store.
  • Encrypted spaces are Erlang API only over REST and MCP for now.
  • No key rotation and no in-place encryption: replicate into a new database under a new key. A plaintext database cannot be opened encrypted (cannot_encrypt_existing_db).
  • A lost key means lost data.
  • The threat model is data at rest. The cipher is not authenticated, so an attacker who can write the files is out of scope, and keys in memory are not zeroized.
  • Code inside your node can open any space without a token; the key is what keeps one tenant from reading another.

Go further

Up and down to moveEnter to open