Premiers pas avec Spanner en Ruby

Objectifs

Ce tutoriel décrit les étapes suivantes à l'aide de l'API Spanner bibliothèque cliente pour Ruby:

  • 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 la page 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 Ruby local

  1. Installez les éléments suivants sur votre ordinateur de développement si ce n'est déjà fait :

  2. Clonez le dépôt de l'exemple d'application sur votre ordinateur local :

    git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples

    Vous pouvez également télécharger l'exemple en tant que fichier zip et l'extraire.

  3. Accédez au répertoire qui contient l'exemple de code Spanner :

    cd ruby-docs-samples/spanner/

  4. Installez les dépendances :

    bundle install

  5. Définissez la variable d'environnement GOOGLE_CLOUD_PROJECT sur votre Google Cloud ID du projet:

    export GOOGLE_CLOUD_PROJECT=[MY_PROJECT_ID]

Créer une instance

Lorsque vous utilisez Spanner pour la première fois, vous devez créer une instance, l'allocation des 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 un 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 page À 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 qui illustre l'utilisation de Spanner avec Ruby.

Examinez le fichier spanner_samples.rb, qui montre comment utiliser Spanner. Le code indique comment créer et utiliser 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 exécutant la commande suivante dans la ligne de commande.

bundle exec ruby spanner_samples.rb create_database test-instance example-db

Vous devriez obtenir le résultat suivant :

Created database example-db on instance test-instance
Le code suivant crée une base de données et deux tables dans la base de données. 
# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"
require "google/cloud/spanner/admin/database"

database_admin_client = Google::Cloud::Spanner::Admin::Database.database_admin

instance_path = database_admin_client.instance_path project: project_id, instance: instance_id

job = database_admin_client.create_database parent: instance_path,
                                            create_statement: "CREATE DATABASE `#{database_id}`",
                                            extra_statements: [
                                              "CREATE TABLE Singers (
      SingerId     INT64 NOT NULL,
      FirstName    STRING(1024),
      LastName     STRING(1024),
      SingerInfo   BYTES(MAX)
    ) PRIMARY KEY (SingerId)",

                                              "CREATE TABLE Albums (
      SingerId     INT64 NOT NULL,
      AlbumId      INT64 NOT NULL,
      AlbumTitle   STRING(MAX)
    ) PRIMARY KEY (SingerId, AlbumId),
    INTERLEAVE IN PARENT Singers ON DELETE CASCADE"
                                            ]

puts "Waiting for create database operation to complete"

job.wait_until_done!

puts "Created database #{database_id} on instance #{instance_id}"

L'étape suivante consiste à écrire des données dans la base de données.

Créer un client de base de données

Pour pouvoir effectuer des opérations de lecture ou d'écriture, vous devez créer un objet Client. Toi Un Client peut être considéré comme une connexion à une base de données: toutes vos interactions avec Spanner doit passer par un Client. En général, vous devez créer un objet Client lorsque votre application démarre. Vous réutiliserez ensuite cet objet Client pour lire, écrire et exécuter des transactions. Le code ci-dessous montre comment créer un client.

# Imports the Google Cloud client library
require "google/cloud/spanner"

# Your Google Cloud Platform project ID
project_id = "YOUR_PROJECT_ID"

# Instantiates a client
spanner = Google::Cloud::Spanner.new project: project_id

# Your Cloud Spanner instance ID
instance_id = "my-instance"

# Your Cloud Spanner database ID
database_id = "my-database"

# Gets a reference to a Cloud Spanner instance database
database_client = spanner.client instance_id, database_id

# Execute a simple SQL statement
results = database_client.execute_query "SELECT 1"
results.rows.each do |row|
  puts row
end

Pour en savoir plus, consultez la documentation de référence sur Client.

É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 execute_update().

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new project: project_id
client  = spanner.client instance_id, database_id
row_count = 0

client.transaction do |transaction|
  row_count = transaction.execute_update(
    "INSERT INTO Singers (SingerId, FirstName, LastName) VALUES
     (12, 'Melissa', 'Garcia'),
     (13, 'Russell', 'Morales'),
     (14, 'Jacqueline', 'Long'),
     (15, 'Dylan', 'Shaw'),
     (16, 'Billie', 'Eillish'),
     (17, 'Judy', 'Garland'),
     (18, 'Taylor', 'Swift'),
     (19, 'Miley', 'Cyrus'),
     (20, 'Michael', 'Jackson'),
     (21, 'Ariana', 'Grande'),
     (22, 'Elvis', 'Presley'),
     (23, 'Kanye', 'West'),
     (24, 'Lady', 'Gaga'),
     (25, 'Nick', 'Jonas')"
  )
