התחברות ל-Spanner באמצעות Cassandra Adapter

בדף הזה מתואר ה-Cassandra Adapter ומוסבר איך להשתמש בו כדי להתחבר ל-Spanner.

המתאם של Cassandra מיועד לפעול באותה מכונה שבה פועלת האפליקציה. המתאם חושף נקודת קצה ב-localhost שתומכת בפרוטוקול התקשורת של שפת השאילתות של Cassandra ‏ (CQL). הוא מתרגם את פרוטוקול התקשורת של CQL ל-gRPC, פרוטוקול התקשורת של Spanner. כשהפרוקסי הזה פועל באופן מקומי, לקוח של Cassandra יכול להתחבר למסד נתונים של Spanner.

אפשר להפעיל את Cassandra Adapter בדרכים הבאות:

  • הבקשה שלך ל-Go נמצאת בתהליך
  • בתוך התהליך באפליקציית Java
  • כתהליך עצמאי
  • בקונטיינר Docker

לפני שמתחילים

לפני שמפעילים את Cassandra Adapter, צריך לוודא שעברתם אימות באמצעות חשבון משתמש או חשבון שירות במחשב שבו יפעל Cassandra Adapter. אם אתם משתמשים בחשבון שירות, אתם צריכים לדעת את המיקום של קובץ מפתח ה-JSON (קובץ פרטי הכניסה). אתם מגדירים את משתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS כדי לציין את נתיב פרטי הכניסה.GOOGLE_APPLICATION_CREDENTIALS

למידע נוסף:

חיבור Cassandra Adapter לאפליקציה

כדי להשתמש ב-Cassandra Adapter, צריך לספק את הפרטים הבאים:

  • Project name
  • שם המכונה ב-Spanner
  • מסד הנתונים שאליו רוצים להתחבר

אם אתם משתמשים ב-Docker, אתם צריכים את הנתיב לקובץ פרטי כניסה בפורמט JSON (קובץ מפתח).

Java in-process

  1. אם אתם משתמשים בחשבון שירות לאימות, חשוב לוודא שמשתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS מוגדר לנתיב של קובץ פרטי הכניסה.

  2. באפליקציות Java, אפשר לקשר את Cassandra Adapter לאפליקציה ישירות על ידי הוספת google-cloud-spanner-cassandra כתלות לפרויקט.

ב-Maven, מוסיפים את יחסי התלות החדשים הבאים בקטע <dependencies>: 

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

ב-Gradle, מוסיפים את השורה הבאה: 

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

  1. משנים את קוד היצירה של CqlSession. במקום להשתמש ב-CqlSessionBuilder, משתמשים ב-SpannerCqlSessionBuilder ומזינים את ה-URI של מסד הנתונים של 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();
    }
  }
}

התקדמות בתהליך

באפליקציות Go, צריך לבצע שינוי של שורה אחת בקובץ האתחול של האשכול כדי לשלב את לקוח ה-Go של Spanner Cassandra. לאחר מכן אפשר לקשר את מתאם Cassandra לאפליקציה ישירות.

  1. מייבאים את חבילת spanner של המתאם מלקוח Spanner Cassandra Go באפליקציית Go.
import spanner "github.com/googleapis/go-spanner-cassandra/cassandra/gocql"
  1. משנים את קוד יצירת האשכול כך שישתמש ב-spanner.NewCluster במקום ב-gocql.NewCluster, ומזינים את ה-URI של מסד הנתונים ב-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
}

אחרי שמתחברים למסד הנתונים של Spanner, אפשר להגדיר את האשכול כרגיל.

עצמאי

  1. משכפלים את המאגר:
git clone https://github.com/googleapis/go-spanner-cassandra.git
cd go-spanner-cassandra
  1. מריצים את הפקודה cassandra_launcher.go עם הדגל -db הנדרש:
go run cassandra_launcher.go \
-db "projects/my_project/instances/my_instance/databases/my_database"
  1. מחליפים את -db במזהה המשאבים האחיד (URI) של מסד הנתונים ב-Spanner.

Docker

מריצים את Cassandra Adapter באמצעות הפקודה הבאה.

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

