Émuler Spanner en local

La Google Cloud CLI fournit un émulateur local en mémoire pour développer et tester vos applications. É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 dialectes GoogleSQL et PostgreSQL. Il est compatible avec tous les langages des bibliothèques clientes. Vous pouvez également utiliser l'émulateur avec la gcloud 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 :

  • Les protocoles TLS/HTTPS, l'authentification, IAM (Identity and Access Management), les autorisations et les rôles ne sont pas compatibles.
  • 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.
  • Tous les outils de journalisation d'audit et de surveillance.
  • Protection contre la suppression de bases de données. L'émulateur accepte le champ enable_drop_protection, mais il permet de supprimer des bases de données même si cette propriété est activée.

L'émulateur diffère également du service de production Spanner de la manière suivante :

  • Les messages d'erreur peuvent différer entre l'émulateur et le service de production.
  • Les performances et l'évolutivité de l'émulateur ne sont pas comparables à celles du 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 un accès exclusif jusqu'à leur exécution.
  • L'émulateur est compatible avec le LMD partitionné et partitionQuery, mais il ne vérifie pas que les instructions sont partitionnables. Cela signifie qu'une instruction LMD partitionnée ou partitionQuery peut s'exécuter dans l'émulateur, mais échouer dans le service de production avec l'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 adaptée à votre workflow de développement et de test d'applications.

Exécuter l'émulateur à l'aide de la gcloud CLI

Pour exécuter l'émulateur à l'aide de la gcloud CLI :

  1. Installez le composant cloud-spanner-emulator :

    gcloud components install cloud-spanner-emulator

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

    gcloud components update

  2. Démarrez l'émulateur :

    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

Exécuter l'émulateur à l'aide de Docker

Pour exécuter l'émulateur à l'aide de Docker :

  1. Installez Docker sur votre système et rendez-le disponible dans le chemin d'accès du 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.

Configurer gcloud CLI pour utiliser l'émulateur

Pour utiliser l'émulateur avec gcloud CLI, désactivez l'authentification et remplacez le point de terminaison. Créez une configuration gcloud CLI distincte pour 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/

  2. Une fois configurée, gcloud CLI envoie vos commandes à l'émulateur au lieu du service de production. Pour le vérifier, créez une instance avec la configuration d'instance de l'émulateur :

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

Changer de configuration

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

# To switch to default (production) configuration:
gcloud config configurations activate default

# To switch back to emulator configuration:
gcloud config configurations activate emulator

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 que SPANNER_EMULATOR_HOST est défini, vous pouvez tester l'émulateur en suivant les guides de démarrage. Ignorez les instructions concernant la création de projet, l'authentification et les identifiants, 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 le langage C

Pour la bibliothèque cliente C#, spécifiez 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. L'exemple suivant montre la chaîne de connexion :

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