חיבור JDBC למסד נתונים של ניב GoogleSQL

הערה: בדף הזה מתואר מנהל ההתקן Spanner JDBC, שהוא מנהל ההתקן המומלץ שנוצר על ידי Google.

בדף הזה מוסבר איך לבצע פעולות בסיסיות ב-Spanner באמצעות Spanner JDBC driver.

התקנת מנהל התקן JDBC

כדי להגדיר אימות, פועלים לפי השלבים שמפורטים במאמר ספריות של לקוח Spanner, ואז מוסיפים לקובץ pom.xml את התלויות של מנהל התקן Spanner JDBC, שמוצגות בקטע הקוד הבא.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>26.76.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-spanner-jdbc</artifactId>
    <exclusions>
      <exclusion>
        <groupId>com.google.api.grpc</groupId>
        <artifactId>proto-google-cloud-spanner-executor-v1</artifactId>
      </exclusion>
    </exclusions>
  </dependency>

אם אתם משתמשים במסגרת שנדרש בה שם מחלקת Java כדי לטעון את מנהל ההתקן של JDBC, השם הוא com.google.cloud.spanner.jdbc.JdbcDriver. הוראות להגדרת חיבור מופיעות במאמרי העזרה של ה-API בנושא JdbcDriver.

התחברות למסד נתונים ב-Spanner

בתיאור המחלקה JdbcDriver מופיע תחביר מחרוזת החיבור וקוד לדוגמה ליצירת חיבור ולהרצת שאילתה.

הדרייבר מזהה באופן אוטומטי את הניב של SQL (GoogleSQL או PostgreSQL) של מסד הנתונים שצוין. אין צורך בפרמטר של ניב, וגם אסור להשתמש בו.

חיבור לאמולטור

כדי להתחבר לאמולטור, מגדירים את משתנה הסביבה SPANNER_EMULATOR_HOST, לדוגמה:

‫Linux / macOS

export SPANNER_EMULATOR_HOST=localhost:9010

Windows

set SPANNER_EMULATOR_HOST=localhost:9010

ההוראה הזו מורה למנהל ההתקן של Spanner JDBC להתחבר לאמולטור שפועל ב-localhost במקום לשירות הייצור שמוגדר כברירת מחדל.

הערה: אפשר לציין את המארח במחרוזת החיבור, למרות שזה פחות נפוץ. לדוגמה: jdbc:cloudspanner://localhost:9010/projects/test-project/instances/test-instance/databases/test-db;usePlainText=true. למארח במחרוזת החיבור תמיד יש עדיפות, בלי קשר להגדרה של SPANNER_EMULATOR_HOST. בנוסף, צריך לציין usePlainText=true במחרוזת החיבור כי האמולטור לא תומך ב-SSL/TLS.

דוגמאות

בדוגמאות הקוד הבאות אפשר לראות כמה תרחישי שימוש נפוצים.

הפעלת עדכון של סכימה

בדוגמה הבאה של קוד, הטבלה Singers מתווספת למסד הנתונים. לשם כך, קודם נוצר חיבור JDBC ואז נוצרת הטבלה:

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
import java.sql.Statement;

class CreateTableExample {

  static void createTable() throws SQLException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "my-project";
    String instanceId = "my-instance";
    String databaseId = "my-database";
    createTable(projectId, instanceId, databaseId);
  }

  static void createTable(String projectId, String instanceId, String databaseId)
      throws SQLException {
    String connectionUrl =
        String.format(
            "jdbc:cloudspanner:/projects/%s/instances/%s/databases/%s",
            projectId, instanceId, databaseId);
    try (Connection connection = DriverManager.getConnection(connectionUrl)) {
      try (Statement statement = connection.createStatement()) {
        statement.execute(
            "CREATE TABLE Singers (\n"
                + "  SingerId   INT64 NOT NULL,\n"
                + "  FirstName  STRING(1024),\n"
                + "  LastName   STRING(1024),\n"
                + "  SingerInfo BYTES(MAX),\n"
                + "  Revenues   NUMERIC,\n"
                + ") PRIMARY KEY (SingerId)\n");
      }
    }
    System.out.println("Created table [Singers]");
  }
}

שימוש בטרנזקציה במצב אישור אוטומטי כדי להוסיף שורות

אם אתם לא צריכים לבצע כמה פעולות כקבוצה, אתם יכולים להשתמש בעסקאות במצב אישור אוטומטי (autocommit), שהוא התנהגות ברירת המחדל. בדוגמת הקוד הבאה נעשה שימוש בטרנזקציה במצב אישור אוטומטי כדי להוסיף שורות לטבלה Singers:

import java.math.BigDecimal;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.SQLException;
import java.sql.Types;
import java.util.Arrays;
import java.util.List;

class InsertDataExample {
  // Class to contain singer sample data.
  static class Singer {
    final long singerId;
    final String firstName;
    final String lastName;
    final BigDecimal revenues;

    Singer(long singerId, String firstName, String lastName, BigDecimal revenues) {
      this.singerId = singerId;
      this.firstName = firstName;
      this.lastName = lastName;
      this.revenues = revenues;
    }
  }

  static final List<Singer> SINGERS =
      Arrays.asList(
          new Singer(10, "Marc", "Richards", new BigDecimal("104100.00")),
          new Singer(20, "Catalina", "Smith", new BigDecimal("9880.99")),
          new Singer(30, "Alice", "Trentor", new BigDecimal("300183")),
          new Singer(40, "Lea", "Martin", new BigDecimal("20118.12")),
          new Singer(50, "David", "Lomond", new BigDecimal("311399.26")));

