Émuler Spanner en local

Le gcloud 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 le 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 (IAM), autorisations ou rôles
  • Dans les modes de requête PLAN ou PROFILE , le plan de requête renvoyé est vide.
  • L'ANALYZEinstruction. L'émulateur l'accepte, mais l'ignore.
  • N'importe quel outil 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 autorise la suppression de bases de données même si cette propriété est activée.

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

  • 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 y accéder de manière exclusive jusqu'à ce qu'elles soient terminées.
  • 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 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 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.

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

Pour exécuter l'émulateur à l'aide de Google Cloud 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 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.

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é, gcloud CLI envoie vos commandes à l'émulateur au lieu du service de production. Vérifiez 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

Basculer entre les configurations

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 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#, spécifiez l' emulatordetection option 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"
};