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
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