Ruby で Spanner を使ってみる

目標

このチュートリアルでは、Ruby 用 Spanner クライアントライブラリを使用する以下の手順について説明します。

Spanner のインスタンスとデータベースを作成します。
データベースのデータに対し、書き込み、読み取り、SQL クエリの実行を行います。
データベーススキーマを更新します。
読み取り / 書き込みトランザクションを使用してデータを更新します。
セカンダリインデックスをデータベースに追加します。
インデックスを使用して、データの読み込みと SQL クエリの実行を行います。
読み取り専用トランザクションを使用してデータを取得します。

費用

このチュートリアルでは、Google Cloudの課金対象コンポーネントである Spanner を使用します。Spanner の使用料金については、料金についてのページをご覧ください。

始める前に

設定で説明されている手順を終わらせておきます。この手順では、デフォルトの Google Cloud プロジェクトの作成と設定、課金の有効化、Cloud Spanner API の有効化、Cloud Spanner API の使用に必要な認証情報を取得するための OAuth 2.0 の設定を行います。

特に、gcloud auth application-default login を使用したローカル開発環境の認証情報の設定は必ず行ってください。

ローカルの Ruby 環境を準備する

開発マシンに次のものがまだインストールされていない場合はインストールします。
- Ruby
- Bundler
ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。
```
git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples
```
または、zip ファイル形式のサンプルをダウンロードし、展開します。
Spanner のサンプルコードが含まれるディレクトリに移動します。
```
cd ruby-docs-samples/spanner/
```
依存関係をインストールします。
```
bundle install
```
GOOGLE_CLOUD_PROJECT 環境変数を Google Cloudプロジェクト ID に設定します。
```
export GOOGLE_CLOUD_PROJECT=[MY_PROJECT_ID]
```

インスタンスを作成する

Spanner を最初に使用する際は、インスタンスを作成する必要があります。インスタンスとは、Spanner データベースによって使用されるリソースの割り当てのことです。インスタンスの作成時には、インスタンス構成を選択してデータの格納場所を指定し、さらに使用するノード数も選択してインスタンスの配信リソースおよびストレージリソースの量を決定します。

次のコマンドを実行して、ノードが 1 つある Spanner インスタンスを us-central1 リージョンに作成します。

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

これにより、次の特性を持つインスタンスが作成されます。

インスタンス ID test-instance
表示名 Test Instance
インスタンス構成 regional-us-central1（リージョン構成ではデータが単一のリージョンに保存され、マルチリージョン構成ではデータが複数のリージョンに分散されます。詳しくは、インスタンスについてをご覧ください）。
ノード数 1（node_count はインスタンスのデータベースで使用可能な配信リソースとストレージリソースの量に対応します。詳しくは、ノードと処理ユニットをご覧ください）。

次のように表示されます。

Creating instance...done.

サンプルファイルを確認する

サンプルリポジトリには、Ruby で Spanner を使用する方法を示すサンプルが含まれています。

spanner_samples.rb ファイルを見ると、Spanner の使用方法を確認できます。このファイルのコードでは、新しいデータベースを作成して使用する方法が示されています。データで使用しているサンプルスキーマは、スキーマとデータモデルのページにあります。

データベースを作成する

GoogleSQL

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

PostgreSQL

bundle exec ruby spanner_postgresql_create_database.rb postgresql_create_database MY_PROJECT_ID test-instance example-db

次のように表示されます。

Created database example-db on instance test-instance

次のコードは、データベースを作成し、そのデータベース内に 2 つのテーブルを作成します。

GoogleSQL

# 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}"

PostgreSQL

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

def postgresql_create_database project_id:, instance_id:, database_id:
  # project_id  = "Your Google Cloud project ID"
  # instance_id = "Your Spanner instance ID"
  # database_id = "Your Spanner database ID"

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

  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}\"",
                                              database_dialect: :POSTGRESQL

  puts "Waiting for create database operation to complete"

  job.wait_until_done!

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

次のステップでは、データベースにデータを書き込みます。

データベースクライアントを作成する

読み取りまたは書き込みを行うには、その前に Client を作成する必要があります。Client はデータベース接続と考えることができます。Spanner とのすべてのやり取りは Client を経由する必要があります。通常はアプリケーション開始時に Client を作成し、読み取り、書き込み、トランザクションの実行に 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

