Barrel
EN GitHub

barrel_docdb

Une base de documents intégrée, sur RocksDB. Les écritures sont versionnées par horloges logiques hybrides et vecteurs de version, chaque chemin est indexé pour les requêtes, et les bases se répliquent en active-active.

Ce qu’elle résout

Les copies d’une même donnée sur plusieurs nœuds, appareils ou agents reçoivent des écritures pendant qu’elles sont séparées. barrel_docdb garde chaque version concurrente comme un conflit au lieu d’en perdre une, vous laisse le résoudre, et vous donne sur le même stockage des requêtes, un flux de changements, des pièces jointes, un historique conservé avec sa provenance, un TTL et des branches.

Quand l’utiliser

  • Vous avez besoin de documents synchronisés entre nœuds ou sites, avec des conflits conservés et résolubles.
  • Vous avez besoin de requêtes sur n’importe quel champ sans déclarer d’index, avec find/2 ou BQL.
  • Vous avez besoin d’une piste d’audit : qui a écrit chaque version, et le contenu des versions passées.

Quand ne pas l’utiliser

  • Il vous faut aussi des vecteurs ou de la recherche sémantique : utilisez barrel, qui associe cette bibliothèque à un magasin de vecteurs.
  • Il vous faut des agrégats, GROUP BY ou des jointures : BQL n’en a pas.

Sa place dans Barrel

Repose sur
barrel_crypto
Fonctionne avec, si présente
barrel_att_s3 : stocke les octets des pièces jointes dans un stockage compatible S3
Autres dépendances
rocksdb, hackney, hlc, match_trie, mimerl, instrument
Seule
Oui. La réplication (barrel_rep, barrel_rep_tasks) et BQL pour les documents sont ici.

Installation

dépendances rebar.config
{barrel_docdb, "~> 3.1"}

La version 2.1.0 a changé la réplication. Une mise à jour depuis la 2.0 peut demander barrel_rep:reconcile/3.

Configuration

Options de create_db/2

CléDéfautRôle
data_dir data_dir de l’environnement Emplacement des fichiers de la base
att_opts magasin de blobs RocksDB #{backend => none} le désactive, s3 utilise barrel_att_s3
encryption désactivé default ou #{provider => Mod}
channels aucun #{Name => [Pattern]}, fixé à la création
retention_period 2592000 s (30 jours) Historique conservé ; 0 désactive le nettoyage
ttl_sweep_interval 0 (désactivé) Nettoyage en arrière-plan des documents expirés
max_conflict_versions 8 Conflits conservés par document
conflict_resolver aucun Résolution automatique à la réplication

Environnement de l’application (barrel_docdb)

CléDéfautRôle
data_dir "data/barrel_docdb" Relatif au répertoire courant
block_cache_size 512 MiB Cache de blocs RocksDB
query_timeout_ms 30000 Délai maximal d’une requête

Seulement les clés les plus utilisées. Pour toutes les options, voyez la référence de configuration et la référence de l’API.

L’API par tâche

Bases

TâcheAppelRenvoie
Créer, ouvrir barrel_docdb:create_db/1,2, open_db/1 {ok, Pid}
Fermer, supprimer barrel_docdb:close_db/1, delete_db/1,2 ok
Décrire, lister barrel_docdb:db_info/1, list_dbs/0 table d’infos, noms

Documents

TâcheAppelRenvoie
Écrire barrel_docdb:put_doc/2,3, put_docs/2,3 {ok, #{id, rev, ok}} ; {error, conflict} sans le _rev courant
Lire barrel_docdb:get_doc/2,3, get_docs/2,3 {ok, Doc} ou {error, not_found}
Supprimer barrel_docdb:delete_doc/2,3 {ok, _}
Conflits barrel_docdb:get_conflicts/2, resolve_conflict/4 {ok, [Rev]}, {ok, #{conflicts_resolved}}

Requêtes et changements

TâcheAppelRenvoie
Requête structurée barrel_docdb:find/2,3, explain/2 {ok, Rows, Meta}
BQL (documents seuls) barrel_docdb:query/2,3 {ok, Rows, Meta}
Flux de changements barrel_docdb:get_changes/2,3, subscribe_changes/2,3 {ok, Changes, Last}, un pid de flux
Abonnement à un chemin barrel_docdb:subscribe/2,3, unsubscribe/1 des messages {barrel_change, Db, Change}

Fichiers, historique, timeline, synchronisation

TâcheAppelRenvoie
Pièces jointes put_attachment/4,5, get_attachment/3, open_attachment_writer/4,5 {ok, Info}, {ok, Bytes}
Versions get_doc_versions/2, get_version_body/3, fold_history/3,4 {ok, [Version]} avec la provenance
Branche, fusion branch_db/3, merge_branch/2, list_branches/1 {ok, _}, {ok, Report}
Répliquer une fois barrel_rep:replicate/2,3 {ok, Report}
Tâche continue barrel_rep_tasks:start_task/1, get_task/1, stop_task/1 {ok, TaskId}

Écrire, chercher et interroger

D’après une exécution vérifiée sur un répertoire de données vierge.

Shell Erlang
{ok, _} = application:ensure_all_started(barrel_docdb).
{ok, _} = barrel_docdb:create_db(<<"kb">>).
barrel_docdb:put_docs(<<"kb">>, [
  #{<<"id">> => <<"kb:101">>, <<"type">> => <<"article">>,
    <<"title">> => <<"Reset a forgotten password">>,
    <<"views">> => 1200,
    <<"tags">> => [<<"account">>, <<"login">>]},
  #{<<"id">> => <<"kb:102">>, <<"type">> => <<"article">>,
    <<"title">> => <<"Configure SSO with Okta">>,
    <<"views">> => 430,
    <<"tags">> => [<<"sso">>, <<"login">>]},
  #{<<"id">> => <<"kb:201">>, <<"type">> => <<"article">>,
    <<"title">> => <<"Export invoices as CSV">>,
    <<"views">> => 980,
    <<"tags">> => [<<"export">>]}]).
