Emulasikan Spanner secara lokal

Gcloud CLI menyediakan emulator lokal dalam memori yang dapat Anda gunakan untuk mengembangkan dan menguji aplikasi secara 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. SDK 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, IAM, izin, atau peran.
  • Mode kueri PLAN atau PROFILE. Hanya mendukung NORMAL.
  • Pernyataan ANALYZE. Emulator menerima, tetapi mengabaikannya.
  • Semua alat pemantauan dan logging audit.

Emulator juga berbeda dari layanan produksi Spanner dalam hal berikut:

  • Pesan error mungkin tidak konsisten antara emulator dan layanan produksi.
  • Performa dan skalabilitas untuk emulator tidak dapat dibandingkan dengan layanan produksi.
  • Transaksi baca-tulis dan perubahan skema akan mengunci seluruh database untuk akses eksklusif hingga transaksi selesai.
  • DML yang Dipartisi dan Kueri Partisi didukung, tetapi emulator tidak memeriksa untuk memastikan bahwa pernyataan dapat dipartisi. Artinya, pernyataan Kueri Partisi atau DML Terpartisi mungkin berjalan di emulator, tetapi mungkin gagal dalam 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.

Menginstal dan menjalankan emulator

Dua cara paling umum untuk menjalankan emulator adalah dengan menggunakan gcloud CLI dan Docker. Anda dapat memilih cara yang sesuai untuk pengembangan aplikasi dan alur kerja pengujian.

gcloud CLI

  1. Instal gcloud CLI.

  2. Untuk pengguna Windows dan MacOS, emulator harus diinstal di sistem Anda dan Docker tersedia di jalur sistem.

  3. Update gcloud untuk mendapatkan versi terbaru:

    gcloud components update

  4. Mulai emulator:

    gcloud emulators spanner start

    Jika emulator belum diinstal, Anda akan diminta untuk mendownload dan menginstal biner untuk emulator.

    Secara default, emulator menghosting dua endpoint lokal: localhost:9010 untuk permintaan gRPC dan localhost:9020 untuk permintaan REST.

    Untuk mengetahui detail selengkapnya tentang perintah ini, baca gcloud emulators spanner.

Docker

  1. Pastikan Docker diinstal di sistem Anda dan tersedia di jalur sistem.

  2. Mendapatkan image emulator terbaru:

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

  3. Mulai emulator:

    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. Anda akan memiliki dua endpoint lokal: localhost:9010 untuk permintaan gRPC dan localhost:9020 untuk permintaan REST.

Menggunakan gcloud CLI dengan emulator

Untuk menggunakan emulator dengan gcloud, Anda harus menonaktifkan autentikasi dan mengganti endpoint.

Sebaiknya buat konfigurasi gcloud terpisah, sehingga Anda dapat beralih dengan cepat antara emulator dan layanan produksi dengan cepat. Untuk membuat dan mengaktifkan konfigurasi emulator, jalankan:

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 Anda akan dikirim ke emulator, bukan ke layanan produksi. Anda dapat memverifikasi hal ini dengan membuat instance menggunakan 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]

Menggunakan library klien dengan emulator

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

Linux / Mac

export SPANNER_EMULATOR_HOST=localhost:9010

Windows

set SPANNER_EMULATOR_HOST=localhost:9010

Atau dengan gcloud env-init:

Linux / Mac

$(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 ditetapkan, Anda dapat menguji emulator dengan mengikuti Panduan Memulai di bawah. Anda dapat mengabaikan petunjuk yang terkait dengan pembuatan, autentikasi, dan kredensial project 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 dan yang lebih baru
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 dalam string koneksi. Tidak seperti library klien lainnya, C# mengabaikan variabel lingkungan SPANNER_EMULATOR_HOST secara default. Berikut cara melakukannya:

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