Barrel
EN GitHub

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">>).
Sortie d’une exécution sur barrel 1.12.0 (Erlang)
{ok,#{name => <<"diagram.txt">>,length => 18,
    digest => <<"sha256-1a8b09f8050eb8c57268d69a...">>,
    content_type => <<"text/plain">>,chunked => false}}
{ok,<<"primary -> replica">>}
Sortie d’une exécution sur barrel_server 1.13.0 (REST)
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">>).

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).
Sortie d’une exécution sur barrel 1.12.0, empreinte raccourcie
{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 ErlangEn-tête RESTEffet
create_only => trueIf-None-Match: *Échoue si la pièce jointe existe
expected_etag => EtagIf-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 configuration

barrel_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":{...}}}.

Limite

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 ; passez att_durability => best_effort pour 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.

Traduit de la page anglaise: /docs/store/attachments/ Modifier cette page Voir en Markdown

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