end

puts "#{row_count} records inserted."

Exécutez l'exemple en utilisant l'argument write_using_dml.

bundle exec ruby spanner_samples.rb write_using_dml test-instance example-db

Vous devriez obtenir le résultat suivant :

 4 records inserted.

É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 d'un objet Client. La méthode Client#commit permet la création et le commit d'une transaction pour les écritures, lesquelles s'exécutent de manière atomique à un même instant logique dans les colonnes, les lignes et les tables d'une base de données.

Le code ci-dessous montre comment écrire les données à l'aide de mutations :

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new project: project_id
client  = spanner.client instance_id, database_id

client.commit do |c|
  c.insert "Singers", [
    { SingerId: 1, FirstName: "Marc",     LastName: "Richards" },
    { SingerId: 2, FirstName: "Catalina", LastName: "Smith"    },
    { SingerId: 3, FirstName: "Alice",    LastName: "Trentor"  },
    { SingerId: 4, FirstName: "Lea",      LastName: "Martin"   },
    { SingerId: 5, FirstName: "David",    LastName: "Lomond"   }
  ]
  c.insert "Albums", [
    { 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" }
  ]
end

puts "Inserted data"

Exécutez l'exemple en utilisant l'argument insert_data.

bundle exec ruby spanner_samples.rb insert_data 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. Vous pouvez accéder à cette interface via la ligne de commande à l'aide de la CLI Google Cloud ou de manière automatisée à l'aide de la bibliothèque cliente Spanner pour Ruby.

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 Ruby

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 Ruby.

La requête SQL s'exécute à l'aide de la méthode Client#execute. Pour accéder aux données d'une colonne spécifique d'une ligne, utilisez un symbole Ruby :ColumnName.

Le code ci-dessous permet d'exécuter la requête et d'accéder aux données.

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new project: project_id
client  = spanner.client instance_id, database_id

client.execute("SELECT SingerId, AlbumId, AlbumTitle FROM Albums").rows.each do |row|
  puts "#{row[:SingerId]} #{row[:AlbumId]} #{row[:AlbumTitle]}"
end

Exécutez l'exemple en utilisant l'argument query_data.

bundle exec ruby spanner_samples.rb query_data test-instance example-db

Vous devriez obtenir le résultat suivant :

1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified

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 interroger des enregistrements contenant une valeur spécifique pour LastName.

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new project: project_id
client  = spanner.client instance_id, database_id

sql_query = "SELECT SingerId, FirstName, LastName
             FROM Singers
             WHERE LastName = @lastName"

params      = { lastName: "Garcia" }
param_types = { lastName: :STRING }

client.execute(sql_query, params: params, types: param_types).rows.each do |row|
  puts "#{row[:SingerId]} #{row[:FirstName]} #{row[:LastName]}"
end

Exécutez l'exemple en utilisant l'argument query_with_parameter :

bundle exec ruby spanner_samples.rb query_with_parameter test-instance example-db

Vous devriez obtenir le résultat suivant :

12 Melissa Garcia

Lire des données à l'aide de l'API de lecture

En plus de son interface SQL, Spanner accepte de lecture.

Pour lire les lignes de la base de données, utilisez la méthode Client#read de la classe Client.

Le code ci-dessous permet de lire les données.

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new project: project_id
client  = spanner.client instance_id, database_id

client.read("Albums", [:SingerId, :AlbumId, :AlbumTitle]).rows.each do |row|
  puts "#{row[:SingerId]} #{row[:AlbumId]} #{row[:AlbumTitle]}"
end

Exécutez l'exemple en utilisant l'argument read_data.

bundle exec ruby spanner_samples.rb read_data test-instance example-db

Un résultat semblable à celui-ci s'affiche :

1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 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 pendant que celle-ci continue de diffuser du trafic. Les mises à jour du schéma ne nécessitent pas la mise hors connexion de la base de données et ne verrouillent pas des tables ou des colonnes entières. Vous pouvez continuer à écrire des données dans la base de données pendant ces mises à jour. 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 à la ligne de commande à l'aide de la CLI Google Cloud ou de manière automatisée à l'aide de la bibliothèque cliente Spanner pour Ruby.

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 Ruby

Pour modifier le schéma, utilisez la méthode Database#update de la classe Database :

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"
require "google/cloud/spanner/admin/database"

database_admin_client = Google::Cloud::Spanner::Admin::Database.database_admin

db_path = database_admin_client.database_path project: project_id,
                                              instance: instance_id,
                                              database: database_id

job = database_admin_client.update_database_ddl database: db_path,
                                                statements: [
                                                  "ALTER TABLE Albums ADD COLUMN MarketingBudget INT64"
                                                ]

puts "Waiting for database update to complete"

job.wait_until_done!

puts "Added the MarketingBudget column"

Exécutez l'exemple en utilisant l'argument add_column.

bundle exec ruby spanner_samples.rb add_column test-instance example-db

Vous devriez voir les éléments suivants :

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).

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new project: project_id
client  = spanner.client instance_id, database_id

