Barrel
EN GitHub

barrel_att_s3

Un backend de pièces jointes pour barrel_docdb qui garde les octets des fichiers dans un bucket compatible S3 au lieu du stockage de blobs RocksDB local.

Ce qu’elle résout

Les gros fichiers remplissent les disques locaux et se partagent mal entre nœuds. Avec barrel_att_s3, le document reste dans barrel_docdb tandis que ses pièces jointes vont dans un stockage objet, avec le flux des pièces jointes, la réplication, les branches (copie côté serveur), les envois multipart et le nettoyage des envois abandonnés.

Quand l’utiliser

  • Les pièces jointes sont grosses ou nombreuses, et le disque local est la limite.
  • Vous exploitez déjà un stockage compatible S3 (RustFS et Garage sont testés en CI).

Quand ne pas l’utiliser

  • La base est chiffrée et les fichiers doivent l’être aussi : les pièces jointes S3 sont stockées en clair.
  • Vous avez besoin d’écritures conditionnelles sur Garage : il ne peut pas les garantir.

Sa place dans Barrel

Repose sur
barrel_docdb
Utilisée par
Aucune autre bibliothèque Barrel n’en dépend
Optionnelle dans
barrel_docdb
Autres dépendances
livery_s3, livery, rocksdb, hlc, mimerl
Seule
Non. C’est un backend que barrel_docdb charge via att_opts.

Installation

dépendances rebar.config
{barrel_att_s3, "~> 0.1"}

Absent du build par défaut de l’umbrella : utilisez rebar3 as s3 compile.

Configuration

att_opts

CléDéfautRôle
backend blob Mettre s3
s3.bucket obligatoire Doit exister ; absent, il donne {att_store_open_failed, missing_bucket}
s3.endpoint, s3.region aucun Où se trouve le stockage
s3.access_key_id, s3.secret_access_key aucun Identifiants
s3.part_size 8 MiB Taille des parties en multipart

Environnement de l’application (barrel_att_s3)

CléDéfautRôle
multipart_gc_interval 1 h Nettoyage des envois abandonnés ; 0 désactive
multipart_gc_max_age 24 h Âge au-delà duquel un envoi est considéré abandonné

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

L’API par tâche

Via barrel_docdb

TâcheAppelRenvoie
Utiliser S3 pour une base barrel_docdb:create_db/2 with att_opts {ok, Pid}
Stocker, lire, supprimer put_attachment/4,5, get_attachment/3, delete_attachment/3 {ok, Info}, {ok, Bytes}, ok
Écrire seulement si absent put_attachment/5 with create_only => true {error, {conflict, Info}} s’il existe
Écrire si inchangé put_attachment/5 with expected_etag {error, conditional_writes_unsupported} sur Garage
En flux open_attachment_writer/4,5, open_attachment_stream/3,4 descripteurs d’écriture et de lecture

Des pièces jointes dans un bucket RustFS local

D’après une exécution vérifiée contre RustFS 1.0.0 dans un conteneur. Les objets ont pour clé <db>/<hex doc id>/<name>.

Erlang
S3 = #{bucket => <<"barrel-matrix">>,
       endpoint => <<"http://127.0.0.1:29000">>,
       region => <<"us-east-1">>,
       access_key_id => <<"s3testadmin">>,
       secret_access_key => <<"s3testsecret">>},
{ok, _} = application:ensure_all_started(barrel_att_s3),
{ok, _} = barrel_docdb:create_db(<<"s3db">>,
    #{data_dir => Dir,
      att_opts => #{backend => s3, s3 => S3}}),
{ok, _} = barrel_docdb:put_doc(<<"s3db">>,
                               #{<<"id">> => <<"doc1">>}),
{ok, Info} = barrel_docdb:put_attachment(<<"s3db">>,
    <<"doc1">>, <<"greeting.txt">>, <<"Hello, World!">>),
io:format("put: ~p~n", [Info]),
io:format("get: ~p~n", [barrel_docdb:get_attachment(
    <<"s3db">>, <<"doc1">>, <<"greeting.txt">>)]),
io:format("create_only again: ~p~n",
    [element(1, barrel_docdb:put_attachment(<<"s3db">>,
        <<"doc1">>, <<"greeting.txt">>, <<"second">>,
        #{create_only => true}))]).
Sortie d’une exécution sur barrel_att_s3 0.1.4 (empreinte abrégée)
put: #{name => <<"greeting.txt">>,length => 13,
       digest => <<"sha256-dffd6021...a362182986f">>,
       content_type => <<"text/plain">>,chunked => false}
get: {ok,<<"Hello, World!">>}
create_only again: error

Limites à connaître

  • Une branche copie chaque pièce jointe en arrière-plan ; tant que ce n’est pas fini, les lectures répondent {error, {att_sync_pending, _}}.
  • Supprimer une base fermée demande à nouveau att_opts. Recréer une base ouverte avec de nouvelles att_opts ne fait rien, sans le signaler.
  • MinIO et AWS S3 sont documentés comme pris en charge mais ne sont pas testés en CI.
  • Les métadonnées du flux restent en local dans <db>/attachments/feed.db.
Lacune connue

Les pièces jointes ne sont pas couvertes par le chiffrement de la base : avec encryption => default, l’objet dans le bucket contenait le texte en clair.

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