詳細については、Client のリファレンスをご覧ください。

DML を使用してデータを書き込む

読み取り / 書き込みトランザクションでデータ操作言語（DML）を使用してデータを挿入できます。

execute_update() メソッドを使用して DML ステートメントを実行します。

# 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."

write_using_dml 引数を使用してサンプルを実行します。

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

次のように表示されます。

 4 records inserted.

ミューテーションを使用してデータを書き込む

ミューテーションを使ってデータを挿入することもできます。

データの書き込みには Client オブジェクトを使用します。Client#commit メソッドは、データベース内の列、行、テーブルにまたがる時点の単一の論理ポイントでアトミックに実行される書き込みトランザクションを作成し、commit します。

次のコードは、ミューテーションを使用してデータを書き込む方法を示しています。

# 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"

insert_data 引数を使用してサンプルを実行します。

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

次のように表示されます。

Inserted data

SQL を使用したデータのクエリ

Spanner では、データの読み取りのために SQL インターフェースがサポートされています。このインターフェースにアクセスするには、コマンドラインで Google Cloud CLI を使用するか、プログラムで Ruby 用 Spanner クライアントライブラリを使用します。

コマンドラインから

Albums テーブルのすべての列から値を読み取るには、次の SQL ステートメントを実行します。

gcloud spanner databases execute-sql example-db --instance=test-instance \
    --sql='SELECT SingerId, AlbumId, AlbumTitle FROM Albums'

結果は次のようになります。

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

Ruby 用 Spanner クライアントライブラリを使用する

コマンドラインで SQL ステートメントを実行するだけでなく、プログラムから Ruby 用 Spanner クライアントライブラリを使用して同じ SQL ステートメントを発行することもできます。

SQL クエリを実行するには、Client#execute メソッドを使用します。Ruby シンボル: :ColumnName を使用すると、行から特定の列のデータにアクセスできます。

クエリを発行してデータにアクセスする方法を次に示します。

# 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

query_data 引数を使用してサンプルを実行します。

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

次のような結果が表示されます。

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

SQL パラメータを使用してクエリする

頻繁に実行されるクエリがアプリケーションにある場合は、対象のクエリをパラメータ化してパフォーマンスを改善できます。パラメータクエリをキャッシュに保存して再利用することで、コンパイルのコストを削減できます。詳細については、クエリパラメータを使用して、頻繁に実行するクエリを高速化するをご覧ください。

ここでは、WHERE 句のパラメータを使用して、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

query_with_parameter 引数を使用してサンプルを実行します。

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

次のような結果が表示されます。

12 Melissa Garcia

読み取り API を使用してデータを読み取る

Spanner は SQL インターフェースだけでなく、読み取りインターフェースもサポートしています。

データベースから行を読み取るには、Client クラスの Client#read メソッドを使用します。

データを読み取る方法は次のとおりです。

# 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

read_data 引数を使用してサンプルを実行します。

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

次のような出力が表示されます。

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

データベーススキーマを更新する

MarketingBudget という列を新たに Albums テーブルに追加する必要があるとします。既存のテーブルに新しい列を追加するには、データベーススキーマの更新が必要です。Spanner では、データベースでのトラフィックの処理中にデータベースのスキーマを更新できます。スキーマの更新では、データベースをオフラインにする必要がなく、テーブル全体あるいは列全体をロックすることもありません。スキーマの更新中もデータベースへのデータの書き込みを続けることができます。サポートされるスキーマの更新とスキーマ変更のパフォーマンスの詳細については、スキーマを更新するをご覧ください。

列を追加する

列を追加するには、コマンドラインで Google Cloud CLI を使用するか、プログラムから Ruby 用 Spanner クライアントライブラリを使用します。

コマンドラインから

テーブルに新しい列を追加するには、次の ALTER TABLE コマンドを使用します。

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'

次のように表示されます。

Schema updating...done.

Ruby 用 Spanner クライアントライブラリを使用する

スキーマを変更するには、Database クラスの Database#update メソッドを使用します。

# 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"

add_column 引数を使用してサンプルを実行します。

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

以下のように表示されます。

Added the MarketingBudget column

新しい列へのデータの書き込み

