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
ouPROFILE
, 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é oupartitionQuery
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.
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]
Démarrez l'émulateur à l'aide de la CLI gcloud.
Installer l'émulateur dans Docker
Installez Docker sur votre système et mettez-le à disposition sur le chemin d'accès au système.
Obtenez la dernière image de l'émulateur :
docker pull gcr.io/cloud-spanner-emulator/emulator
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 etlocalhost:9020
pour les requêtes REST.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 gRPClocalhost: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.
Premiers pas avec C# Vous devez définir des options de chaîne de connexion. Consultez les instructions supplémentaires pour C#.
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"
};