É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 avec une instance d'essai gratuit sans avoir à créer de projet Google Cloud ni de compte de facturation. Étant donné que l'émulateur ne stocke les données qu'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 dialectes GoogleSQL et PostgreSQL. Il est compatible avec tous les langages des bibliothèques clientes. Vous pouvez également utiliser l'émulateur avec la Google Cloud CLI 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:

  • TLS/HTTPS, authentification, Identity and Access Management, autorisations ou rôles
  • Dans les modes de requête PLAN ou PROFILE, le plan de requête renvoyé est vide.
  • L'instruction ANALYZE L'émulateur l'accepte, mais l'ignore.
  • N'importe quel outil de journalisation d'audit et de surveillance

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 partitionQuery sont compatibles, mais l'émulateur ne vérifie pas que les instructions sont partitionnables. Cela signifie qu'une instruction de LMD partitionné ou partitionQuery 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.

Options d'exécution de l'émulateur

Il existe deux façons courantes d'exécuter l'émulateur:

Choisissez la méthode la plus adaptée au workflow de développement et de test de votre application.

Configurer l'émulateur pour la CLI gcloud

Pour les utilisateurs de Windows et de macOS, avant d'installer l'émulateur, procédez comme suit:

  • Installez les composants de la gcloud CLI sur votre station de travail:

    gcloud components install

    Si gcloud CLI est déjà installé, exécutez la commande suivante pour vous assurer que tous ses composants sont à jour:

    gcloud components update

Créer et configurer l'émulateur à l'aide de la gcloud CLI

Pour utiliser l'émulateur avec gcloud CLI, vous devez désactiver l'authentification et remplacer le point de terminaison. Nous vous recommandons de créer une configuration de la CLI gcloud distincte afin de pouvoir basculer rapidement entre l'émulateur et le service de production.

  1. Créez et activez une configuration d'émulateur:

      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 CLI sont envoyées à l'émulateur au lieu du service de production. Pour vérifier que c'est bien le cas, créez 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]

  2. Démarrez l'émulateur à l'aide de la CLI gcloud.

Installer l'émulateur dans Docker

  1. Installez Docker sur votre système et mettez-le à disposition 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. Exécutez l'émulateur dans Docker:

    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. L'émulateur utilise deux points de terminaison locaux : localhost:9010 pour les requêtes gRPC et localhost:9020 pour les requêtes REST.

  4. Démarrez l'émulateur à l'aide de la CLI gcloud.

Démarrer l'émulateur à l'aide de la CLI gcloud

Démarrez l'émulateur à l'aide de la commande gcloud emulators spanner:

gcloud emulators spanner start

L'émulateur utilise deux points de terminaison locaux:

  • localhost:9010 pour les requêtes gRPC
  • localhost:9020 pour les requêtes REST

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 SPANNER_EMULATOR_HOST défini, vous pouvez tester l'émulateur en suivant les guides de démarrage. Ignorez 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 un exemple de chaîne de connexion:

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