次のコードは、新しい列にデータを書き込みます。MarketingBudget の値を、キーが Albums(1, 1) の行は 100000 に、キーが Albums(2, 2) の行は 500000 に設定します。

# 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"

update_data 引数を使用してサンプルを実行します。

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

以下のように表示されます。

Updated data

SQL クエリまたは読み取り呼び出しを実行して、書き込んだばかりの値を取得することもできます。

クエリを実行するコードを次に示します。

# 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

このクエリを実行するには、query_data_with_new_column 引数を使用してサンプルを実行します。

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

以下のように表示されます。

データの更新

読み取り / 書き込みトランザクションで DML を使用してデータを更新できます。

execute_update() メソッドを使用して DML ステートメントを実行します。

# 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"

write_with_transaction_using_dml 引数を使用してサンプルを実行します。

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

次のように表示されます。

Transaction complete

セカンダリインデックスを使用する

Albums から AlbumTitle の値が特定の範囲内にある行すべてを取得すると仮定します。SQL ステートメントまたは読み取り呼び出しを使用して AlbumTitle 列からすべての値を読み取り、基準を満たしていない行を破棄することもできますが、このようなテーブル全体のスキャンは割高です（特に、行数が多いテーブルの場合）。代わりに、テーブルにセカンダリインデックスを作成することにより、主キー以外の列を検索するときの行の取得速度を上げることができます。

既存のテーブルにセカンダリインデックスを追加するには、スキーマの更新が必要です。他のスキーマの更新と同様に、Spanner ではデータベースがトラフィックを提供している間にインデックスを追加できます。Spanner では、インデックスに既存のデータが自動的にバックフィルされます。バックフィルには数分かかることがありますが、このプロセスの間に、データベースをオフラインにしたり、インデックス化対象のテーブルへの書き込みを控えたりする必要はありません。詳しくは、セカンダリインデックスを追加するをご覧ください。

セカンダリインデックスを追加すると、インデックスの効果により実行速度が上がりそうな SQL クエリに対してそのセカンダリインデックスが自動的に使用されるようになります。読み取りインターフェースを使用する場合は、使用するインデックスを指定する必要があります。

セカンダリインデックスを追加する

コマンドラインでインデックスを追加するには、gcloud CLI を使用するか、プログラムから Ruby 用 Spanner クライアントライブラリを使用します。

コマンドラインから

データベースにインデックスを追加するには、次の CREATE INDEX コマンドを使用します。

gcloud spanner databases ddl update example-db --instance=test-instance \
    --ddl='CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)'

次のように表示されます。

Schema updating...done.

Ruby 用 Spanner クライアントライブラリの使用

インデックスを追加するには、Database クラスの Database#update メソッドを使用します。

# 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"

create_index 引数を使用してサンプルを実行します。

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

インデックスの追加には数分かかる場合があります。インデックスが追加されると、次のように表示されます。

Added the AlbumsByAlbumTitle index

インデックスを使用して読み取る

SQL クエリの場合、Spanner により適切なインデックスが自動的に使用されます。読み取りインターフェースでは、リクエストでインデックスを指定する必要があります。

読み取りインターフェースでインデックスを使用するには、Client クラスの read メソッドに index パラメータを渡します。

# 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

read_data_with_index 引数を使用してサンプルを実行します。

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

以下のように表示されます。

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

インデックス限定の読み取り用インデックスを追加する

前述の読み取り例には、MarketingBudget 列の読み取りが含まれていませんでした。これは、Spanner の読み取りインターフェースが、インデックスとデータテーブルを結合してインデックスに格納されていない値を検索する機能をサポートしていないためです。

MarketingBudget のコピーをインデックスに格納する AlbumsByAlbumTitle の代替定義を作成します。

コマンドラインを使用する

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)

インデックスの追加には数分かかる場合があります。インデックスが追加されると、次のように表示されます。

Schema updating...done.

Ruby 用 Spanner クライアントライブラリの使用

Database クラスの Database#update メソッドを使用し、STORING 句を指定してインデックスを追加します。

# 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"

create_storing_index 引数を使用してサンプルを実行します。

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

以下のように表示されます。

Added the AlbumsByAlbumTitle2 index

