RavenDB 3.4, installation, architecture et prise en main

Introduction

RavenDB est la meilleure base de données orientée Documents pour les développeurs .NET. Parmi les avantages de RavenDB :

Le moteur n’est pas limitée à requêter par clé/valeur.
Support des mises à jour partielles (partial update).
Support de LINQ.
Facilite les verrous granulaires.

Une installation est réalisée ici pour une prise en main et une découverte de l’architecture RavenDB.

Les aspects développement des indexes, cluster, réplication, intégration avec Visual Studio… ne sont pas abordés ici. Il s’agit d’une première prise en main.

Le support de la sécurité d’accès nécessite une licence. Dans l’édition Developer, aucun contrôle de l’authentification n’est possible.

Pré-requis

La configuration recommandée pour un serveur RavenDB est assez minimale :

4 GB de RAM
2 GHz Quad core
50 GB de disque
OS Windows 64 Bits
.NET 4.5 ou versions supérieures

Une instance RavenDB peut supporter plusieurs bases de données, toutefois il n’est pas recommandé d’avoir trop de bases de données, les performances peuvent être dégradées.

Plusieurs instances RavenDB sont également possibles sur une même machine, mais même recommandation, éviter si possible le multi instance.

Architecture d’une instance RavenDB

Une instance RavenDB contient obligatoirement une base de données System, elle contient le catalogue de l’instance.

Après l’initialisation d’une instance RavenDB, une ou plusieurs bases de données peuvent être créées ainsi que un ou plusieurs FileSystems.

2 moteurs de stockage sont possibles pour les bases de données et les filesystems

Esent (moteur de stockage par défaut) : Extensible storage engine. Moteur de stockage ISAM (indexed sequential access method) de Microsoft.
Voron : moteur de stockage créé par Hibernating Rhinos mais il semble présenter des limitations. Les transactions distribuées DTC ne sont pas supportées, la configuration des disques doit savoir gérer les paramètres UNBUFFERED_ID/WRITE_THROUGH…

Le moteur Esent semble le plus indiqué en fiabilité, il est notamment le moteur de stockage des serveurs Exchange.

Installation des binaires

Installation de cURL

Avant d’installer RavenDB, de nombreuses commandes d’administration de RavenDB (création de bases de données, sauvegardes…) utilisent cURL, télécharger cURL également : Téléchargements cURL pour Windows 64 bits. Le package 7.55.1 (SSL/SSH) de Viktor Szakáts est parfait (curl-7.55.1-win64-mingw.7z).

cURL, téléchargé précédemment, est déployé dans le répertoire D:\Software\tools\curl

D:\software\tools\7zip\7z.exe x curl-7.55.1-win64-mingw.7z -oD:\software\tools

rename D:\software\tools\curl-7.55.1-win64-mingw curl

Pour simplier les appels au binaire cURL, ajouter le répertoire <curl_install_dir>\bin dans la variable système %PATH%

set PATH=D:\software\tools\curl\bin;%PATH%

Installation de la suite logicielle RavenDB

À l’heure de l’écriture de cet article, la version 4.0 est disponible mais elle est encore en version Release Candidate. C’est pourquoi c’est la version 3.5.4 (stable) qui est téléchargée.

Télécharger le package zip de RavenDB (RavenDB-3.5.4.zip) et les outils (RavenDB-3.5.4.Tools.zip) depuis la page de téléchargement de RavenDB : RavenDB - Downloads

RavenDB (binaires client et serveur) est installé dans le répertoire D:\software\ravendb. Le numéro de version est éliminé pour les futures campagnes de patchs et de migrations.

unzip RavenDB-3.5.4.zip -d D:\software\ravendb

Les outils sont installés dans le répertoire D:\software\ravendbtools. Le numéro de version est également éliminé.

unzip RavenDB-3.5.4.Tools.zip -d D:\software\ravendbtools

Les variables systèmes %RAVENDB% et %RAVENDB_TOOLS% sont créées pour simplifier la navigation.