  static void insertData() throws SQLException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "my-project";
    String instanceId = "my-instance";
    String databaseId = "my-database";
    insertData(projectId, instanceId, databaseId);
  }

  static void insertData(String projectId, String instanceId, String databaseId)
      throws SQLException {
    String connectionUrl =
        String.format(
            "jdbc:cloudspanner:/projects/%s/instances/%s/databases/%s",
            projectId, instanceId, databaseId);
    try (Connection connection = DriverManager.getConnection(connectionUrl)) {
      try (PreparedStatement ps =
          connection.prepareStatement(
              "INSERT INTO Singers\n"
                  + "(SingerId, FirstName, LastName, SingerInfo, Revenues)\n"
                  + "VALUES\n"
                  + "(?, ?, ?, ?, ?)")) {
        for (Singer singer : SINGERS) {
          ps.setLong(1, singer.singerId);
          ps.setString(2, singer.firstName);
          ps.setString(3, singer.lastName);
          ps.setNull(4, Types.BINARY);
          ps.setBigDecimal(5, singer.revenues);
          ps.addBatch();
        }
        int[] updateCounts = ps.executeBatch();
        System.out.printf("Insert counts: %s%n", Arrays.toString(updateCounts));
      }
    }
  }
}

שליטה באופן שבו כמה פעולות מבוצעות כקבוצה

אם אתם רוצים לשלוט בהחלטה אם Spanner יבצע קומיט של כמה פעולות יחד כקבוצה, אתם יכולים להשבית את מצב הקומיט האוטומטי. בדוגמת הקוד הבאה נעשה שימוש בפקודות connection.setAutoCommit(false) ו-connection.commit() כדי להוסיף שורות לטבלה Singers.

import com.google.common.collect.ImmutableList;
import java.math.BigDecimal;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.SQLException;
import java.util.Arrays;

class BatchDmlExample {
  static class Singer {
    final long singerId;
    final String firstName;
    final String lastName;
    final BigDecimal revenues;

    Singer(long singerId, String firstName, String lastName, BigDecimal revenues) {
      this.singerId = singerId;
      this.firstName = firstName;
      this.lastName = lastName;
      this.revenues = revenues;
    }
  }

  static void batchDml() throws SQLException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "my-project";
    String instanceId = "my-instance";
    String databaseId = "my-database";
    batchDml(projectId, instanceId, databaseId);
  }

  // This example shows how to execute a batch of DML statements with the JDBC driver.
  static void batchDml(String projectId, String instanceId, String databaseId) throws SQLException {
    String connectionUrl =
        String.format(
            "jdbc:cloudspanner:/projects/%s/instances/%s/databases/%s",
            projectId, instanceId, databaseId);

    ImmutableList<Singer> singers = ImmutableList.of(
        new Singer(10, "Marc", "Richards", BigDecimal.valueOf(10000)),
        new Singer(11, "Amirah", "Finney", BigDecimal.valueOf(195944.10d)),
        new Singer(12, "Reece", "Dunn", BigDecimal.valueOf(10449.90))
    );

    try (Connection connection = DriverManager.getConnection(connectionUrl)) {
      connection.setAutoCommit(false);
      // Use prepared statements for the lowest possible latency when executing the same SQL string
      // multiple times.
      try (PreparedStatement statement = connection.prepareStatement(
          "INSERT INTO Singers (SingerId, FirstName, LastName, Revenues)\n" 
              + "VALUES (?, ?, ?, ?)")) {
        for (Singer singer : singers) {
          statement.setLong(1, singer.singerId);
          statement.setString(2, singer.firstName);
          statement.setString(3, singer.lastName);
          statement.setBigDecimal(4, singer.revenues);
          // Add the current parameter values to the batch.
          statement.addBatch();
        }
        // Execute the batched statements.
        int[] updateCounts = statement.executeBatch();
        connection.commit();
        System.out.printf("Batch insert counts: %s%n", Arrays.toString(updateCounts));
      }
    }
  }
}

הרצת שאילתת SQL

בדוגמה הבאה של קוד מוצגות כל השורות בטבלה Singers, מסודרות לפי שם המשפחה של הזמר:

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;

public class SingleUseReadOnlyExample {

  static void singleUseReadOnly() throws SQLException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "my-project";
    String instanceId = "my-instance";
    String databaseId = "my-database";
    singleUseReadOnly(projectId, instanceId, databaseId);
  }

  static void singleUseReadOnly(String projectId, String instanceId, String databaseId)
      throws SQLException {
    String connectionUrl =
        String.format(
            "jdbc:cloudspanner:/projects/%s/instances/%s/databases/%s",
            projectId, instanceId, databaseId);
    try (Connection connection = DriverManager.getConnection(connectionUrl);
        Statement statement = connection.createStatement()) {
      // When the connection is in autocommit mode, any query that is executed will automatically
      // be executed using a single-use read-only transaction, even if the connection itself is in
      // read/write mode.
      try (ResultSet rs =
          statement.executeQuery(
              "SELECT SingerId, FirstName, LastName, Revenues FROM Singers ORDER BY LastName")) {
        while (rs.next()) {
          System.out.printf(
              "%d %s %s %s%n",
              rs.getLong(1), rs.getString(2), rs.getString(3), rs.getBigDecimal(4));
        }
      }
    }
  }
}

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

• תשובות לשאלות נפוצות לגבי מנהל ההתקן של Spanner JDBC
• מידע על פקודות לניהול סשנים במנהל התקן Spanner JDBC