これで、インデックス AlbumsByAlbumTitle2 から AlbumId、AlbumTitle、MarketingBudget 列をすべて取得する読み取りを実行できるようになりました。

# 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

read_data_with_storing_index 引数を使用してサンプルを実行します。

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

次のような出力が表示されます。

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

読み取り専用トランザクションを使用したデータの取得

同じタイムスタンプで複数の読み取りを実行する場合について考えます。読み取り専用トランザクションは、トランザクションの commit 履歴で整合性のある接頭辞を監視しているため、アプリケーションは常に整合性のあるデータを取得できます。読み取り専用トランザクションを実行するには、Snapshot オブジェクトを使用します。Client クラスの snapshot メソッドを使用して、Snapshot オブジェクトを取得します。

同じ読み取り専用トランザクションでクエリと読み取りを実行する方法を次に示します。

# 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

read_only_transaction 引数を使用してサンプルを実行します。

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

次のような出力が表示されます。

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

クリーンアップする

このチュートリアルで使用したリソースについて Cloud 請求先アカウントに課金されないようにするには、作成したデータベースとインスタンスを削除します。

データベースを削除する

インスタンスを削除すると、それに含まれるすべてのデータベースが自動的に削除されます。このステップでは、インスタンスを削除しないでデータベースを削除する方法を示します（インスタンスの料金は引き続き発生します）。

コマンドラインから

gcloud spanner databases delete example-db --instance=test-instance

Google Cloud コンソールの使用

Google Cloud コンソールの [Spanner インスタンス] ページに移動します。

インスタンスページに移動
インスタンスをクリックします。
削除するデータベースをクリックします。
[データベースの詳細] ページで [削除] をクリックします。
データベースを削除することを確認し、[削除] をクリックします。

インスタンスの削除

インスタンスを削除すると、そのインスタンスで作成されたすべてのデータベースが自動的に削除されます。

コマンドラインから

gcloud spanner instances delete test-instance

Google Cloud コンソールの使用

Google Cloud コンソールの [Spanner インスタンス] ページに移動します。

インスタンスページに移動
インスタンスをクリックします。
[削除] をクリックします。
インスタンスを削除することを確認し、[削除] をクリックします。

次のステップ

仮想マシンインスタンスで Spanner にアクセスする方法を確認する。
クライアントライブラリを使用して Cloud サービスに対する認証を行うで、認可と認証について確認する。
Spanner のスキーマ設計のベストプラクティスを確認する。

Ruby で Spanner を使ってみる コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

目標

費用

始める前に

ローカルの Ruby 環境を準備する

インスタンスを作成する

サンプル ファイルを確認する

データベースを作成する

GoogleSQL

PostgreSQL

GoogleSQL

PostgreSQL

データベース クライアントを作成する

DML を使用してデータを書き込む

ミューテーションを使用してデータを書き込む

SQL を使用したデータのクエリ

コマンドラインから

Ruby 用 Spanner クライアント ライブラリを使用する

SQL パラメータを使用してクエリする

読み取り API を使用してデータを読み取る

データベース スキーマを更新する

列を追加する

コマンドラインから

GoogleSQL

PostgreSQL

Ruby 用 Spanner クライアント ライブラリを使用する

新しい列へのデータの書き込み

データの更新

セカンダリ インデックスを使用する

セカンダリ インデックスを追加する

コマンドラインから

Ruby 用 Spanner クライアント ライブラリの使用

インデックスを使用して読み取る

インデックス限定の読み取り用インデックスを追加する

コマンドラインを使用する

GoogleSQL

PostgreSQL

Ruby 用 Spanner クライアント ライブラリの使用

読み取り専用トランザクションを使用したデータの取得

クリーンアップする

データベースを削除する

コマンドラインから

Google Cloud コンソールの使用

インスタンスの削除

コマンドラインから

Google Cloud コンソールの使用

次のステップ

Ruby で Spanner を使ってみる

サンプルファイルを確認する

データベースクライアントを作成する

Ruby 用 Spanner クライアントライブラリを使用する

データベーススキーマを更新する

Ruby 用 Spanner クライアントライブラリを使用する

セカンダリインデックスを使用する

セカンダリインデックスを追加する

Ruby 用 Spanner クライアントライブラリの使用

Ruby 用 Spanner クライアントライブラリの使用