see on GitHub

    Server: Running an Embedded Instance

    Overview

    RavenDB makes it very easy to be embedded within your application, with PyRavenDB Embedded package you can integrate your RavenDB server with few easy steps. 

    EmbeddedServer().start_server()
with EmbeddedServer().get_document_store("Embedded") as store:
    with store.open_session() as session:
        # Your Code Here
        pass

    Prerequisites

    PyRavenDB Embedded does not include .NET Core runtime required for it to run. By default the ServerOptions.framework_version is set to the .NET Core version that we compiled the server with and ServerOptions.dotnet_path is set to dotnet meaning that it will require to have it declared in PATH. We highly recommend using the .NET Core framework version defined in ServerOptions.framework_version for proper functioning of the Server. If you don't have dotnet installed The .NET Core runtime can be downloaded from here, to use it just add it to the PATH or change ServerOptions.dotnet_path to dotnet.exe path you just downloaded. 

    EmbeddedServer().start_server(ServerOptions(dotnet_path="PATH_TO_DOTNET_EXEC"))

    Getting Started

    Installation

    • Create a new project.
    • Install from PyPi, as pyravendb-embedded.
      pip install pyravendb-embedded
    • Start a new Embedded Server
    • Get the new Embedded Document Store, and start working with the database.

    Starting the Server

    RavenDB Embedded Server is available under EmbeddedServer Instance. In order to start it call start_server method. 

    # Start RavenDB Embedded Server with default options
EmbeddedServer().start_server()

    or more control on how to start the server just pass to start_server method a ServerOptions object and that`s it.

    ServerOptions

    Name Type Description
    framework_version str The .NET Core framework version to run the server with
    data_directory str Indicates where your data should be stored
    server_directory str The path to the server binary files (.dll)
    dotnet_path str The path to exec dotnet (if it is in PATH, leave it)
    accept_eula bool If set to false, will ask to accept our terms & conditions
    server_url str What address we want to start our server (default 127.0.0.1:0)
    max_server_startup_time_duration timedelta The timeout for the server to start
    command_line_args list The command lines arguments to start the server with 

    server_options = ServerOptions(data_directory="C:\\RavenData", server_url="http://127.0.0.1:8080")
EmbeddedServer().start_server(server_options)

    Note

    Without the server_options, RavenDB server will start with a default values on 127.0.0.1:{Random Port}

    Security

    PyRavenDB Embedded support running a secured server. There are two options to make ravendb secured in Pyravendb-Embedded:

    1) secured(certificate_path, certificate_password=None) - For this option you will put a path to a .pfx file for the server and a password to the file if you have one. 

    server_options = ServerOptions()
server_options.secured(certificate_path="PathToServerCertificate.pfx",
                       certificate_password="CertificatePassword")

    2) secured_with_exec(self, cert_exec, cert_exec_args, server_cert_fingerprint, client_cert_path, client_cert_password=None) - For this option you will have to put executable program (ex. powershell, python, etc) and the arguments for him, the fingerprint of the cert file you can use pyravendb Utils for that (see get_cert_file_fingerprint method), the client cert path and the password if you have one. 

    server_options_with_exec = ServerOptions()
server_options_with_exec.secured_with_exec("powershell",
                                           "C:\\secrets\\give_me_cert.ps1",
                                           Utils.get_cert_file_fingerprint("PATH_TO_PEM_CERT_FILE"),
                                           "PATH_TO_PEM_CERT_FILE")
EmbeddedServer.start_server(server_options_with_exec)

    Note

    This option is useful when you want to protect your certificate (private key) with other solutions such as "Azure Key Vault", "HashiCorp Vault" or even Hardware-Based Protection. RavenDB will invoke a process you specify, so you can write your own scripts / mini programs and apply whatever logic you need. It creates a clean separation between RavenDB and the secret store in use. RavenDB expects to get the raw binary representation (byte array) of the .pfx certificate through the standard output. In this options you can control on your client certificate and to use in a different certificate for your client.

    Document Store

    After Starting the server you can get the DocumentStore from the Embedded Server and start working with PyRavenDB. Getting the DocumentStore from The Embedded Server is pretty easy you only need to call get_document_store method with database name or with DatabaseOptions.

    DatabaseOptions

    Name Type Description
    database_name str The name of the database
    skip_creating_database bool If set to True, will skip try creating the database 

    EmbeddedServer().get_document_store("Embedded")
    database_options = DatabaseOptions(database_name="Embedded", skip_creating_database=True)
EmbeddedServer().get_document_store(database_options)

    Remarks

    • You can have only one instance of EmbeddedServer
    • Method EmbeddedServer().open_studio_in_browser() can be used to open an browser instance with Studio

    Home / Docs / Server / Embedded