Installer un cluster

Avant que votre application puisse lire ou écrire quoi que ce soit, il lui faut un cluster à qui parler. Deux cas de figure :

• Vous avez déjà un cluster (un collègue en a installé un, ou il tourne dans votre infrastructure) : voir Se connecter à un cluster existant.
• Vous n'avez encore rien : voir Lancer un cluster local avec Docker.

Les deux chemins mènent à Prise en main. Pour un cluster existant, trouvez sa version (fdbcli --version), faites-la correspondre au package FoundationDB.Client.Native et au niveau d'API, puis pointez votre application vers son fichier fdb.cluster. Si vous n'avez encore rien, lancez FoundationDB 7.4 en local dans Docker. Les deux voies sont couvertes ci-dessous.

Se connecter à un cluster existant

1. Trouver la version du cluster

Le client natif que vous livrez doit correspondre au cluster (voir Fonctionnement), commencez donc par trouver la version :

fdbcli --version

Vous devriez voir quelque chose comme :

FoundationDB CLI 7.3 (v7.3.76)
source version ...
protocol fdb00b073000000

C'est le 7.3 (ou 7.4) qui compte. Si fdbcli n'est pas installé, demandez à la personne qui gère le cluster, ou lisez la version dans sa sortie status.

2. Choisir les packages correspondants

Gardez FoundationDB.Client (le package managé) à la dernière version dans les deux cas. Seul le package natif suit la version du cluster.

Vous prévoyez de passer à 7.4 bientôt ? Ciblez le niveau d'API 730 aujourd'hui sur votre cluster 7.3, puis basculez le package natif vers 7.4.x et montez le niveau d'API à 740 une fois le cluster mis à jour. Le package managé et votre code ne changent pas.

3. Y pointer votre application

Votre application a besoin des coordinateurs du cluster, fournis soit sous forme de fichier cluster (fdb.cluster, le même que celui qu'utilise fdbcli), soit sous forme de connection string avec le même contenu. Les deux tiennent sur une ligne, description:id@host:port (avec plus d'hôtes pour les clusters multi-coordinateurs) :

mycluster:abcdef1234567890@10.0.0.10:4500

Vous l'utiliserez dans Prise en main. Préférez le package natif NuGet à une installation du client à l'échelle de la machine, ainsi chaque projet épingle sa propre version (voir pourquoi).

Lancer un cluster local avec Docker

Pas de cluster ? Lancez un FoundationDB 7.4 jetable, à un seul nœud, dans Docker. Cela fonctionne pareil sur Windows, Linux et macOS : fdbserver est un programme Linux, donc même sur Windows et macOS il tourne à l'intérieur du conteneur Linux, et votre application .NET lui parle par le réseau.

Côté application, prenez FoundationDB.Client.Native 7.4.x et le niveau d'API 740 (ou 730).

1. Démarrer le conteneur

docker run --detach --name fdb \
  --publish 127.0.0.1:4500:4500 \
  --env FDB_NETWORKING_MODE=host \
  --env FDB_PORT=4500 \
  --env FDB_COORDINATOR_PORT=4500 \
  foundationdb/foundationdb:7.4.7

FDB_NETWORKING_MODE=host fait annoncer 127.0.0.1 par le serveur pour que votre application sur l'hôte puisse l'atteindre, et le --publish 127.0.0.1:4500:4500 assorti garde le port identique à l'intérieur et à l'extérieur du conteneur. Les deux comptent : sans eux, le client se connecte une fois, reçoit une adresse qu'il ne peut pas atteindre, et chaque transaction tombe en timeout.

• Cannot connect to the Docker daemon : Docker n'est pas lancé (voir Prérequis).
• The container name "/fdb" is already in use : vous en avez déjà un. Réutilisez-le avec docker start fdb, ou supprimez-le avec docker rm -f fdb et relancez.
• Depuis la 7.4.6, l'image 7.4 amont est publiée pour amd64 et arm64, donc Docker sur un Mac Apple Silicon l'exécute nativement. Les branches non-AVX plus anciennes (7.3, 7.2, 7.1) ne fournissent que des images amd64 et peuvent tourner en émulation ; ajoutez --platform linux/amd64 si l'une refuse de démarrer.

2. Initialiser la base de données (une fois)

Un cluster tout neuf n'a pas encore de base de données. Créez-en une :

docker exec fdb fdbcli --exec "configure new single ssd"

Vous devriez voir :

Database created

single signifie une seule copie des données (parfait pour du dev local) ; ssd est le moteur de stockage.

3. Vérifier qu'il tourne

docker exec fdb fdbcli --exec "status minimal"

Vous devriez voir :

The database is available.

Juste après configure, status minimal peut brièvement signaler "The database is available, but has issues" pendant que le cluster termine son recrutement ; attendez quelques secondes et il se stabilise sur "The database is available". Si vous voyez "The database is unavailable" ou "Unable to locate a usable set of coordination servers", attendez quelques secondes et réessayez.

4. Se connecter depuis votre application

Utilisez cette connection string ; elle correspond au coordinateur du conteneur :

docker:docker@127.0.0.1:4500

C'est ce que vous passerez dans Prise en main.

Nettoyer

docker rm -f fdb

Supprime le conteneur. La commande ci-dessus ne monte aucun volume, donc cela jette aussi les données, ce qui est bien ce que vous voulez pour un cluster jetable.

Ou laissez Aspire s'en charger

Pour du vrai développement, .NET Aspire peut démarrer ce cluster pour vous et injecter la connexion dans votre application automatiquement, sans docker run manuel. C'est la configuration recommandée une fois passé le « hello world » : voir Aspire.

La suite

• Prise en main : votre première connexion, lecture et écriture.