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
{barrel_att_s3, "~> 0.1"} Absent du build par défaut de l’umbrella : utilisez rebar3 as s3 compile.
Configuration
att_opts
| Clé | Défaut | Rô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éfaut | Rô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âche | Appel | Renvoie |
|---|---|---|
| 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>.
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}))]). 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 nouvellesatt_optsne 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.
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.