Menghubungkan ke Spanner menggunakan Cassandra Adapter

Halaman ini menjelaskan Cassandra Adapter dan menjelaskan cara menggunakan dan menghubungkan Spanner dari Cassandra Adapter.

Cassandra Adapter dirancang untuk berjalan di mesin yang sama dengan aplikasi Anda. Adaptor mengekspos endpoint di localhost yang mendukung protokol wire Cassandra Query Language (CQL). Layanan ini menerjemahkan protokol wire CQL ke gRPC, yaitu protokol wire Spanner. Dengan proxy ini yang berjalan secara lokal, klien Cassandra dapat terhubung ke database Spanner.

Anda dapat memulai Cassandra Adapter dengan cara berikut:

  • Dalam proses dengan aplikasi Go Anda
  • Dalam proses dengan aplikasi Java Anda
  • Sebagai proses mandiri
  • Dalam container Docker

Sebelum memulai

Sebelum memulai Cassandra Adapter, pastikan Anda telah melakukan autentikasi dengan akun pengguna atau akun layanan di mesin tempat Cassandra Adapter akan berjalan. Jika Anda menggunakan akun layanan, Anda harus mengetahui lokasi file kunci JSON (file kredensial). Anda menetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS untuk menentukan jalur kredensial.

Untuk informasi selengkapnya, lihat:

Menghubungkan Cassandra Adapter ke aplikasi Anda

Adaptor Cassandra memerlukan informasi berikut:

  • Nama project
  • Nama instance Spanner
  • Database yang akan dihubungkan

Jika menggunakan Docker, Anda memerlukan jalur untuk file kredensial berformat JSON (file kunci).

Dalam proses Java

  1. Jika Anda menggunakan akun layanan untuk autentikasi, pastikan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS ditetapkan ke jalur file kredensial.

  2. Untuk aplikasi Java, Anda dapat menautkan Cassandra Adapter ke aplikasi secara langsung dengan menambahkan google-cloud-spanner-cassandra sebagai dependensi ke project Anda.

Untuk Maven, tambahkan dependensi baru berikut di bagian <dependencies>: 

<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-spanner-cassandra</artifactId>
    <version>0.4.0</version>
</dependency>

Untuk Gradle, tambahkan kode berikut: 

dependencies {
    implementation 'com.google.cloud:google-cloud-spanner-cassandra:0.4.0'
}

  1. Ubah kode pembuatan CqlSession. Daripada menggunakan CqlSessionBuilder, gunakan SpannerCqlSessionBuilder dan berikan URI database Spanner: 
    
import com.datastax.oss.driver.api.core.CqlSession;
import com.datastax.oss.driver.api.core.config.DefaultDriverOption;
import com.datastax.oss.driver.api.core.config.DriverConfigLoader;
import com.datastax.oss.driver.api.core.cql.ResultSet;
import com.datastax.oss.driver.api.core.cql.Row;
import com.google.cloud.spanner.adapter.SpannerCqlSession;
import java.net.InetSocketAddress;
import java.time.Duration;
import java.util.Random;

// This sample assumes your spanner database <my_db> contains a table <users>
// with the following schema:

// CREATE TABLE users (
//  id        INT64          OPTIONS (cassandra_type = 'int'),
//  active    BOOL           OPTIONS (cassandra_type = 'boolean'),
//  username  STRING(MAX)    OPTIONS (cassandra_type = 'text'),
// ) PRIMARY KEY (id);

class QuickStartSample {

