Mengemulasi Spanner secara lokal

gcloud CLI menyediakan emulator lokal dalam memori, yang dapat Anda gunakan untuk mengembangkan dan menguji aplikasi dengan instance uji coba gratis tanpa membuat project Google Cloud atau akun penagihan. Karena emulator hanya menyimpan data dalam memori, semua status, termasuk data, skema, dan konfigurasi, akan hilang saat dimulai ulang. Emulator menawarkan API yang sama dengan layanan produksi Spanner dan ditujukan untuk pengembangan dan pengujian lokal, bukan untuk deployment produksi.

Emulator mendukung dialek GoogleSQL dan PostgreSQL. Library 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, izin, atau peran.
  • Dalam mode kueri PLAN atau PROFILE, paket kueri yang ditampilkan kosong.
  • Pernyataan ANALYZE. Emulator menerima, tetapi mengabaikannya.
  • Salah satu alat pemantauan dan pencatatan log audit.

Emulator juga berbeda dengan layanan produksi Spanner dengan cara berikut:

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

Untuk mengetahui daftar lengkap API dan fitur yang didukung, tidak didukung, dan sebagian didukung, 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.

Menyiapkan emulator untuk gcloud CLI

Untuk pengguna Windows dan macOS, sebelum menginstal emulator, lakukan hal berikut:

  • Instal komponen gcloud CLI di workstation Anda:

    gcloud components install

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

    gcloud components update

Membuat dan mengonfigurasi emulator menggunakan gcloud CLI

Untuk menggunakan emulator dengan gcloud CLI, Anda harus menonaktifkan autentikasi dan mengganti endpoint. Sebaiknya buat konfigurasi gcloud CLI terpisah agar Anda dapat 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/

    Setelah dikonfigurasi, perintah gcloud CLI Anda akan dikirim ke emulator, bukan layanan produksi. Anda dapat memverifikasinya dengan membuat instance dengan konfigurasi instance emulator:

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

    Untuk beralih antara emulator dan konfigurasi default, jalankan:

    gcloud config configurations activate [emulator | default]

  2. Mulai emulator menggunakan gcloud CLI.

Menginstal emulator di 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 dalam penampung ke port yang sama di host lokal Anda. Emulator menggunakan dua endpoint lokal: localhost:9010 untuk permintaan gRPC dan localhost:9020 untuk permintaan REST.

  4. Mulai emulator menggunakan gcloud CLI.

Memulai emulator menggunakan gcloud CLI

Mulai emulator menggunakan perintah gcloud emulators spanner:

gcloud emulators spanner start

Emulator menggunakan dua endpoint lokal:

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

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 dimulai, library klien akan otomatis memeriksa SPANNER_EMULATOR_HOST dan terhubung ke emulator jika sedang berjalan.

Setelah SPANNER_EMULATOR_HOST ditetapkan, Anda dapat menguji emulator dengan mengikuti panduan Memulai. Abaikan petunjuk yang terkait dengan pembuatan project, autentikasi, dan kredensial karena hal ini 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#, Anda juga harus menentukan opsi emulatordetection di string koneksi. Tidak seperti library klien lainnya, C# mengabaikan variabel lingkungan SPANNER_EMULATOR_HOST secara default. Berikut adalah contoh untuk string koneksi:

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