barrel_docdb:find(<<"kb">>, #{id_prefix => <<"kb:1">>,
                              include_docs => false}).
barrel_docdb:query(<<"kb">>,
  <<"SELECT title, views FROM kb WHERE type = 'article' "
    "AND views >= 500 ORDER BY views DESC">>).
Sortie d’une exécution sur barrel_docdb 2.1.0 (abrégée)
[{ok,#{<<"id">> => <<"kb:101">>,<<"ok">> => true,
      <<"rev">> =>
        <<"000001a1b8784bea00000000@waec6d4b23aba0dca">>}},
 ...]

{ok,[#{<<"id">> => <<"kb:101">>},#{<<"id">> => <<"kb:102">>}],
    #{has_more => false, ...}}

{ok,[#{<<"id">> => <<"kb:101">>,
       <<"title">> => <<"Reset a forgotten password">>,
       <<"views">> => 1200},
     #{<<"id">> => <<"kb:201">>,
       <<"title">> => <<"Export invoices as CSV">>,
       <<"views">> => 980}],
    #{count => 2, has_more => false, ...}}

Résoudre un conflit après une réplication dans les deux sens

Deux bases locales ont modifié le même document, puis se sont répliquées dans les deux sens. La résolution nomme les versions qu’elle a observées.

Shell Erlang
barrel_rep:replicate(<<"edge_a">>, <<"edge_b">>),
barrel_rep:replicate(<<"edge_b">>, <<"edge_a">>).
%% both sides edited task:1 while apart
barrel_docdb:get_conflicts(<<"edge_a">>, <<"task:1">>).
{ok, #{<<"_observed">> := Seen}} =
    barrel_docdb:get_doc(<<"edge_a">>, <<"task:1">>,
                         #{conflicts => true}).
barrel_docdb:resolve_conflict(<<"edge_a">>, <<"task:1">>,
    Seen, {merge, Merged}).
%% Merged: the body to keep, here with a "note" field
Sortie de la même exécution
{ok,[<<"000001a1b879d59100000000@w7bcb971434496877">>]}

{ok,#{id => <<"task:1">>,
      rev => <<"000001a1b879d59500000000@w7bcb971434496877">>,
      conflicts_resolved => 1}}

Limites à connaître

  • La lignée est linéaire : une branche d’une branche est refusée, et une branche à un instant antérieur au plancher de l’historique échoue avec pitr_window_exceeded.
  • La réplication ne transporte ni les vecteurs ni la provenance. Les canaux ne suppriment pas des réplicas les documents qui en sont sortis.
  • Les tâches de réplication refusent les identifiants passés en ligne. Les points de reprise des pièces jointes attendent que la cible soit durable, sauf si vous fixez att_durability => best_effort.
  • Les réglages d’exécution (encryption, read_only, channels, conflict_resolver, rétention) doivent être repassés à chaque réouverture.
  • Le data_dir de l’environnement est relatif au répertoire courant. La documentation de create_db/2 indique encore /tmp/barrel_data.
Lacune connue

Dans find/2, order_by sur un chemin est ignoré si ce chemin n’est pas sélectionné ou lié à une variable.

Lacune connue

Une requête BQL découpée en morceaux avec un prédicat d’intervalle a perdu une ligne à la continuation, une fois pendant les tests ; le cas n’est pas encore réduit.

Haut et bas pour se déplacerEntrée pour ouvrir