Membuat dan mengkueri database menggunakan gcloud CLI

Tujuan

Tutorial ini memandu Anda melakukan langkah-langkah berikut menggunakan alat command line gcloud.

• Membuat instance, database, dan skema Spanner
• Menulis data ke database dan mengeksekusi kueri SQL terhadap data tersebut
• Membersihkan dengan menghapus database dan instance

Untuk referensi gcloud spanner lengkap, lihat gcloud spanner.

Catatan: Untuk menjelajahi Spanner menggunakan instance uji coba gratis 90 hari, lihat Membuat instance uji coba gratis Spanner.

Harga

Tutorial ini menggunakan Spanner, yang merupakan komponen Google Cloud yang dapat ditagih. Untuk mengetahui informasi tentang biaya penggunaan Spanner, lihat Harga.

Sebelum memulai

1. Selesaikan langkah-langkah yang dijelaskan dalam artikel Menginstal gcloud CLI dan menyiapkan Cloud Spanner API, yang mencakup pembuatan dan penetapan project Google Cloud default, mengaktifkan penagihan, mengaktifkan Cloud Spanner API, dan menyiapkan OAuth 2.0 guna mendapatkan kredensial autentikasi untuk menggunakan Cloud Spanner API.

Secara khusus, pastikan Anda menjalankan gcloud auth application-default login untuk menyiapkan lingkungan pengembangan lokal dengan kredensial autentikasi.

Menetapkan project default

Jika belum melakukannya, tetapkan ID project Google Cloud sebagai project default untuk Google Cloud CLI:

gcloud config set project PROJECT_ID

Jika tidak menetapkan project default, Anda harus meneruskan --project PROJECT_ID ke setiap perintah di bawah sebagai argumen pertama ke gcloud spanner. Contoh:

gcloud spanner --project=PROJECT_ID instance-configs list

Instance

Saat pertama kali menggunakan Spanner, Anda harus membuat instance, yang merupakan alokasi resource yang digunakan oleh database Spanner. Saat membuat instance, Anda memilih tempat data akan disimpan dan berapa banyak kapasitas komputasi yang dimiliki instance tersebut.

Instance dan konfigurasi instance

Untuk membuat instance, Anda harus memilih konfigurasi instance, yang seperti cetak biru untuk instance Anda yang menentukan penempatan geografis dan replikasi data Spanner Anda.

Membuat daftar konfigurasi instance

Saat membuat instance, Anda menetapkan konfigurasi instance, yang menentukan penempatan geografis dan replikasi database Anda di instance tersebut. Anda dapat memilih konfigurasi regional, yang menyimpan data di satu region, atau konfigurasi multi-region, yang mendistribusikan data di beberapa region. Pelajari lebih lanjut di Instance.

Untuk melihat rangkaian konfigurasi instance yang tersedia untuk project Anda:

gcloud spanner instance-configs list

Anda akan melihat daftar konfigurasi regional dan multi-region.

Konfigurasi regional mendistribusikan data dalam satu region, sementara konfigurasi multi-region mendistribusikan data secara geografis di beberapa region. Baca selengkapnya tentang hal ini di Instance.

Membuat instance

Untuk membuat instance bernama test-instance dengan nama tampilan My Instance menggunakan konfigurasi instance regional regional-us-central1 dengan 1 node:

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

Pada perintah di atas, nama instance disetel ke test-instance dan --description menetapkan nama tampilan instance. Kedua nilai ini harus unik dalam sebuah project Google Cloud Platform.

Catatan: Gunakan ID instance, bukan nama tampilan, saat merujuk ke instance dalam perintah gcloud spanner.

Menetapkan instance default

Anda dapat menetapkan instance default yang digunakan Spanner jika belum menentukan instance dalam perintah. Untuk menetapkan instance default:

gcloud config set spanner/instance test-instance

Buat database

Buat database bernama example-db. Dialek database secara default disetel ke GoogleSQL.

GoogleSQL

gcloud spanner databases create example-db

PostgreSQL

gcloud spanner databases create example-db --database-dialect=POSTGRESQL

Memperbarui skema

Gunakan Data Definition Language (DDL) Spanner untuk membuat, mengubah, atau menghapus tabel, dan untuk membuat atau menghapus indeks.

Mari kita buat dua tabel:

GoogleSQL

gcloud spanner databases ddl update example-db \
--ddl='CREATE TABLE Singers ( SingerId INT64 NOT NULL, FirstName STRING(1024), LastName STRING(1024), SingerInfo BYTES(MAX) ) PRIMARY KEY (SingerId)'

gcloud spanner databases ddl update example-db \
--ddl='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'

PostgreSQL

gcloud spanner databases ddl update example-db \
--ddl='CREATE TABLE Singers ( SingerId bigint NOT NULL, FirstName varchar(1024), LastName varchar(1024), SingerInfo bytea, PRIMARY KEY (SingerId) )'