  public static void main(String[] args) {

    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "my-gcp-project";
    final String instanceId = "my-spanner-instance";
    final String databaseId = "my_db";

    final String databaseUri =
        String.format("projects/%s/instances/%s/databases/%s", projectId, instanceId, databaseId);

    try (CqlSession session =
        SpannerCqlSession.builder() // `SpannerCqlSession` instead of `CqlSession`
            .setDatabaseUri(databaseUri) // Set spanner database URI.
            .addContactPoint(new InetSocketAddress("localhost", 9042))
            .withLocalDatacenter("datacenter1")
            .withKeyspace(databaseId) // Keyspace name should be the same as spanner database name
            .withConfigLoader(
                DriverConfigLoader.programmaticBuilder()
                    .withString(DefaultDriverOption.PROTOCOL_VERSION, "V4")
                    .withDuration(
                        DefaultDriverOption.CONNECTION_INIT_QUERY_TIMEOUT, Duration.ofSeconds(5))
                    .build())
            .build()) {

      final int randomUserId = new Random().nextInt(Integer.MAX_VALUE);

      System.out.printf("Inserting user with ID: %d%n", randomUserId);

      // INSERT data
      session.execute(
          "INSERT INTO users (id, active, username) VALUES (?, ?, ?)",
          randomUserId,
          true,
          "John Doe");

      System.out.printf("Successfully inserted user: %d%n", randomUserId);
      System.out.printf("Querying user: %d%n", randomUserId);

      // SELECT data
      ResultSet rs =
          session.execute("SELECT id, active, username FROM users WHERE id = ?", randomUserId);

      // Get the first row from the result set
      Row row = rs.one();

      System.out.printf(
          "%d %b %s%n", row.getInt("id"), row.getBoolean("active"), row.getString("username"));

    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

Beralih ke dalam proses

Untuk aplikasi Go, Anda perlu melakukan perubahan satu baris pada file inisialisasi cluster untuk mengintegrasikan klien Go Spanner Cassandra. Kemudian, Anda dapat menautkan Cassandra Adapter ke aplikasi secara langsung.

  1. Impor paket spanner adapter dari klien Go Spanner Cassandra di aplikasi Go Anda.
import spanner "github.com/googleapis/go-spanner-cassandra/cassandra/gocql"
  1. Ubah kode pembuatan cluster Anda untuk menggunakan spanner.NewCluster, bukan gocql.NewCluster, dan berikan URI database Spanner: 
    import (
	"fmt"
	"io"
	"math"
	"math/rand/v2"
	"time"

	spanner "github.com/googleapis/go-spanner-cassandra/cassandra/gocql"
)

// This sample assumes your spanner database <your_db> contains a table <users>
// with the following schema:
//
// CREATE TABLE users (
//	id   	 	INT64          OPTIONS (cassandra_type = 'int'),
//	active    	BOOL           OPTIONS (cassandra_type = 'boolean'),
//	username  	STRING(MAX)    OPTIONS (cassandra_type = 'text'),
// ) PRIMARY KEY (id);

func quickStart(databaseURI string, w io.Writer) error {
	opts := &spanner.Options{
		DatabaseUri: databaseURI,
	}
	cluster := spanner.NewCluster(opts)
	if cluster == nil {
		return fmt.Errorf("failed to create cluster")
	}
	defer spanner.CloseCluster(cluster)

	// You can still configure your cluster as usual after connecting to your
	// spanner database
	cluster.Timeout = 5 * time.Second
	cluster.Keyspace = "your_db_name"

	session, err := cluster.CreateSession()

	if err != nil {
		return err
	}

	randomUserId := rand.IntN(math.MaxInt32)
	if err = session.Query("INSERT INTO users (id, active, username) VALUES (?, ?, ?)",
			       randomUserId, true, "John Doe").
		Exec(); err != nil {
		return err
	}

	var id int
	var active bool
	var username string
	if err = session.Query("SELECT id, active, username FROM users WHERE id = ?",
			       randomUserId).
		Scan(&id, &active, &username); err != nil {
		return err
	}
	fmt.Fprintf(w, "%d %v %s\n", id, active, username)
	return nil
}

Anda dapat mengonfigurasi cluster seperti biasa setelah terhubung ke database Spanner.

Mandiri

  1. Meng-cloning repository
git clone https://github.com/googleapis/go-spanner-cassandra.git
cd go-spanner-cassandra
  1. Jalankan cassandra_launcher.go dengan flag -db yang diperlukan:
go run cassandra_launcher.go \
-db "projects/my_project/instances/my_instance/databases/my_database"
  1. Ganti -db dengan URI database Spanner Anda.

Docker

Mulai Cassandra Adapter dengan perintah berikut.

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json
docker run -d -p 9042:9042 \
-e GOOGLE_APPLICATION_CREDENTIALS \
-v ${GOOGLE_APPLICATION_CREDENTIALS}:${GOOGLE_APPLICATION_CREDENTIALS}:ro \
gcr.io/cloud-spanner-adapter/cassandra-adapter \
-db DATABASE_URI

Daftar berikut berisi opsi startup yang paling sering digunakan untuk Spanner Cassandra Adapter:

  • -db <DatabaseUri>

URI database Spanner (wajib). Tindakan ini menentukan database Spanner yang terhubung ke klien. Misalnya, projects/YOUR_PROJECT/instances/YOUR_INSTANCE/databases/YOUR_DATABASE.

  • -tcp <TCPEndpoint>

Alamat pendengar proxy klien. Ini menentukan endpoint TCP tempat klien memproses koneksi klien Cassandra yang masuk. Default:localhost:9042

  • -grpc-channels <NumGrpcChannels>

Jumlah channel gRPC yang akan digunakan saat terhubung ke Spanner. Default: 4

Misalnya, perintah berikut memulai Cassandra Adapter di port 9042 menggunakan kredensial aplikasi, dan menghubungkan adapter ke database projects/my_project/instances/my_instance/databases/my_database:

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json
docker run -d -p 9042:9042 \
-e GOOGLE_APPLICATION_CREDENTIALS \
-v ${GOOGLE_APPLICATION_CREDENTIALS}:${GOOGLE_APPLICATION_CREDENTIALS}:ro \
gcr.io/cloud-spanner-adapter/cassandra-adapter \
-db projects/my_project/instances/my_instance/databases/my_database

Rekomendasi

Rekomendasi berikut membantu Anda meningkatkan kualitas pengalaman dengan Cassandra Adapter. Rekomendasi ini berfokus pada Java, khususnya driver klien Cassandra untuk Java versi 4.

Meningkatkan waktu tunggu permintaan

Waktu tunggu permintaan lima detik atau lebih memberikan pengalaman yang lebih baik dengan Cassandra Adapter daripada nilai default dua detik.

# Sample application.conf: increases request timeout to five seconds
datastax-java-driver {
  basic {
    request {
      timeout = 5 seconds
    }
  }
}

Menyesuaikan penggabungan koneksi

Konfigurasi default untuk jumlah koneksi maksimum dan permintaan serentak maksimum per koneksi atau host sesuai untuk lingkungan pengembangan, pengujian, dan produksi atau penyiapan dengan volume rendah. Namun, sebaiknya Anda meningkatkan nilai ini, karena Cassandra Adapter menyamar sebagai node tunggal, tidak seperti kumpulan node dalam cluster Cassandra.

Meningkatkan nilai ini memungkinkan lebih banyak koneksi serentak antara klien dan Cassandra Interface. Hal ini dapat mencegah kehabisan kumpulan koneksi saat beban berat.

# Sample application.conf: increases maximum number of requests that can be
# executed concurrently on a connection
advanced.connection {
  max-requests-per-connection = 32000
  pool {
    local.size = 10
  }
}

Menyesuaikan saluran gRPC

Channel gRPC digunakan oleh klien Spanner untuk komunikasi. Satu channel gRPC kira-kira setara dengan koneksi TCP. Satu channel gRPC dapat menangani hingga 100 permintaan serentak. Artinya, aplikasi akan memerlukan setidaknya sebanyak saluran gRPC seperti jumlah permintaan serentak yang akan dijalankan aplikasi, dibagi dengan 100.

Menonaktifkan perutean yang mendukung token

Driver yang menggunakan load balancing yang mendukung token mungkin mencetak peringatan atau mungkin tidak berfungsi saat menggunakan Cassandra Adapter. Karena Cassandra Adapter menyamar sebagai satu node, Cassandra Adapter tidak selalu berfungsi dengan baik dengan driver yang mendukung token yang mengharapkan setidaknya ada sejumlah node faktor replikasi dalam cluster. Beberapa driver mungkin mencetak peringatan (yang dapat diabaikan) dan melakukan penggantian ke sesuatu seperti kebijakan penyeimbangan round-robin, sementara driver lain mungkin gagal dengan error. Untuk driver yang gagal dengan error, Anda harus menonaktifkan fitur sadar token atau mengonfigurasi kebijakan load balancing round-robin.

# Sample application.conf: disables token-aware routing
metadata {
  token-map {
    enabled = false
  }
}

Menyematkan versi protokol ke V4

Cassandra Adapter kompatibel dengan driver klien Apache Cassandra open source yang sesuai dengan protokol wire biner CQL v4. Pastikan untuk menyematkan PROTOCOL_VERSION ke V4, atau Anda mungkin melihat error koneksi.

# Sample application.conf: overrides protocol version to V4
datastax-java-driver {
  advanced.protocol.version = V4
}

Langkah berikutnya