Mengemulasi Spanner secara lokal

gcloud CLI menyediakan emulator dalam memori lokal untuk mengembangkan dan menguji aplikasi Anda. Karena emulator hanya menyimpan data dalam memori, emulator akan kehilangan semua status, termasuk data, skema, dan konfigurasi, saat dimulai ulang. Emulator menawarkan API yang sama dengan layanan produksi Spanner dan melayani pengembangan dan pengujian lokal, bukan deployment produksi.

Emulator mendukung dialek GoogleSQL dan PostgreSQL. API ini mendukung semua bahasa library klien. Anda juga dapat menggunakan emulator dengan Google Cloud CLI dan REST API.

Emulator juga tersedia sebagai project open source di GitHub.

Batasan dan perbedaan

Emulator tidak mendukung hal berikut:

  • TLS/HTTPS, autentikasi, Identity and Access Management (IAM), izin, atau peran.
  • Dalam mode kueri PLAN atau PROFILE, rencana kueri yang ditampilkan kosong.
  • Pernyataan ANALYZE. Emulator menerima, tetapi mengabaikannya.
  • Salah satu alat pemantauan dan logging audit.
  • Perlindungan penghapusan database. Emulator menerima kolom enable_drop_protection, tetapi emulator mengizinkan database dihapus meskipun properti ini diaktifkan.

Emulator juga berbeda dengan layanan produksi Spanner dalam hal berikut:

  • Pesan error mungkin berbeda antara emulator dan layanan produksi.
  • Performa dan skalabilitas emulator tidak sebanding dengan layanan produksi.
  • Transaksi baca-tulis dan perubahan skema mengunci seluruh database untuk akses eksklusif hingga selesai.
  • Emulator mendukung DML yang Dipartisi dan partitionQuery, tetapi tidak memverifikasi bahwa pernyataan dapat dipartisi. Artinya, pernyataan DML yang dipartisi atau partitionQuery dapat berjalan di emulator, tetapi gagal di layanan produksi dengan error pernyataan yang tidak dapat dipartisi.

Untuk mengetahui daftar lengkap API dan fitur yang didukung, tidak didukung, dan didukung sebagian, lihat file README di GitHub.

Opsi untuk menjalankan emulator

Ada dua cara umum untuk menjalankan emulator:

Pilih cara yang sesuai untuk pengembangan aplikasi dan alur kerja pengujian Anda.

Menjalankan emulator menggunakan gcloud CLI

Untuk menjalankan emulator menggunakan Google Cloud CLI:

  1. Instal komponen cloud-spanner-emulator:

    gcloud components install cloud-spanner-emulator

    Jika gcloud CLI sudah diinstal, jalankan perintah berikut untuk memastikan semua komponennya diupdate:

    gcloud components update

  2. Mulai emulator:

    gcloud emulators spanner start

    Emulator menggunakan dua endpoint lokal:

    • localhost:9010 untuk permintaan gRPC
    • localhost:9020 untuk permintaan REST

Menjalankan emulator menggunakan Docker

Untuk menjalankan emulator menggunakan Docker:

  1. Instal Docker di sistem Anda dan sediakan di jalur sistem.

  2. Dapatkan image emulator terbaru:

    docker pull gcr.io/cloud-spanner-emulator/emulator

  3. Jalankan emulator di Docker:

    docker run -p 9010:9010 -p 9020:9020 gcr.io/cloud-spanner-emulator/emulator

    Perintah ini menjalankan emulator dan memetakan port di container ke port yang sama di host lokal Anda. Emulator menggunakan dua endpoint lokal: localhost:9010 untuk permintaan gRPC dan localhost:9020 untuk permintaan REST.

Mengonfigurasi gcloud CLI untuk menggunakan emulator

Untuk menggunakan emulator dengan gcloud CLI, nonaktifkan autentikasi dan ganti endpoint. Buat konfigurasi gcloud CLI terpisah untuk beralih dengan cepat antara emulator dan layanan produksi.

  1. Buat dan aktifkan konfigurasi emulator:

    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/

  2. Setelah dikonfigurasi, gcloud CLI akan mengirimkan perintah Anda ke emulator, bukan layanan produksi. Verifikasi ini dengan membuat instance dengan konfigurasi instance emulator:

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

Konfigurasi peralihan

Untuk beralih antara emulator dan konfigurasi default, jalankan:

# To switch to default (production) configuration:
gcloud config configurations activate default

# To switch back to emulator configuration:
gcloud config configurations activate emulator

Menggunakan library klien dengan emulator

Anda dapat menggunakan versi yang didukung dari library klien dengan emulator dengan menetapkan variabel lingkungan SPANNER_EMULATOR_HOST. Ada banyak cara untuk melakukannya. Contoh:

Linux/macOS

export SPANNER_EMULATOR_HOST=localhost:9010

Windows

set SPANNER_EMULATOR_HOST=localhost:9010

Atau dengan gcloud env-init:

Linux/macOS

$(gcloud emulators spanner env-init)

Windows

gcloud emulators spanner env-init > set_vars.cmd && set_vars.cmd

Saat aplikasi Anda dimulai, library klien akan otomatis memeriksa SPANNER_EMULATOR_HOST dan terhubung ke emulator jika sedang berjalan.

Setelah SPANNER_EMULATOR_HOST disetel, Anda dapat menguji emulator dengan mengikuti panduan Memulai. Abaikan petunjuk terkait pembuatan project, autentikasi, dan kredensial karena tidak diperlukan untuk menggunakan emulator.

Versi yang didukung

Tabel berikut mencantumkan versi library klien yang mendukung emulator.

Library klien Versi minimum
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+

Petunjuk tambahan untuk C

Untuk library klien C#, tentukan opsi emulatordetection di string koneksi. Tidak seperti library klien lainnya, C# mengabaikan variabel lingkungan SPANNER_EMULATOR_HOST secara default. Contoh berikut menunjukkan string koneksi:

var builder = new SpannerConnectionStringBuilder
{
    DataSource = $"projects/{projectId}/instances/{instanceId}/databases/{databaseId}",
    EmulatorDetection = "EmulatorOnly"
};