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. Adapter ini mengekspos endpoint di localhost yang mendukung protokol wire Cassandra Query Language (CQL). Adapter ini menerjemahkan protokol wire CQL ke gRPC, protokol wire Spanner. Dengan proxy ini 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 diautentikasi dengan akun pengguna atau akun layanan di mesin tempat Cassandra Adapter akan berjalan. Jika menggunakan akun layanan, Anda harus mengetahui lokasi file kunci JSON (file kredensial). Anda menetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS untuk menentukan jalur kredensial. Sebelum memulai Cassandra Adapter, pastikan Anda telah diautentikasi dengan akun pengguna atau akun layanan di mesin tempat Cassandra Adapter akan berjalan. Jika 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

Cassandra Adapter memerlukan informasi berikut:

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

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

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>1.1.0</version>
</dependency>

Untuk Gradle, tambahkan kode berikut: 

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

  1. Ubah kode pembuatan CqlSession Anda. 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();
    }
  }
}

Dalam proses Go

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

  1. Impor paket spanner adapter dari klien Spanner Cassandra Go 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. Buat clone repositori:
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). URI ini menentukan database Spanner yang terhubung dengan klien. Misalnya, projects/YOUR_PROJECT/instances/YOUR_INSTANCE/databases/YOUR_DATABASE.

  • -tcp <TCPEndpoint>

Alamat pemroses proxy klien. Alamat ini menentukan endpoint TCP tempat klien mendengarkan koneksi klien Cassandra yang masuk. Default:localhost:9042

  • -grpc-channels <NumGrpcChannels>

Jumlah saluran 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 pengalaman dengan Cassandra Adapter. Rekomendasi ini berfokus pada Java, khususnya driver klien Cassandra untuk Java versi 4.

Meningkatkan waktu tunggu permintaan

Waktu tunggu permintaan selama 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 staging volume rendah. Namun, sebaiknya Anda meningkatkan nilai ini, karena Cassandra Adapter menyamar sebagai satu node, 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

Saluran gRPC digunakan oleh klien Spanner untuk komunikasi. Satu saluran gRPC kira-kira setara dengan koneksi TCP. Satu saluran gRPC dapat menangani hingga 100 permintaan serentak. Artinya, aplikasi akan memerlukan setidaknya saluran gRPC sebanyak jumlah permintaan serentak yang akan dieksekusi aplikasi, dibagi 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 jumlah node faktor replikasi dalam cluster. Beberapa driver mungkin mencetak peringatan (yang dapat diabaikan) dan kembali ke sesuatu seperti kebijakan load balancing round-robin, sementara driver lain mungkin gagal dengan error. Untuk driver yang gagal dengan error, Anda harus menonaktifkan yang mendukung 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 CQL Binary v4 protocol. Pastikan untuk menyematkan PROTOCOL_VERSION ke V4, jika tidak, Anda mungkin akan melihat error koneksi.

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

Langkah berikutnya