הרשימה הבאה מכילה את אפשרויות ההפעלה הנפוצות ביותר של Spanner Cassandra Adapter:

  • -db <DatabaseUri>

ה-URI של מסד הנתונים של Spanner (חובה). כאן מציינים את מסד הנתונים של Spanner שאליו הלקוח מתחבר. לדוגמה, projects/YOUR_PROJECT/instances/YOUR_INSTANCE/databases/YOUR_DATABASE.

  • -tcp <TCPEndpoint>

כתובת מאזין ה-Proxy של הלקוח. ההגדרה הזו מגדירה את נקודת הקצה של TCP שבה הלקוח מאזין לחיבורים נכנסים של לקוח Cassandra. ברירת מחדל:localhost:9042

  • -grpc-channels <NumGrpcChannels>

מספר ערוצי ה-gRPC שבהם יש להשתמש כשמתחברים ל-Spanner. ברירת מחדל: 4

לדוגמה, הפקודה הבאה מפעילה את Cassandra Adapter ביציאה 9042 באמצעות פרטי הכניסה של האפליקציה, ומקשרת את המתאם למסד הנתונים 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

המלצות

ההמלצות הבאות יעזרו לכם לשפר את חוויית השימוש ב-Cassandra Adapter. ההמלצות האלה מתמקדות ב-Java, ובמיוחד במנהל התקן של לקוח Cassandra ל-Java בגרסה 4.

הגדלת הזמן הקצוב לתפוגת הבקשה

זמן קצוב לתפוגה לבקשה של חמש שניות או יותר מספק חוויה טובה יותר עם Cassandra Adapter מאשר ערך ברירת המחדל של שתי שניות.

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

שיפור מאגר החיבורים

ההגדרות שמוגדרות כברירת מחדל למספר החיבורים המקסימלי ולמספר המקסימלי של בקשות בו-זמניות לכל חיבור או לכל מארח מתאימות לפיתוח, לבדיקות ולסביבות ייצור או לבמה עם נפח נמוך. עם זאת, מומלץ להגדיל את הערכים האלה, כי Cassandra Adapter מתחזה לצומת יחיד, בניגוד למאגר צמתים בתוך Cassandra cluster.

הגדלת הערכים האלה מאפשרת יותר חיבורים בו-זמנית בין הלקוח לבין Cassandra Interface. כך אפשר למנוע את מיצוי מאגר החיבורים בעומס כבד.

# 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
  }
}

כוונון ערוצי gRPC

הלקוח של Spanner משתמש בערוצי gRPC לתקשורת. ערוץ gRPC אחד שווה בערך לחיבור TCP. ערוץ gRPC אחד יכול לטפל בעד 100 בקשות בו-זמנית. המשמעות היא שאפליקציה תצטרך לפחות מספר ערוצי gRPC ששווה למספר הבקשות המקבילות שהאפליקציה תבצע, חלקי 100.

השבתת ניתוב מודע לטוקן

יכול להיות שיוצג לנהגים שמשתמשים באיזון עומסים מבוסס-טוקן אזהרה, או שהם לא יוכלו לעבוד עם Cassandra Adapter. מכיוון ש-Cassandra Adapter מתחזה לצומת יחיד, הוא לא תמיד פועל טוב עם מנהלי התקנים שמודעים לטוקנים ומצפים שיהיו לפחות מספר צמתים בגורם השכפול באשכול. חלק מהדרייברים עשויים להדפיס אזהרה (שאפשר להתעלם ממנה) ולחזור למדיניות איזון כמו round-robin, בעוד שדרייברים אחרים עשויים להיכשל עם שגיאה. לגבי הדרייברים שנכשלים עם שגיאה, צריך להשבית את התכונה token-aware או להגדיר את מדיניות איזון העומסים round-robin.

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

הצמדת גרסת הפרוטוקול ל-V4

מתאם Cassandra תואם לכל מנהל התקן של לקוח Apache Cassandra בקוד פתוח שתואם לפרוטוקול חוטי CQL Binary v4. חשוב להצמיד את PROTOCOL_VERSION אל V4, אחרת יכול להיות שיוצגו שגיאות חיבור.

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

המאמרים הבאים