set RAVENDB=D:\software\ravendb
set RAVENDB_TOOLS=D:\software\ravendbtools

Création d’une instance RavenDB

Configuration de l’instance

Pour préparer une nouvelle instance RavenDB, dans le répertoire %RAVENDB%/Server, faire au préalable une sauvegarde du fichier de configuration Raven.Sever.exe.config (Raven.Sever.exe.config.orig)

Par défaut les bases de données et filesystems de RavenDB sont créés dans le répertoire %RAVENDB%/Server et le port est 8080.

L’installation (port, répertoires, mémoire…) est personnalisée dans le fichier de configuration Raven.Sever.exe.config, cette étape est plutôt importante si on souhaite délocaliser les bases de données, filesystems, etc. du répertoire des binaires, répertoire qui sera forcément manipulé un jour ou l’autre lors de l’application de patchs ou de migrations.

Dans la configuration ci-dessous, le port est fixé à 35000 (Raven/Port) et tous les composants de l’instance sont délocalisés dans le répertoire D:\ravendb avec le paramètre Raven/WorkingDir. Ce dernier paramètre garantit qu’aucun élément de l’instance ne sera créé dans le répertoire des binaires %RAVENDB%\Server

Raven.Sever.exe.config

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
    <appSettings>
        <add key="Raven/Port" value="35000"/>
        <add key="Raven/DataDir/Legacy" value="~\Database\System"/>
        <add key="Raven/WorkingDir" value="D:\ravendb"/>
        <add key="Raven/AnonymousAccess" value="Admin"/>
        <add key="Raven/Licensing/AllowAdminAnonymousAccessForCommercialUse" value="false" />
        <add key="Raven/AccessControlAllowOrigin" value="*" />
    </appSettings>
    <runtime>
        <loadFromRemoteSources enabled="true"/>
        <gcServer enabled="true"/>
        <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
            <probing privatePath="Analyzers;Plugins"/>
        </assemblyBinding>
    </runtime>
</configuration>

L’arborescence d’une instance est alors la suivante :

WorkingDir
   |________ Assemblies
   |________ CompiledIndexCache
   |________ Databases
   |________ FileSystems
   |________ Plugins

Bien entendu d’autres paramètres permettent de contrôler encore plus finement la localisation des composants de l’instance, notamment si on dispose d’une architecture ou des disques sont plus rapides que d’autres, parmi ces paramètres :

`Raven/DataDir`	Répertoire des bases de données
`Raven/FileSystem/DataDir`	Répertoire des Filesystems
`Raven/CompiledIndexCacheDirectory`	Répertoire utilisé par le compilateur des indexes
`Raven/TransactionJournalsPath`	Répertoire des journaux de transactions des moteurs de stockage Esent ou Voron. Pour les performances, si ils sont localisés sur un autre disque, c’est encore mieux.
`Raven/IndexStoragePath`	Répertoire des indexes.
`Raven/FileSystem/IndexStoragePath`	Répertoire des indexes des filesystems.
`Raven/AssembliesDirectory`	Répertoire des assemblages

Les options de configuration sont très nombreuses, la documentation est bien conçue à ce sujet : RavenDB, Configuration - Options.

La première exécution de Raven.Server.exe initialise l’environnement (création des répertoires, de la base de données System…)

La base de données System est créée dans le répertoire D:\ravendb\Databases\System.

Raven.Server.exe

Console RavenDB Studio

La console graphique RavenDB Studio est prête à l’emploi dès le démarrage du serveur : http://hostname:35000

Création du service Windows

Pour arrêter le serveur démarré précédemment à l’initialisation, taper q dans la console.

Pour créér un service Windows RavenDB : en tant qu’administrateur, exécuter Raven.Server.exe avec l’option --install

Raven.Server.exe --install

Un nom de service personnalisé peut être donné avec l’option --service-name

Raven.Server.exe --service-name="RavenDB (Test)" --install

Fichiers de logs

