Pièces jointes
Une pièce jointe est un blob binaire nommé stocké avec un document : un PDF, une image, un journal. Elle appartient à l’id du document, l’accompagne lors de la réplication, et est stockée à part du JSON, dans les fichiers blob de RocksDB par défaut ou dans un bucket S3. Utilisez les pièces jointes quand un enregistrement a besoin de fichiers et que vous les voulez sous le même id, synchronisés par la même réplication.
Écrire et lire
{ok, Info} = barrel:put_attachment(Db, <<"rb:pg">>,
<<"diagram.txt">>, <<"primary -> replica">>),
barrel:get_attachment(Db, <<"rb:pg">>, <<"diagram.txt">>). curl -X PUT localhost:8080/db/demo/doc/a/att/hello.txt \
-H 'content-type: text/plain' \
--data-binary 'hello attachment'
curl localhost:8080/db/demo/doc/a/att/hello.txt {ok,#{name => <<"diagram.txt">>,length => 18,
digest => <<"sha256-1a8b09f8050eb8c57268d69a...">>,
content_type => <<"text/plain">>,chunked => false}}
{ok,<<"primary -> replica">>} HTTP/1.1 201 Created
{"name":"hello.txt","length":16,
"digest":"sha256-7fa36b95d5c98859ed72b4787f3c28b2...",
"content_type":"text/plain","chunked":false}
HTTP/1.1 200 OK
content-type: text/plain
hello attachment Les empreintes sont raccourcies ci-dessus. Écrire une pièce jointe ne
change pas le _rev du document.
Lister, inspecter, supprimer
barrel:list_attachments(Db, <<"rb:pg">>),
barrel:attachment_info(Db, <<"rb:pg">>, <<"diagram.txt">>),
ok = barrel:delete_attachment(Db, <<"rb:pg">>,
<<"diagram.txt">>). curl -X DELETE localhost:8080/db/demo/doc/a/att/hello.txt Diffuser les gros fichiers en flux
Un writer envoie un fichier par morceaux ; rien ne garde le fichier entier en mémoire.
{ok, W0} = barrel:open_attachment_writer(Db, <<"rb:pg">>,
<<"log.txt">>,
<<"text/plain">>),
{ok, W1} = barrel:write_attachment(W0, <<"line 1\n">>),
{ok, W2} = barrel:write_attachment(W1, <<"line 2\n">>),
barrel:finish_attachment(W2).
{ok,#{name => <<"log.txt">>,length => 14,chunk_size => 65536,
digest => <<"sha256-9060554863a62b9db5f72621...">>,
content_type => <<"text/plain">>,chunked => true,
chunk_count => 1}} abort_attachment/1 abandonne un envoi inachevé. Pour lire par
morceaux, utilisez open_attachment_reader/3 et read_attachment/1, et
fermez le reader si vous vous arrêtez avant la fin : il retient cette
version jusque-là. Les lectures par plage d’octets
(open_attachment_stream/4, read_attachment_range/5) n’existent que
dans barrel_docdb.
Un envoi reste invisible tant qu’il n’est pas terminé. Un envoi laissé
inachevé plus longtemps que att_upload_timeout (3600 s par défaut) est
supprimé.
Écrire seulement si
| Option Erlang | En-tête REST | Effet |
|---|---|---|
create_only => true | If-None-Match: * | Échoue si la pièce jointe existe |
expected_etag => Etag | If-Match: Etag | Échoue sauf si c’est toujours cette version |
expected_digest => Digest | Échoue si les octets ne correspondent pas |
Une condition non remplie répond 409. Un backend qui ne sait pas faire
d’écritures conditionnelles répond 501 conditional_writes_unsupported.
Garder les pièces jointes dans S3
Optionnel, demande une configurationbarrel_att_s3 stocke les octets dans un bucket compatible S3. Le
bucket doit exister. Passez le backend à la création de la base :
{ok, _} = barrel_docdb:create_db(<<"s3db">>, #{
att_opts => #{backend => s3,
s3 => #{
bucket => <<"barrel-files">>,
endpoint => <<"http://127.0.0.1:9000">>,
region => <<"us-east-1">>,
access_key_id => <<"...">>,
secret_access_key => <<"...">>}}}).
En REST, PUT /db/:db prend les mêmes options en JSON :
{"att_opts":{"backend":"s3","s3":{...}}}.
Les pièces jointes dans S3 ne sont pas chiffrées, même dans une base chiffrée. Le backend est testé avec RustFS et Garage ; Garage ne peut pas appliquer les écritures conditionnelles.
Pour ne stocker aucune pièce jointe, passez
att_opts => #{backend => none}.
Comment elles se répliquent
Chaque exécution de réplication a une phase pièces jointes après les documents. Elle compare les empreintes, n’envoie que ce qui manque à la cible, et résout les écritures concurrentes par la dernière écriture selon leur horodatage. Il n’y a pas de versions sœurs pour les pièces jointes.
- Un document peut arriver avant sa pièce jointe ; la pièce jointe répond 404 jusqu’à ce que la phase aboutisse.
- Par défaut, une exécution attend que la cible ait rendu durables les
écritures de pièces jointes avant d’avancer son point de reprise. Une
cible qui ne sait pas le faire échoue avec
att_flush_unsupported; passezatt_durability => best_effortpour répliquer vers elle malgré tout. - Une réplication filtrée n’envoie que les pièces jointes des documents qui passent le filtre.
Voir Synchronisation.