Émuler Spanner en local

La gcloud CLI fournit un émulateur local en mémoire, que vous pouvez utiliser pour développer et tester vos applications gratuitement, sans créer de projet Google Cloud ni compte de facturation Google Cloud. Étant donné que l'émulateur stocke les données uniquement en mémoire, tous les états, y compris les données, le schéma et les configurations, sont perdus au redémarrage. L'émulateur propose les mêmes API que le service de production Spanner. Il est destiné au développement et aux tests locaux, et non aux déploiements en production.

L'émulateur est compatible avec les API GoogleSQL et PostgreSQL dialectes. Il est compatible avec toutes les langues bibliothèques clientes. Vous pouvez également utiliser l'émulateur avec la CLI Google Cloud et les API REST.

L'émulateur est également disponible en tant que projet Open Source dans GitHub.

Limites et différences

L'émulateur n'est pas compatible avec les éléments suivants :

L'émulateur diffère également du service de production Spanner des manières suivantes :

  • Il est possible que les messages d'erreur ne soient pas cohérents entre l'émulateur et le service de production.
  • Les performances et l'évolutivité de l'émulateur ne sont pas comparables au service de production.
  • Les transactions en lecture/écriture et les modifications de schéma bloquent l'intégralité de la base de données pour y accéder de manière exclusive jusqu'à ce qu'elles soient terminées.
  • Le LMD partitionné et l'interrogation de partition sont compatibles, mais l'émulateur ne vérifie pas que les instructions sont partitionnables. Cela signifie qu'une instruction de LMD partitionné ou d'interrogation de partition peut s'exécuter dans l'émulateur, mais peut échouer dans le service de production avec une erreur d'instruction non partitionnable.

Pour obtenir la liste complète des API et des fonctionnalités compatibles, non compatibles et partiellement compatibles, consultez le fichier README dans GitHub.

Installer et exécuter l'émulateur

Les deux méthodes les plus courantes pour exécuter l'émulateur sont l'utilisation de la CLI gcloud et de Docker. Vous pouvez choisir la méthode la plus adaptée au workflow de développement et de test de votre application.

CLI gcloud

  1. Installez la CLI gcloud.

  2. Pour les utilisateurs de Windows et MacOS, l'émulateur nécessite que Docker soit installé sur votre système et disponible sur le chemin d'accès du système.

  3. Mettez à jour gcloud pour obtenir la dernière version :

    gcloud components update

  4. Démarrez l'émulateur :

    gcloud emulators spanner start

    Si l'émulateur n'est pas déjà installé, vous serez invité à télécharger et installer le fichier binaire de l'émulateur.

    Par défaut, l'émulateur héberge deux points de terminaison locaux : localhost:9010 pour les requêtes gRPC et localhost:9020 pour les requêtes REST.

    Pour en savoir plus sur cette commande, consultez la page gcloud emulators spanner.

Docker

  1. Assurez-vous que Docker est installé sur votre système et disponible sur le chemin d'accès au système.

  2. Obtenez la dernière image de l'émulateur :

    docker pull gcr.io/cloud-spanner-emulator/emulator

  3. Démarrez l'émulateur :

    docker run -p 9010:9010 -p 9020:9020 gcr.io/cloud-spanner-emulator/emulator

    Cette commande exécute l'émulateur et mappe les ports du conteneur aux mêmes ports sur l'hôte local. Vous disposerez de deux points de terminaison locaux : localhost:9010 pour les requêtes gRPC et localhost:9020 pour les requêtes REST.

Utiliser la gcloud CLI avec l'émulateur

Pour utiliser l'émulateur avec gcloud, vous devez désactiver l'authentification et remplacer le point de terminaison.

Nous vous recommandons de créer une configuration gcloud distincte afin de pouvoir basculer rapidement entre l'émulateur et le service de production. Pour créer et activer une configuration d'émulateur, exécutez les commandes suivantes :

gcloud config configurations create emulator
  gcloud config set auth/disable_credentials true
  gcloud config set project your-project-id
  gcloud config set api_endpoint_overrides/spanner http://localhost:9020/

Une fois cette configuration réalisée, les commandes gcloud sont envoyées à l'émulateur au lieu du service de production. Vous pouvez vérifier que c'est bien le cas en créant une instance à l'aide de la configuration d'instance de l'émulateur :

gcloud spanner instances create test-instance \
   --config=emulator-config --description="Test Instance" --nodes=1

Pour basculer entre l'émulateur et la configuration par défaut, exécutez la commande suivante :

gcloud config configurations activate [emulator | default]

Utiliser les bibliothèques clientes avec l'émulateur

Vous pouvez utiliser les versions compatibles des bibliothèques clientes avec l'émulateur en définissant la variable d'environnement SPANNER_EMULATOR_HOST. Pour ce faire, il existe plusieurs méthodes : Exemple :

Linux/macOS

export SPANNER_EMULATOR_HOST=localhost:9010

Windows

set SPANNER_EMULATOR_HOST=localhost:9010

Ou avec gcloud env-init :

Linux/macOS

$(gcloud emulators spanner env-init)

Windows

gcloud emulators spanner env-init > set_vars.cmd && set_vars.cmd

Lorsque votre application démarre, la bibliothèque cliente recherche automatiquement SPANNER_EMULATOR_HOST et se connecte à l'émulateur s'il est en cours d'exécution.

Une fois l'hôte SPANNER_EMULATOR_HOST défini, vous pouvez tester l'émulateur en suivant les guides de démarrage ci-dessous. Vous pouvez ignorer les instructions concernant la création, l'authentification et les identifiants du projet, car elles ne sont pas nécessaires pour utiliser l'émulateur.

Versions compatibles

Le tableau suivant répertorie les versions des bibliothèques clientes compatibles avec l'émulateur.

Bibliothèque cliente Version minimale
C++ v0.9.x+
C# v3.1.0+
Go v1.5.0+
Java v1.51.0+
Node.js v4.5.0+
PHP v1.25.0+
Python v1.15.0+
Ruby v1.13.0+

Instructions supplémentaires pour C#

Pour la bibliothèque cliente C#, vous devez également spécifier l'option emulatordetection dans la chaîne de connexion. Contrairement aux autres bibliothèques clientes, C# ignore la variable d'environnement SPANNER_EMULATOR_HOST par défaut. Voici la procédure à suivre :

var builder = new SpannerConnectionStringBuilder
{
    DataSource = $"projects/{projectId}/instances/{instanceId}/databases/{databaseId}";
    EmulatorDetection = "EmulatorOnly"
};