Import Data from a Live RavenDB Server

1st Step: Prepare Servers for the Import Process

  • Before migrating data from a secure source server, the destination server must also be secure.
    You must pass the certificate from the destination to the source server. The following steps explain how.

  • Perform this step only if your source RavenDB server is a secure verion 4.x (or newer) server that is running on HTTPS. For other servers, skip this step and continue to Step 2.

  • To import, the destination server needs to access the existing source database and fetch data from it.
    To grant such access, you must first register the destination server certificate as a client certificate on your source server.

  • To accomplish this, follow these steps:

Manage Server-Certificates View

Studio Manage Server-Certificates View

  1. Manage Server
    Click the Manage Server tab.

  2. Certificates.
    Select Certificates. (See Certificates Management) for more information on this Studio view.

  3. Server certificates
    Export the destination RavenDB certificate from the DESTINATION RavenDB server.
    Export server certificate

    • Choose Export Server Certificates option from the Server Certificates dropdown.
  4. Client certificate
    Register this certificate on the SOURCE RavenDB server
    Register exported certificate as client certificate

    • Choose Upload client certificate to upload the exported certificate as the client certificate.
  5. Upload client certificate
    Set the certificate details.
    Import certificate details

    1. Name
      Enter a name for this certificate. For future clarity, consider naming each certificate after the role that it will enable in your system (Full Stack Development, HR, Customer, Unregistered Guest, etc...)
    2. Security Clearance
      Set authorization level for this certificate. Read about Security Clearance to choose appropriate level.
    3. Certificate file
      Upload the .pfx certificate file from the destination server installation folder.
    4. Certificate Passphrase
      (Optional) Set a password for this certificate.
    5. Database permissions
      Select databases and permission levels for this certificate.
      If you choose User security clearance, you can give access to specific databases on the server and configure User authorization levels for this certificate.

    Click Upload to complete the process.
    The uploaded certificate will be added to the list of registered client certificates on this server.

2nd Step: Access the Import View

Databases List

Databases List View

On the destination RavenDB server, select a database into which the data will be imported.

  1. Verify that this database is empty as the import will overwrite any existing content.

Import Data

Go to Import Data View

  1. Click Tasks tab.
  2. Select Import Data.
  3. Select From RavenDB.

3rd Step: Set the Source Server URL and database

  • Specify the source server URL and select the database to import the data from.
Import configuration

Import Configuration

  1. Server URL
    Paste URL of the server you want to import from.
  2. Server Version
    The version of the server that you want to import from will show here once you enter the URL.
  3. Database Name
    Enter the name of the database that you want to migrate your data from.

4th Step: Set Import Options

  • Filter the data you want to import.
  • Customize advanced configuration and apply a transform script under the Advanced Import Options.
Import Options

Import Options

Toggling Import Options determines whether the following items will be imported:

  1. Documents
  2. Indexes
  3. Other

Importing an item that doesn't exist

If any of the options is set but the source database doesn't contain any items of that type, the type will be skipped.

5th Step: Advanced Import Options

Click the Advanced button at the bottom of the options view for the following import features.

Transform Script

In the Studio, select database > click Task tab > select Import > select From RavenDB > click the Advanced button at the bottom > toggle Use Transform script.

Advanced Import Options - Transform Script

Advanced Import Options - Transform Script

  • Use Transform Script:
    When enabled, the supplied javascript will be executed on each document before importing the document.

Sample transform javascripts:

// Example 1
delete this['@metadata']['@change-vector']
// The script above will delete the existing change-vector from imported documents,
// New change vectors will be generated during the import.
// This is very helpful if the data is imported from a different database-group
// and you want to avoid adding old change-vector entries to a new environment.

// Example 2
this.collection = this['@metadata']['@collection'];
// This script will create a new 'collection' property in each imported document.

Customize Configuration and Ongoing Tasks

In the Studio, select database > click Task tab > select Import > select From RavenDB > click the Advanced button at the bottom > toggle Customize Configuration and Ongoing Tasks.

Advanced Import Options - Customize Configuration and Ongoing Tasks

Advanced Import Options - Customize Configuration and Ongoing Tasks

  1. Ongoing tasks:

  2. Other:

  3. Connection Strings:

    • Connection Strings used by ETL tasks to authenticate and connect to external databases will be imported.