Rien de bien compliqué pour activer et délocaliser les fichiers de logs d’une instance RavenDB. Par défaut les fichiers de log ne sont pas activés. Un modèle est proposé avec le fichier NLog.ignored.config dans le répertoire %RAVENDB%/Server. Renommer le fichier NLog.ignored.config en NLog.config en personnalisant ce dernier si besoin (localisation, verbosité…) et redémarrer le serveur.

Cas du multi instance

Le multi instances est possible en donnant le fichier de configuration de l’instance à l’exécutable Raven.Server.exe, mais malheureusement il n’est pas possible de définir un service Windows en donnant l’option --config à l’exécutable Raven.Server.exe. Les serveurs ne peuvent être démarrés qu’en mode lignes de commandes.

Raven.Server.exe --config=D:\dba\ravendb\cfg\RavenDBInst1.config

Raven.Server.exe --config=D:\dba\ravendb\cfg\RavenDBInst2.config

La solution la plus élégante consiste alors à créér une distribution RavenDB pour chaque instance, ainsi d’ailleurs chaque instance pourra avoir sa propre version.

Instance 1
`%RAVENDB_HOME1%` : `D:\Software\ravendb\Instance1` Config : `%RAVENDB_HOME1%\Server\Raven.Server.exe.config` Création du service RavenDB (Instance 1) : `cd %RAVENDB_HOME1%\Server Raven.Server.exe --service-name="RavenDB (Instance 1)" --install`

Instance 2
`%RAVENDB_HOME2%` : `D:\Software\ravendb\Instance2` Config : `%RAVENDB_HOME2%\Server\Raven.Server.exe.config` Création du service RavenDB (Instance 2) : `cd %RAVENDB_HOME2%\Server Raven.Server.exe --service-name="RavenDB (Instance 2)" --install`

Manipuler des bases de données (création, suppression…)

En mode graphique avec RavenDB Studio, la création d’une base de données est très simple. Le moteur de stockage Esent est le moteur de stockage par défaut.

Avec la clé Raven/WorkingDir (ou éventuellement Raven/DataDir) définie dans le fichier de configuration du serveur, la base de données est créée par défaut dans le répertoire D:\ravendb\Databases\<dbname>

En ligne de commandes avec cURL, la syntaxe de création d’une base de données (myDB2 ici) est un peu plus ardue :

curl "http://<ServerName>:35000/admin/databases/myDB2" -X PUT ^
-d "{\"SecuredSettings\":{},\"Settings\":{\"Raven/ActiveBundles\":\"PeriodicExport\",\"Raven/DataDir\":\"~/myDB2\"},\"Disabled\":false,\"Id\":\"myDB2\"}"

Tout ce qui est réalisé graphiquement avec RavenDB Studio peut être réalisé en ligne de commandes mais via cURL, voici quelques exemples

Supprimer une base de données, y compris les données et indexes

curl "http://<ServerName>:35000/admin/databases/myDB2?hard-delete=true" -X DELETE

Lister les bases de données :

curl -X GET "http://<ServerName>:35000/databases?pageSize=8&start=0"

Et encore bien d’autres opérations : sauvegardes, restaurations, indexations, compactages…

Création d’un filesystem

En mode graphique avec RavenDB Studio, la création d’un filesystem est tout aussi simple.

Comme pour les bases de données, le moteur de stockage peut être Esent (par défaut) ou Voron.

Avec la clé Raven/WorkingDir (ou Raven/FileSystem/DataDir) définie dans le fichier de configuration du serveur, le filesystem est créé par défaut dans le répertoire D:\ravendb\FileSystems\<filesystemname>

Insérer les données de démo

Afin de découvrir le produit RavenDB, des données de démo sont disponibles avec RavenDB. Sélectionner dans RavenDB Studio la base de données dans laquelle vous souhaitez insérer les données de démo : ici myDB1

Puis cliquer sur TasksCreate Sample Data

Joyeuse navigation, il y a beaucoup à découvrir et cette note technique sur la prise en main s’arrête ici.