Objectifs
Ce tutoriel décrit les étapes suivantes à l'aide de l'API Spanner pour PHP:
- Créer une instance et une base de données Spanner
- Écrire ou lire des données dans la base de données, et exécuter des requêtes SQL sur ces données
- Mettre à jour le schéma de base de données
- Mettre à jour les données à l'aide d'une transaction en lecture/écriture
- Ajouter un index secondaire à la base de données
- Utiliser l'index pour lire et exécuter des requêtes SQL sur des données
- Récupérer des données à l'aide d'une transaction en lecture seule
Coûts
Ce tutoriel utilise Spanner, un composant facturable de Google Cloud. Pour en savoir plus sur le coût d'utilisation de Spanner, consultez Tarifs :
Avant de commencer
Pour obtenir les identifiants d'authentification permettant d'utiliser l'API Cloud Spanner, suivez les étapes décrites dans la section dédiée à la configuration qui traite des sujets suivants : création et définition d'un projet Google Cloud par défaut, activation de la facturation ainsi que de l'API Cloud Spanner, et configuration d'OAuth 2.0.
Veillez en particulier à exécuter gcloud auth
application-default login
pour configurer votre environnement de développement local avec des identifiants d'authentification.
Préparer votre environnement PHP local
Suivez les étapes décrites dans la section Comptes de service pour configurer un compte de service en tant qu'identifiants par défaut de votre application. En suivant ces étapes, vous devez obtenir un fichier de clé de compte de service (au format JSON) et une variable d'environnement
GOOGLE_APPLICATION_CREDENTIALS
qui vous permettra de vous authentifier auprès de l'API Spanner.Installez les éléments suivants sur votre ordinateur de développement si ce n'est déjà fait :
Clonez le dépôt de l'exemple d'application sur votre ordinateur local :
git clone https://github.com/GoogleCloudPlatform/php-docs-samples
Vous pouvez également télécharger l'exemple en tant que fichier zip et l'extraire.
Accédez au répertoire qui contient l'exemple de code Spanner :
cd php-docs-samples/spanner
Installez les dépendances :
composer install
Cette commande permet d'installer la bibliothèque cliente Spanner pour PHP, que vous que vous pouvez ajouter à n'importe quel projet en exécutant
composer require google/cloud-spanner
.
Créer une instance
Lorsque vous utilisez Spanner pour la première fois, vous devez créer une instance, c'est-à-dire un élément qui alloue les ressources utilisées par les bases de données Spanner. Lorsque vous créez une instance, vous choisissez une configuration d'instance, qui détermine l'emplacement de stockage de vos données et le nombre de nœuds à utiliser. Ce dernier paramètre définit la quantité de ressources disponibles dans votre instance pour le stockage et la diffusion.
Exécutez la commande suivante pour créer une instance Spanner dans la région
us-central1
avec 1 nœud:
gcloud spanner instances create test-instance --config=regional-us-central1 \
--description="Test Instance" --nodes=1
Cette commande crée une instance présentant les caractéristiques suivantes :
- ID d'instance :
test-instance
- Nom à afficher :
Test Instance
- Configuration d'instance :
regional-us-central1
(Les configurations régionales stockent les données dans une région, tandis que les configurations multirégionales les distribuent dans plusieurs régions. Pour en savoir plus, consultez la section À propos des instances.) - Nombre de nœuds : 1 (
node_count
correspond à la quantité de ressources de stockage et de diffusion disponibles pour les bases de données de l'instance. Pour en savoir plus, consultez la section Nœuds et unités de traitement par défaut.)
Vous devriez obtenir le résultat suivant :
Creating instance...done.
Consulter des exemples de fichiers
Le dépôt d'exemples contient un exemple illustrant l'utilisation de Spanner avec PHP.
Examinez les fonctions dans les fichiers src/create_database.php
et src/add_column.php
, qui montrent comment créer une base de données et modifier le schéma d'une base de données. Les données utilisent l'exemple de schéma présenté sur la page Schéma et modèle de données.
Créer une base de données
Créez une base de données nommée example-db
dans l'instance test-instance
en procédant comme suit :
en exécutant la commande suivante sur la ligne de commande.
php src/create_database.php test-instance example-db
Vous devriez obtenir le résultat suivant :
Created database example-db on instance test-instance
L'étape suivante consiste à écrire des données dans la base de données.
Créer un client de base de données
Pour effectuer des opérations de lecture et d'écriture, vous devez obtenir une instance deGoogle\Cloud\Spanner\Database
.
Un objet Database
s'apparente à une connexion à une base de données. Toutes vos interactions avec Spanner doivent s'effectuer par le biais de cet objet Database
. En général, vous devez créer un objet Database
lorsque votre application démarre. Vous réutiliserez ensuite cet objet Database
pour lire, écrire et exécuter des transactions. Chaque client utilise des ressources dans Spanner.
Si vous créez plusieurs clients dans la même application, vous devez appeler Database::close
pour nettoyer les ressources du client, y compris les connexions réseau, dès que ce n'est pas le cas nécessaire.
Pour en savoir plus, consultez la documentation de référence sur Database
.
Écrire des données avec le langage LMD
Vous pouvez insérer des données à l'aide du langage de manipulation de données (LMD) dans une transaction en lecture/écriture.
L'exécution d'une instruction LMD s'effectue via la méthode executeUpdate()
.
Exécutez le fichier d'exemple src/write_data_with_dml.php
.
php src/write_data_with_dml.php test-instance example-db
Vous devriez obtenir le résultat suivant :
Inserted 4 row(s).
Écrire des données avec des mutations
Vous pouvez également insérer des données à l'aide de mutations.
Vous pouvez écrire des données à l'aide de la méthode Database::insertBatch
. insertBatch
ajoute des lignes à une table. Toutes les insertions d'un même lot sont appliquées de manière atomique.
Le code ci-dessous montre comment écrire les données à l'aide de mutations :
Exécutez l'exemple de fichier src/insert_data.php
.
php src/insert_data.php test-instance example-db
Vous devriez obtenir le résultat suivant :
Inserted data.
Interroger des données à l'aide de SQL
Spanner accepte une interface SQL pour la lecture des données, que vous pouvez via la ligne de commande à l'aide de la Google Cloud CLI de manière programmatique à l'aide la bibliothèque cliente Spanner pour PHP.
Sur la ligne de commande
Exécutez l'instruction SQL suivante pour lire les valeurs de toutes les colonnes de la table Albums
:
gcloud spanner databases execute-sql example-db --instance=test-instance \
--sql='SELECT SingerId, AlbumId, AlbumTitle FROM Albums'
Vous devez obtenir le résultat suivant :
SingerId AlbumId AlbumTitle
1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified
Utiliser la bibliothèque cliente Spanner pour PHP
Outre l'exécution d'une instruction SQL via la ligne de commande, vous pouvez utiliser le la même instruction SQL de manière programmatique à l'aide de la bibliothèque cliente Spanner PHP.
Utilisez la méthodeDatabase::execute()
pour exécuter la requête SQL.
Le code ci-dessous permet d'exécuter la requête et d'accéder aux données.
Exécutez l'exemple de fichier src/query_data.php
.
php src/query_data.php test-instance example-db
Vous devriez obtenir le résultat suivant :
SingerId: 2, AlbumId: 2, AlbumTitle: Forever Hold Your Peace
SingerId: 1, AlbumId: 2, AlbumTitle: Go, Go, Go
SingerId: 2, AlbumId: 1, AlbumTitle: Green
SingerId: 2, AlbumId: 3, AlbumTitle: Terrified
SingerId: 1, AlbumId: 1, AlbumTitle: Total Junk
Vos résultats ne s'afficheront pas nécessairement dans cet ordre. Si vous devez les classer, utilisez une clause ORDER BY
, comme indiqué sur la page Bonnes pratiques sur les instructions SQL.
Requête utilisant un paramètre SQL
Si votre application comporte une requête fréquemment exécutée, vous pouvez améliorer ses performances en les paramétrant. La requête paramétrique obtenue peut être mise en cache et réutilisée, ce qui réduit les coûts de compilation. Pour en savoir plus, consultez Utilisez des paramètres de requête pour accélérer les requêtes fréquemment exécutées.
Voici un exemple d'utilisation d'un paramètre dans la clause WHERE
pour
enregistrements de requête contenant une valeur spécifique pour LastName
.
Exécutez l'exemple de fichier src/query_data_with_parameter.php
.
php src/query_data_with_parameter.php test-instance example-db
Vous devriez obtenir le résultat suivant :
SingerId: 12, FirstName: Melissa, LastName: Garcia
Lire des données à l'aide de l'API de lecture
En plus de son interface SQL, Spanner accepte de lecture.
Utilisez Database::read()
pour lire les lignes de la base de données. Utilisez un objet KeySet
pour définir une collection de clés et de plages de clés à lire.
Le code ci-dessous permet de lire les données.
Exécutez l'exemple dans le fichier read_data.php
.
php read_data.php test-instance example-db
Un résultat semblable à celui-ci s'affiche :
SingerId: 1, AlbumId: 1, AlbumTitle: Total Junk
SingerId: 1, AlbumId: 2, AlbumTitle: Go, Go, Go
SingerId: 2, AlbumId: 1, AlbumTitle: Green
SingerId: 2, AlbumId: 2, AlbumTitle: Forever Hold your Peace
SingerId: 2, AlbumId: 3, AlbumTitle: Terrified
Mettre à jour le schéma de base de données
Supposons que vous deviez ajouter la colonne MarketingBudget
à la table Albums
. L'ajout d'une colonne à une table existante nécessite une mise à jour du schéma de base de données. Spanner permet de mettre à jour le schéma d'une base de données, tandis que
continue de diffuser du trafic. Les mises à jour de schéma ne nécessitent pas
hors ligne et ne verrouillent pas
des tables ou des colonnes entières ; vous pouvez continuer
l'écriture de données dans la base de données
pendant la mise à jour du schéma. En savoir plus sur les compatibilités
des mises à jour de schéma
et des performances liées aux modifications de schéma
Effectuez des mises à jour de schéma.
Ajouter une colonne
Vous pouvez ajouter une colonne sur la ligne de commande à l'aide de la Google Cloud CLI ou de manière programmatique à l'aide la bibliothèque cliente Spanner pour PHP.
Sur la ligne de commande
Pour ajouter la colonne à la table, utilisez la commande ALTER TABLE
suivante :
GoogleSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='ALTER TABLE Albums ADD COLUMN MarketingBudget INT64'
PostgreSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='ALTER TABLE Albums ADD COLUMN MarketingBudget BIGINT'
Vous devriez obtenir le résultat suivant :
Schema updating...done.
Utiliser la bibliothèque cliente Spanner pour PHP
Utilisez Database::updateDdl
pour modifier le schéma :
Exécutez l'exemple de fichier src/add_column.php
.
php src/add_column.php test-instance example-db
Vous devriez obtenir le résultat suivant :
Added the MarketingBudget column.
Écrire des données dans la nouvelle colonne
Le code ci-dessous permet d'écrire des données dans la nouvelle colonne. Il définit MarketingBudget
sur 100000
pour la ligne correspondant à la clé Albums(1, 1)
et sur 500000
pour la ligne correspondant à la clé Albums(2, 2)
.
Exécutez l'exemple de fichier src/update_data.php
.
php src/update_data.php test-instance example-db
Vous devriez obtenir le résultat suivant :
Updated data.
Vous pouvez également exécuter une requête SQL ou un appel de lecture pour récupérer les valeurs que vous venez d'écrire.
Le code permettant d'exécuter la requête est présenté ci-dessous.
Pour mettre en œuvre cette requête, exécutez le fichier d'exemple src/query-data-with-new-column.php
.
php src/query_data_with_new_column.php test-instance example-db
Vous devriez obtenir le résultat suivant :
SingerId: 1, AlbumId: 1, MarketingBudget: 100000
SingerId: 1, AlbumId: 2, MarketingBudget: 0
SingerId: 2, AlbumId: 1, MarketingBudget: 0
SingerId: 2, AlbumId: 2, MarketingBudget: 500000
SingerId: 2, AlbumId: 3, MarketingBudget: 0
Mettre à jour des données
Vous pouvez mettre à jour des données à l'aide du langage LMD dans une transaction en lecture/écriture.
L'exécution d'une instruction LMD s'effectue via la méthode executeUpdate()
.
Exécutez l'exemple de fichier src/write_data_with_dml_transaction.php
.
php src/write_data_with_dml_transaction.php test-instance example-db
Vous devriez obtenir le résultat suivant :
Transaction complete.
Utiliser un index secondaire
Supposons que vous vouliez récupérer toutes les lignes de la table Albums
dont les valeurs AlbumTitle
sont comprises dans une certaine plage. Vous pouvez lire toutes les valeurs de la colonne AlbumTitle
à l'aide d'une instruction SQL ou d'un appel de lecture, puis supprimer les lignes qui ne correspondent pas aux critères. Toutefois, cette analyse complète de la table est coûteuse, en particulier si celle-ci comporte beaucoup de lignes. Vous pouvez accélérer la récupération des lignes lors des recherches effectuées en fonction des colonnes de clé non primaire en créant un index secondaire pour la table.
L'ajout d'un index secondaire à une table existante nécessite une mise à jour du schéma. Comme pour les autres mises à jour de schéma, Spanner permet d'ajouter un index alors que la base de données continue de diffuser du trafic. Spanner remplit automatiquement l'index à l'aide de vos données existantes. Les remplissages peuvent prendre quelques minutes. Toutefois, ce processus ne requiert pas la mise hors connexion de la base de données et ne vous empêche pas d'écrire dans la table indexée. Pour en savoir plus, consultez la section Ajouter un index secondaire.
Une fois l'index secondaire ajouté, Spanner l'utilise automatiquement pour les requêtes SQL susceptibles de s'exécuter plus rapidement avec l'index. Si vous utilisez l'interface de lecture, vous devez spécifier l'index que vous souhaitez utiliser.
Ajouter un index secondaire
Vous pouvez ajouter un index via la ligne de commande à l'aide de la CLI gcloud ou de manière automatisée à l'aide de la bibliothèque cliente Spanner pour PHP.
Sur la ligne de commande
Exécutez la commande CREATE INDEX
suivante pour ajouter un index à la base de données :
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)'
Vous devriez obtenir le résultat suivant :
Schema updating...done.
Utiliser la bibliothèque cliente Spanner pour PHP
Utilisez Database::updateDdl
pour ajouter un index :
Exécutez le fichier d'exemple src/create_index.php
.
php src/create_index.php test-instance example-db
L'ajout d'un index peut prendre quelques minutes. Une fois l'index ajouté, vous devriez obtenir le résultat suivant :
Added the AlbumsByAlbumTitle index.
Lire des données avec l'index
Pour les requêtes SQL, Spanner utilise automatiquement un index approprié. Dans l'interface de lecture, vous devez spécifier l'index dans votre requête.
Pour utiliser l'index dans l'interface de lecture, utilisez la méthode Database::read
.
Exécutez le fichier d'exemple src/read_data_with_index.php
.
php src/read_data_with_index.php test-instance example-db
Vous devriez obtenir le résultat suivant :
AlbumId: 2, AlbumTitle: Forever Hold your Peace
AlbumId: 2, AlbumTitle: Go, Go, Go
AlbumId: 1, AlbumTitle: Green
AlbumId: 3, AlbumTitle: Terrified
AlbumId: 1, AlbumTitle: Total Junk
Ajouter un index pour les lectures en mode index uniquement
Vous avez peut-être remarqué que l'exemple de lecture précédent n'incluait pas la lecture de la colonne MarketingBudget
. En effet, l'interface de lecture de Spanner ne permet pas de joindre un index à une table de données pour rechercher des valeurs qui ne sont pas stockées dans l'index.
Créez une autre définition de l'index AlbumsByAlbumTitle
qui stocke dans l'index une copie de MarketingBudget
.
Sur la ligne de commande
GoogleSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) STORING (MarketingBudget)
PostgreSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) INCLUDE (MarketingBudget)
L'ajout d'un index peut prendre quelques minutes. Une fois l'index ajouté, vous devriez obtenir le résultat suivant :
Schema updating...done.
Utiliser la bibliothèque cliente Spanner pour PHP
Utilisez la méthodeDatabase::updateDdl
pour ajouter un index avec une clause STORING
:
Exécutez l'exemple de fichier src/create_storing_index.php
.
php src/create_storing_index.php test-instance example-db
Vous devriez obtenir le résultat suivant :
Added the AlbumsByAlbumTitle2 index.
Vous pouvez maintenant exécuter une opération de lecture permettant de récupérer toutes les colonnes AlbumId
, AlbumTitle
et MarketingBudget
à partir de l'index AlbumsByAlbumTitle2
:
Exécutez l'exemple de fichier src/read_data_with_storing_index.php
.
php src/read_data_with_storing_index.php test-instance example-db
Un résultat semblable à celui-ci s'affiche :
AlbumId: 2, AlbumTitle: Forever Hold your Peace, MarketingBudget: 300000
AlbumId: 2, AlbumTitle: Go, Go, Go, MarketingBudget: 0
AlbumId: 1, AlbumTitle: Green, MarketingBudget: 0
AlbumId: 3, AlbumTitle: Terrified, MarketingBudget: 0
AlbumId: 1, AlbumTitle: Total Junk, MarketingBudget: 300000
Récupérer des données à l'aide de transactions en lecture seule
Supposons que vous souhaitiez exécuter plusieurs opérations de lecture avec le même horodatage. Les transactions en lecture seule tiennent compte d'un préfixe cohérent de l'historique de commit des transactions, de sorte que votre application obtienne toujours des données cohérentes.
Pour exécuter des transactions en lecture seule, utilisez un objet Snapshot
. Utilisez la méthode Database::snapshot
pour obtenir un objet Snapshot
.
L'exemple ci-dessous montre comment exécuter une requête et effectuer une lecture dans la même transaction en lecture seule.
Exécutez l'exemple de fichier src/read_only_transaction.php
.
php src/read_only_transaction.php test-instance example-db
Un résultat semblable à celui-ci s'affiche :
Results from first read:
SingerId: 2, AlbumId: 2, AlbumTitle: Forever Hold Your Peace
SingerId: 1, AlbumId: 2, AlbumTitle: Go, Go, Go
SingerId: 2, AlbumId: 1, AlbumTitle: Green
SingerId: 2, AlbumId: 3, AlbumTitle: Terrified
SingerId: 1, AlbumId: 1, AlbumTitle: Total Junk
Results from second read:
SingerId: 1, AlbumId: 1, AlbumTitle: Total Junk
SingerId: 1, AlbumId: 2, AlbumTitle: Go, Go, Go
SingerId: 2, AlbumId: 1, AlbumTitle: Green
SingerId: 2, AlbumId: 2, AlbumTitle: Forever Hold Your Peace
SingerId: 2, AlbumId: 3, AlbumTitle: Terrified
Nettoyage
Pour éviter que des frais supplémentaires ne soient facturés sur votre compte Cloud Billing pour les ressources utilisées dans ce tutoriel, supprimez la base de données et l'instance que vous avez créées.
Supprimer la base de données
Si vous supprimez une instance, toutes les bases de données qu'elle contient sont automatiquement supprimées. Cette étape montre comment supprimer une base de données sans supprimer l'instance. Des frais continueront à vous être facturés pour cette dernière.
Sur la ligne de commande
gcloud spanner databases delete example-db --instance=test-instance
Utiliser la console Google Cloud
Accédez à la page Instances de Spanner dans la console Google Cloud.
Cliquez sur l'instance.
Cliquez sur la base de données que vous souhaitez supprimer.
Sur la page Détails de la base de données, cliquez sur Supprimer.
Confirmez que vous souhaitez supprimer la base de données, puis cliquez sur Supprimer.
Supprimer l'instance
La suppression d'une instance supprime automatiquement toutes les bases de données créées dans cette instance.
Sur la ligne de commande
gcloud spanner instances delete test-instance
Utiliser la console Google Cloud
Accédez à la page Instances Spanner dans la console Google Cloud.
Cliquez sur votre instance.
Cliquez sur Supprimer.
Confirmez que vous souhaitez supprimer l'instance, puis cliquez sur Supprimer.
Étape suivante
Découvrez comment accéder à Spanner avec une instance de machine virtuelle.
Pour en savoir plus sur les identifiants d'autorisation et d'authentification, consultez la page S'authentifier auprès de services cloud à l'aide de bibliothèques clientes.
En savoir plus sur les bonnes pratiques concernant la conception de schémas Spanner.