gcloud spanner databases ddl update example-db \
--ddl='CREATE TABLE Albums ( SingerId bigint NOT NULL, AlbumId bigint NOT NULL, AlbumTitle varchar, PRIMARY KEY (SingerId, AlbumId) ) INTERLEAVE IN PARENT Singers ON DELETE CASCADE'

Untuk memeriksa progres operasi, gunakan gcloud spanner operations describe. Perintah ini memerlukan ID operasi.

Dapatkan ID operasi:

gcloud spanner operations list --instance="test-instance" \
--database=DATABASE-NAME --type=DATABASE_UPDATE_DDL

Ganti DATABASE-NAME dengan nama database.

Jalankan gcloud spanner operations describe:

gcloud spanner operations describe \
  --instance="test-instance" \
  --database="example-db" \
  projects/PROJECT-NAME/instances/test-instance/databases/example-db/operations/OPERATION-ID

Ganti kode berikut:

• PROJECT-NAME: Nama project.
• OPERATION-ID: ID operasi dari operasi yang ingin Anda periksa.

Outputnya terlihat mirip dengan yang berikut ini:

done: true
metadata:
...
progress:
- endTime: '2022-03-01T00:28:06.691403Z'
  progressPercent: 100
  startTime: '2022-03-01T00:28:04.221401Z'
- endTime: '2022-03-01T00:28:17.624588Z'
  startTime: '2022-03-01T00:28:06.691403Z'
  progressPercent: 100
...

Menulis data

Mari tambahkan beberapa data sampel ke {i>database<i}

GoogleSQL

gcloud spanner rows insert --database=example-db \
  --table=Singers \
  --data=SingerId=1,FirstName=Marc,LastName=Richards

gcloud spanner rows insert --database=example-db \
  --table=Singers \
  --data=SingerId=2,FirstName=Catalina,LastName=Smith

gcloud spanner rows insert --database=example-db \
  --table=Singers \
  --data=SingerId=3,FirstName=Alice,LastName=Trentor

gcloud spanner rows insert --database=example-db \
  --table=Albums \
  --data=SingerId=1,AlbumId=1,AlbumTitle="Total Junk"

gcloud spanner rows insert --database=example-db \
  --table=Albums \
  --data=SingerId=2,AlbumId=1,AlbumTitle="Green"

gcloud spanner rows insert --database=example-db \
  --table=Albums \
  --data=^:^SingerId=2:AlbumId=2:AlbumTitle="Go, Go, Go"

Secara default, koma digunakan untuk membatasi item dalam daftar. Dalam perintah penyisipan terakhir, kita menentukan titik dua (^:^) sebagai pembatas sehingga kita dapat menggunakan koma dalam judul album.

PostgreSQL

Catatan: Ada masalah umum ketika gcloud CLI tidak dapat mencari nama tabel saat menggunakan mutasi untuk menulis data ke database PostgreSQL. Oleh karena itu, Anda harus menggunakan DML untuk menyisipkan data.

gcloud spanner databases execute-sql example-db \
  --sql="INSERT INTO Singers (SingerId, FirstName, LastName) VALUES (1, 'Marc', 'Richards')"

gcloud spanner databases execute-sql example-db \
  --sql="INSERT INTO Singers (SingerId, FirstName, LastName) VALUES (2, 'Catalina', 'Smith')"

gcloud spanner databases execute-sql example-db   \
  --sql="INSERT INTO Singers (SingerId, FirstName, LastName) VALUES (3, 'Alice', 'Trentor')"

gcloud spanner databases execute-sql example-db   \
  --sql="INSERT INTO Albums (SingerId, AlbumId, AlbumTitle) VALUES (1, 1, 'Total Junk')"

gcloud spanner databases execute-sql example-db   \
  --sql="INSERT INTO Albums (SingerId, AlbumId, AlbumTitle) VALUES (2, 1, 'Green')"

gcloud spanner databases execute-sql example-db   \
  --sql="INSERT INTO Albums (SingerId, AlbumId, AlbumTitle) VALUES (2, 2, 'Go, Go, Go')"

Membuat kueri data menggunakan SQL

Jalankan kueri pada command line:

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

Untuk referensi SQL Spanner, lihat Sintaksis kueri untuk GoogleSQL atau Sintaksis kueri untuk PostgreSQL.

Untuk melihat daftar flag yang dapat Anda gunakan dengan perintah execute-sql, lihat gcloud spanner databaseexecute-sql.

Pembersihan

Agar tidak menimbulkan biaya tambahan pada akun Google Cloud Anda untuk resource yang digunakan dalam tutorial ini, hapus database dan hapus instance yang Anda buat.

Melepas database

Untuk menghapus instance yang ada:

gcloud spanner databases delete example-db

Menghapus instance

Untuk menghapus instance yang ada:

gcloud spanner instances delete test-instance

Perhatikan bahwa dengan menghapus instance, semua database dalam instance tersebut juga akan dihapus. Penghapusan instance tidak dapat dibatalkan.