client.commit do |c|
  c.update "Albums", [
    { SingerId: 1, AlbumId: 1, MarketingBudget: 100_000 },
    { SingerId: 2, AlbumId: 2, MarketingBudget: 500_000 }
  ]
end

puts "Updated data"

Exécutez l'exemple en utilisant l'argument update_data.

bundle exec ruby spanner_samples.rb update_data test-instance example-db

Vous devriez voir les éléments suivants :

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.

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new project: project_id
client  = spanner.client instance_id, database_id

client.execute("SELECT SingerId, AlbumId, MarketingBudget FROM Albums").rows.each do |row|
  puts "#{row[:SingerId]} #{row[:AlbumId]} #{row[:MarketingBudget]}"
end

Pour mettre en œuvre cette requête, exécutez l'exemple en utilisant l'argument query_data_with_new_column.

bundle exec ruby spanner_samples.rb query_data_with_new_column test-instance example-db

Vous devriez voir les éléments suivants :

1 1 100000
1 2
2 1
2 2 500000
2 3

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 execute_update().

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner         = Google::Cloud::Spanner.new project: project_id
client          = spanner.client instance_id, database_id
transfer_amount = 200_000

client.transaction do |transaction|
  first_album = transaction.execute(
    "SELECT MarketingBudget from Albums
     WHERE SingerId = 1 and AlbumId = 1"
  ).rows.first
  second_album = transaction.execute(
    "SELECT MarketingBudget from Albums
    WHERE SingerId = 2 and AlbumId = 2"
  ).rows.first
  raise "The second album does not have enough funds to transfer" if second_album[:MarketingBudget] < transfer_amount

  new_first_album_budget  = first_album[:MarketingBudget] + transfer_amount
  new_second_album_budget = second_album[:MarketingBudget] - transfer_amount

  transaction.execute_update(
    "UPDATE Albums SET MarketingBudget = @albumBudget WHERE SingerId = 1 and AlbumId = 1",
    params: { albumBudget: new_first_album_budget }
  )
  transaction.execute_update(
    "UPDATE Albums SET MarketingBudget = @albumBudget WHERE SingerId = 2 and AlbumId = 2",
    params: { albumBudget: new_second_album_budget }
  )
end

puts "Transaction complete"

Exécutez l'exemple en utilisant l'argument write_with_transaction_using_dml.

bundle exec ruby spanner_samples.rb write_with_transaction_using_dml 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. J'aime autres mises à jour de schéma, Spanner permet d'ajouter un index continue de diffuser du trafic. Spanner remplit automatiquement avec 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 que vous avez ajouté un index secondaire, Spanner l'utilise automatiquement pour 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 gcloud CLI ou de manière automatisée à l'aide de la bibliothèque cliente Spanner pour Ruby.

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 Ruby

Pour ajouter un index, utilisez la méthode Database#update de la classe Database :

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"
require "google/cloud/spanner/admin/database"

database_admin_client = Google::Cloud::Spanner::Admin::Database.database_admin

db_path = database_admin_client.database_path project: project_id,
                                              instance: instance_id,
                                              database: database_id

job = database_admin_client.update_database_ddl database: db_path,
                                                statements: [
                                                  "CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)"
                                                ]

puts "Waiting for database update to complete"

job.wait_until_done!

