see on GitHub

How to migrate data from 3.x server to 4.0?

Backward compatibility

RavenDB 4.0 is a major version upgrade from 3.x. As such, applications using 3.x client DLLs will not be able to work against 4.0 server and require migrating to the latest 4.0 client release prior the server upgrade. Please refer to our client migration guide if you haven't migrated your application yet.

There are a few options to migrate 3.x data to RavenDB 4.0:

  • create database from 3.x data
  • live import data from a running instance
  • restore 3.x backup


How to create database from 3.x database or file system data?

The process of upgrading to RavenDB 4.0 server is as follows:

  • Ensure backups of 3.x databases have been made
  • Stop existing 3.x server
  • Start new RavenDB 4.0 server (4.0 binaries must not be extracted the same directory as 3.x ones)
  • Create new database using New database from v3.x (legacy) data files:
Figure 1. Create new database from 3.x data

You will see the following dialog:

Figure 2. Create new database from 3.x data - dialog

Next, you need to provide the migration configuration:

  • Resource type - whether you are going to import a database of a file system
  • Data directory - the absolute path to 3.x data directory
  • Data exporter - the absolute path to Raven.StorageExporter.exe - RavenDB 3.5 tool that can be found on ravendb.net as a part of Tools package. Please make sure to use the latest version (patch or stable).

The Advanced options section allows to:

  • specify custom path to journals / logs (use if the migrated resource has Raven/TransactionJournalsPath or Raven/Esent/LogsPath setting defined),
  • indicate that the source data had the compression bundle enabled
  • provide encryption key if the source data are encrypted (if you need the new database to be encrypted, please configure it in Encryption section)

Files and legacy attachments

RavenDB 4.0 introduces the notion of attachments that can be bound to documents. The files migrated from RavenFS and legacy database attachments will be saved as documents in @files collection. Each document will have a single attachment. The name of the document will be files/{attachment-name}, the name of an attachment will remain unchanged.

How to live import data from a running instance?

Another option of moving data to RavenDB 4.0 is to import database from running RavenDB 3.x instance. To import data of running database please create a new empty database on 4.0 server and go to Setting -> Import Data -> From another RavenDB Server

Figure 2. Migrate data from another, running RavenDB

How to restore an existing 3.x backup?

If you want to restore a database from 3.x backup to 4.0 server, first you need to restore it manually to running 3.x instance (by command line or RavenDB Studio). Next, use New database from v3.x (legacy) data files option, described above, and point the just restored data.