Skip to main content

Attachments and Other Features

Attachments & Replication​

Replication is triggered by document changes, including when attachments are added or modified.

  • Internal replication occurs automatically between nodes in the database group.
  • External replication is a defined ongoing task between two RavenDB databases (typically across clusters).

Learn more about replication in Replication overview.

For both internal and external replication:

Local attachments:
The document is replicated along with the attachment's binary content, which will be stored on the target node.

Remote attachments:
The document is replicated without the binary content, only the metadata is transferred.
The attachment's content resides in shared remote storage (e.g., S3, Azure Blob) and does not need to be copied between nodes.

  • Target server compatibility:
    If the target node is running a RavenDB server version earlier than 7.2, which does not support remote attachments,
    replicating a document that references a remote attachment will throw a LegacyReplicationViolationException.

  • Remote destination configuration for external replication:
    When using external replication, the remote storage destinations must also be configured on the target database.
    This is your responsibility, RavenDB does not automatically replicate the remote attachment configurations.
    If the destination is not defined on the target, the remote attachment will be inaccessible after replication.

Attachments & RavenDB ETL​

A RavenDB ETL task sends documents to another RavenDB database and allows you to transform documents using a script. The ETL task is triggered by document changes in the source database, including when attachments are added or modified.

Local attachments:
The document is sent to the target database along with the binary attachment stream.

Remote attachments:
The document is sent without the binary stream, only the metadata is transferred, since the attachment content resides in remote storage.

  • Remote destination configuration:
    When documents that reference remote attachments are sent via RavenDB ETL, you must ensure that the same remote attachment configuration is defined on the target database. This is your responsibility, as the ETL process does not automatically configure remote destinations on the target side.

  • Target server compatibility:
    If the target node is running a RavenDB server version earlier than 7.2, which does not support remote attachments, attempting to send a document that references a remote attachment will result in an excetion.

Attachments & Export/import/backup/restore​

The following behavior applies to Export, Import, Backup, and Restore from backup operations.

Local attachments:
The attachment metadata and the binary content are included in the operation:

  • During export/backup, the binary stream is written to the dump file.
  • During import/restore, the binary stream is loaded from the dump into the database.

Remote attachments:

  • Attachments metadata:

    • During export/backup:
      only the metadata is written to the dump,
      the binary content remains in remote storage.
    • During import/restore:
      the metadata is loaded from the dump into the database,
      the content is expected to remain accessible in its original remote location.

  • Remote attachments configuration:
    By default, RavenDB includes the remote attachments configuration, including the list of defined remote destinations, in both export/backup and import/restore operations.

    However, during import or restore, RavenDB does not verify the actual remote storage itself.
    You must ensure that:

    • The destination identifiers still point to valid and accessible remote storage.
    • The external storage contains all the remote attachment files referenced in the imported documents.
      If the files are missing, the attachments will not be accessible.

Attachments & Revisions​

Revisions are immutable snapshots of a document's state at a given point in time. If Document revisions are enabled, any addition or removal of attachments will create a new revision of the document.

When a revision is created, it records the attachment's state exactly as it was at that moment.
The storage location of the attachment is bound to the revision’s creation context, not to the current state of the document:

  • If the attachment was local, the revision stores it as local.
  • If the attachment was remote, the revision stores only the remote parameters (e.g., destination identifier, upload time).

The background process that uploads attachments to remote storage only processes current documents.
It does not process or modify revisions.

  • Revisions that reference an attachment as local will remain local forever, even if the attachment in the current (parent) document is scheduled for remote uploading and later uploaded to remote storage.
  • The binary content will be retained on disk until all references to the attachments are removed -
    both from the parent document and from any revision that still reference it.

Restoring from a Revision:
Reverting a document to a previous revision also restores the attachment state stored in that revision:

  • Reverting to a revision that references a local attachmet restores the attachment as local.
  • Reverting to a revision that references a remote attachment results in a document with a remote attachment.