puts "Added the AlbumsByAlbumTitle index"

Exécutez l'exemple en utilisant l'argument create_index.

bundle exec ruby spanner_samples.rb create_index 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, indiquez un paramètre index à la méthode read de la classe Client.

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new project: project_id
client  = spanner.client instance_id, database_id

result = client.read "Albums", [:AlbumId, :AlbumTitle],
                     index: "AlbumsByAlbumTitle"

result.rows.each do |row|
  puts "#{row[:AlbumId]} #{row[:AlbumTitle]}"
end

Exécutez l'exemple en utilisant l'argument read_data_with_index.

bundle exec ruby spanner_samples.rb read_data_with_index test-instance example-db

Vous devriez obtenir le résultat suivant :

2 Forever Hold Your Peace
2 Go, Go, Go
1 Green
3 Terrified
1 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 Ruby

Pour ajouter un index avec une clause STORING, utilisez la méthode Database#update de la classe Database :

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"
require "google/cloud/spanner/admin/database"

database_admin_client = Google::Cloud::Spanner::Admin::Database.database_admin

db_path = database_admin_client.database_path project: project_id,
                                              instance: instance_id,
                                              database: database_id

job = database_admin_client.update_database_ddl database: db_path,
                                                statements: [
                                                  "CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle)
   STORING (MarketingBudget)"
                                                ]

puts "Waiting for database update to complete"

job.wait_until_done!

puts "Added the AlbumsByAlbumTitle2 storing index"

Exécutez l'exemple en utilisant l'argument create_storing_index.

bundle exec ruby spanner_samples.rb create_storing_index test-instance example-db

Vous devriez voir les éléments suivants :

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 :

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new project: project_id
client  = spanner.client instance_id, database_id

result = client.read "Albums", [:AlbumId, :AlbumTitle, :MarketingBudget],
                     index: "AlbumsByAlbumTitle2"

result.rows.each do |row|
  puts "#{row[:AlbumId]} #{row[:AlbumTitle]} #{row[:MarketingBudget]}"
end

Exécutez l'exemple en utilisant l'argument read_data_with_storing_index.

bundle exec ruby spanner_samples.rb read_data_with_storing_index test-instance example-db

Un résultat semblable à celui-ci s'affiche :

2 Forever Hold Your Peace 300000
2 Go, Go, Go
1 Green
3 Terrified
1 Total Junk 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. Pour obtenir un objet Snapshot, utilisez la méthode snapshot de la classe Client.

L'exemple ci-dessous montre comment exécuter une requête et effectuer une lecture dans la même transaction en lecture seule.

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new project: project_id
client  = spanner.client instance_id, database_id

client.snapshot do |snapshot|
  snapshot.execute("SELECT SingerId, AlbumId, AlbumTitle FROM Albums").rows.each do |row|
    puts "#{row[:AlbumId]} #{row[:AlbumTitle]} #{row[:SingerId]}"
  end

  # Even if changes occur in-between the reads, the transaction ensures that
  # both return the same data.
  snapshot.read("Albums", [:AlbumId, :AlbumTitle, :SingerId]).rows.each do |row|
    puts "#{row[:AlbumId]} #{row[:AlbumTitle]} #{row[:SingerId]}"
  end
end

Exécutez l'exemple en utilisant l'argument read_only_transaction.

bundle exec ruby spanner_samples.rb read_only_transaction test-instance example-db

Un résultat semblable à celui-ci s'affiche :

2 Forever Hold Your Peace 2
2 Go, Go, Go 1
1 Green 2
3 Terrified 2
1 Total Junk 1
1 Total Junk 1
2 Go, Go, Go 1
1 Green 2
2 Forever Hold Your Peace 2
3 Terrified 2

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

  1. Accédez à la page Instances de Spanner dans la console Google Cloud.

    Accéder à la page Instances

  2. Cliquez sur l'instance.

  3. Cliquez sur la base de données que vous souhaitez supprimer.

  4. Sur la page Détails de la base de données, cliquez sur Supprimer.

  5. 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

  1. Accédez à la page Instances de Spanner dans la console Google Cloud.

    Accéder à la page Instances

  2. Cliquez sur votre instance.

  3. Cliquez sur Supprimer.

  4. Confirmez que vous souhaitez supprimer l'instance, puis cliquez sur Supprimer.

Étape suivante