Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

חיבור באמצעות מחברי שפה של Cloud SQL

‫MySQL | PostgreSQL | SQL Server

המחברים של Cloud SQL הם ספריות שמספקות הצפנה והרשאה שמבוססת על ניהול זהויות והרשאות גישה (IAM) כשמתחברים למכונה של Cloud SQL. הם לא יכולים לספק נתיב רשת למופע Cloud SQL אם הוא לא קיים.

דרכים אחרות להתחבר למכונה של Cloud SQL כוללות שימוש בלקוח מסד נתונים או בשרת proxy ל-Cloud SQL Auth. מידע נוסף על חיבור למופע Cloud SQL זמין בדף אפשרויות חיבור.

בדף הזה נסביר על מחברי Cloud SQL הבאים:

‫Cloud SQL Java Connector
המחבר של Cloud SQL Python (פתיחה ב-Colab)
מחבר Go ל-Cloud SQL
‫Cloud SQL Node.js Connector

יתרונות

שימוש ב-Cloud SQL Connector מספק את היתרונות הבאים:

הרשאה ב-IAM: משתמשים בהרשאות IAM כדי לקבוע למי או למה תהיה אפשרות להתחבר למופעי Cloud SQL.
נוחות: אין צורך לנהל אישורי SSL, להגדיר כללי חומת אש או להפעיל רשתות מורשות.

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

מפעילים את Cloud SQL Admin API.
תפקידים שנדרשים להפעלת ממשקי API
כדי להפעיל ממשקי API, צריך את תפקיד ה-IAM 'אדמין של Service Usage' (roles/serviceusage.serviceUsageAdmin), שכולל את ההרשאה serviceusage.services.enable. איך מקצים תפקידים
להפעלת ה-API
יצירת מכונה של Cloud SQL, כולל הגדרת משתמש ברירת המחדל.

מידע נוסף על יצירת מופעים זמין במאמר יצירת מופעים.

מידע נוסף על הגדרת משתמש ברירת המחדל זמין במאמר בנושא הגדרת הסיסמה לחשבון משתמש ברירת המחדל.
מגדירים את התפקידים וההרשאות שנדרשים כדי להתחבר למופע Cloud SQL.
הערה: אם הגורם המורשה ב-IAM שייך לפרויקט אחר מזה שמכיל את מופע Cloud SQL, צריך לבצע את הפעולות הבאות:
- מפעילים את Cloud SQL Admin API בשני הפרויקטים.
- מוסיפים את הרשאות ה-IAM לחשבון המשתמש ב-IAM בפרויקט שמכיל את מכונת Cloud SQL.

הגדרה

Java

‫Cloud SQL Java Connector היא ספרייה שמספקת הרשאה והצפנה מבוססות-IAM כשמתחברים למכונת Cloud SQL. הוא לא יכול לספק נתיב ברשת למופע Cloud SQL אם הוא לא קיים.

התקנה

הוראות ליצירה ולשימוש במנהלי התקנים ל-JDBC ול-R2DBC באמצעות Cloud SQL Java Connector זמינות בקישורים הבאים:

‫JDBC: חיבור ל-Cloud SQL באמצעות JDBC.
‫R2DBC: חיבור ל-Cloud SQL באמצעות R2DBC.

כדי לראות דוגמאות לשימוש בספרייה הזו בהקשר של אפליקציה, אפשר לעיין באפליקציות לדוגמה.

אמת

הספרייה הזו משתמשת ב-Application Default Credentials כדי לאמת את החיבור לשרת Cloud SQL.

כדי להפעיל את פרטי הכניסה באופן מקומי, משתמשים בפקודה הבאה של gcloud:

    gcloud auth application-default login

התחברות באמצעות Intellij

כדי לקשר את IntelliJ למופע Cloud SQL, צריך להוסיף את הספרייה כקובץ jar עם תלות בקטע Additional Files בדף הגדרות הדרייבר. לדוגמה, קובצי JAR גדולים מוכנים מראש זמינים בדף Cloud SQL Java Connector Releases.

Python

המחבר של Cloud SQL Python הוא ספרייה שאפשר להשתמש בה לצד מנהל התקן של מסד נתונים כדי לאפשר למשתמשים עם הרשאות מספיקות להתחבר למסד נתונים של Cloud SQL בלי להוסיף כתובות IP לרשימת ההיתרים באופן ידני או לנהל אישורי SSL.

כדי לראות דוגמאות אינטראקטיביות לשימוש ב-Cloud SQL Python Connector, פותחים את המחברת Cloud SQL Python Connector.

הדרייבר שנתמך על ידי SQL Server הוא pytds.

התקנה

כדי להתקין את הגרסה האחרונה של Cloud SQL Python Connector, משתמשים בפקודה pip install ומציינים את מנהל ההתקן pytds של מסד הנתונים:

    pip install "cloud-sql-python-connector[pytds]"

אמת

הספרייה הזו משתמשת ב-Application Default Credentials כדי לאמת את החיבור לשרת Cloud SQL.

כדי להפעיל את פרטי הכניסה באופן מקומי, משתמשים בפקודה הבאה של gcloud:

    gcloud auth application-default login

המשך

המחבר Cloud SQL Go הוא מחבר Cloud SQL שמיועד לשימוש בשפת Go. כדי לשפר את האבטחה, המחבר הזה משתמש בהצפנת TLS 1.3 חזקה ומאומתת ידנית בין מחבר הלקוח לבין ה-proxy בצד השרת, ללא קשר לפרוטוקול של מסד הנתונים.

התקנה

אפשר להתקין את המאגר הזה באמצעות go get:

    go get cloud.google.com/go/cloudsqlconn

Node.js

‫Node.js Connector היא ספרייה שנועדה לשימוש עם סביבת זמן הריצה של Node.js, ומאפשרת להתחבר בצורה מאובטחת למופע Cloud SQL.

התקנה

אפשר להתקין את הספרייה באמצעות npm install:

    npm install @google-cloud/cloud-sql-connector

שימוש

Java

כדי לראות את קטע הקוד הזה בהקשר של אפליקציית אינטרנט, אפשר לעיין בקובץ ה-README ב-GitHub.


import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import javax.sql.DataSource;

public class ConnectorConnectionPoolFactory extends ConnectionPoolFactory {

  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  private static final String INSTANCE_CONNECTION_NAME =
      System.getenv("INSTANCE_CONNECTION_NAME");
  private static final String DB_USER = System.getenv("DB_USER");
  private static final String DB_PASS = System.getenv("DB_PASS");
  private static final String DB_NAME = System.getenv("DB_NAME");

  public static DataSource createConnectionPool() {
    // The configuration object specifies behaviors for the connection pool.
    HikariConfig config = new HikariConfig();

    // The following is equivalent to setting the config options below:
    // jdbc:sqlserver://;user=<DB_USER>;password=<DB_PASS>;databaseName=<DB_NAME>;
    // socketFactoryClass=com.google.cloud.sql.sqlserver.SocketFactory;
    // socketFactoryConstructorArg=<INSTANCE_CONNECTION_NAME>

    // See the link below for more info on building a JDBC URL for the Cloud SQL JDBC Socket Factory
    // https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory#creating-the-jdbc-url

    // Configure which instance and what database user to connect with.
    config
        .setDataSourceClassName("com.microsoft.sqlserver.jdbc.SQLServerDataSource");
    config.setUsername(DB_USER); // e.g. "root", "sqlserver"
    config.setPassword(DB_PASS); // e.g. "my-password"
    config.addDataSourceProperty("databaseName", DB_NAME);

    config.addDataSourceProperty("socketFactoryClass",
        "com.google.cloud.sql.sqlserver.SocketFactory");
    config.addDataSourceProperty("socketFactoryConstructorArg", INSTANCE_CONNECTION_NAME);

    // The Java Connector provides SSL encryption, so it should be disabled
    // at the driver level.
    config.addDataSourceProperty("encrypt", "false");

    // cloudSqlRefreshStrategy set to "lazy" is used to perform a
    // refresh when needed, rather than on a scheduled interval.
    // This is recommended for serverless environments to
    // avoid background refreshes from throttling CPU.
    config.addDataSourceProperty("cloudSqlRefreshStrategy", "lazy");

    // ... Specify additional connection properties here.
    // ...

    // Initialize the connection pool using the configuration object.
    return new HikariDataSource(config);
  }
}

הערה: אם מגדירים את encrypt=true ואת trustServerCertificate = false or blank, צריך לכלול את CA file עבור המופע. אם אתם משתמשים בשרת proxy ל-Cloud SQL Auth, hostNameInCertificate אסור להיות ריק.

Python

הוראות מפורטות לשימוש בספרייה מופיעות במאמר איך משתמשים במחבר הזה. אפשר לראות קוד לדוגמה של בדיקת חיבור ב-GitHub.

import os

from google.cloud.sql.connector import Connector, IPTypes
import pytds

import sqlalchemy


def connect_with_connector() -> sqlalchemy.engine.base.Engine:
    """
    Initializes a connection pool for a Cloud SQL instance of SQL Server.

    Uses the Cloud SQL Python Connector package.
    """
    # Note: Saving credentials in environment variables is convenient, but not
    # secure - consider a more secure solution such as
    # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
    # keep secrets safe.

    instance_connection_name = os.environ[
        "INSTANCE_CONNECTION_NAME"
    ]  # e.g. 'project:region:instance'
    db_user = os.environ.get("DB_USER", "")  # e.g. 'my-db-user'
    db_pass = os.environ["DB_PASS"]  # e.g. 'my-db-password'
    db_name = os.environ["DB_NAME"]  # e.g. 'my-database'

    ip_type = IPTypes.PRIVATE if os.environ.get("PRIVATE_IP") else IPTypes.PUBLIC

    # initialize Cloud SQL Python Connector object
    connector = Connector(ip_type=ip_type, refresh_strategy="LAZY")

    connect_args = {}
    # If your SQL Server instance requires SSL, you need to download the CA
    # certificate for your instance and include cafile={path to downloaded
    # certificate} and validate_host=False. This is a workaround for a known issue.
    if os.environ.get("DB_ROOT_CERT"):  # e.g. '/path/to/my/server-ca.pem'
        connect_args = {
            "cafile": os.environ["DB_ROOT_CERT"],
            "validate_host": False,
        }

    def getconn() -> pytds.Connection:
        conn = connector.connect(
            instance_connection_name,
            "pytds",
            user=db_user,
            password=db_pass,
            db=db_name,
            **connect_args
        )
        return conn

    pool = sqlalchemy.create_engine(
        "mssql+pytds://",
        creator=getconn,
        # ...
    )
    return pool

הערה: אם המכונה שלכם דורשת SSL כדי להתחבר, כדי ש-Pytds יעבוד, אתם צריכים לכלול את CA file עבור המכונה. אם אתם משתמשים גם בשרת proxy ל-Cloud SQL Auth, צריך להגדיר את validate_host לערך False.

המשך

הוראות מפורטות לשימוש בספרייה מופיעות במאמר בנושא שימוש. אפשר לראות קוד לדוגמה של בדיקת חיבור ב-GitHub.

package cloudsql

import (
	"context"
	"database/sql"
	"fmt"
	"log"
	"net"
	"os"

	"cloud.google.com/go/cloudsqlconn"
	mssql "github.com/denisenkom/go-mssqldb"
)

type csqlDialer struct {
	dialer     *cloudsqlconn.Dialer
	connName   string
	usePrivate bool
}

// DialContext adheres to the mssql.Dialer interface.
func (c *csqlDialer) DialContext(ctx context.Context, network, addr string) (net.Conn, error) {
	var opts []cloudsqlconn.DialOption
	if c.usePrivate {
		opts = append(opts, cloudsqlconn.WithPrivateIP())
	}
	return c.dialer.Dial(ctx, c.connName, opts...)
}

func connectWithConnector() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Fatal Error in connect_connector.go: %s environment variable not set.\n", k)
		}
		return v
	}
	// Note: Saving credentials in environment variables is convenient, but not
	// secure - consider a more secure solution such as
	// Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
	// keep secrets safe.
	var (
		dbUser                 = mustGetenv("DB_USER")                  // e.g. 'my-db-user'
		dbPwd                  = mustGetenv("DB_PASS")                  // e.g. 'my-db-password'
		dbName                 = mustGetenv("DB_NAME")                  // e.g. 'my-database'
		instanceConnectionName = mustGetenv("INSTANCE_CONNECTION_NAME") // e.g. 'project:region:instance'
		usePrivate             = os.Getenv("PRIVATE_IP")
	)

	dbURI := fmt.Sprintf("user id=%s;password=%s;database=%s;", dbUser, dbPwd, dbName)
	c, err := mssql.NewConnector(dbURI)
	if err != nil {
		return nil, fmt.Errorf("mssql.NewConnector: %w", err)
	}
	// WithLazyRefresh() Option is used to perform refresh
	// when needed, rather than on a scheduled interval.
	// This is recommended for serverless environments to
	// avoid background refreshes from throttling CPU.
	dialer, err := cloudsqlconn.NewDialer(context.Background(), cloudsqlconn.WithLazyRefresh())
	if err != nil {
		return nil, fmt.Errorf("cloudsqlconn.NewDailer: %w", err)
	}
	c.Dialer = &csqlDialer{
		dialer:     dialer,
		connName:   instanceConnectionName,
		usePrivate: usePrivate != "",
	}

	dbPool := sql.OpenDB(c)
	if err != nil {
		return nil, fmt.Errorf("sql.Open: %w", err)
	}
	return dbPool, nil
}

Node.js

הוראות מפורטות לשימוש בספרייה מופיעות במאמר בנושא שימוש.

const {Connection} = require('tedious');
const {Connector} = require('@google-cloud/cloud-sql-connector');

// In case the PRIVATE_IP environment variable is defined then we set
// the ipType=PRIVATE for the new connector instance, otherwise defaults
// to public ip type.
const getIpType = () =>
  process.env.PRIVATE_IP === '1' || process.env.PRIVATE_IP === 'true'
    ? 'PRIVATE'
    : 'PUBLIC';

// connectWithConnector initializes a TCP connection
// to a Cloud SQL instance of SQL Server.
const connectWithConnector = async config => {
  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  const connector = new Connector();
  const clientOpts = await connector.getTediousOptions({
    instanceConnectionName: process.env.INSTANCE_CONNECTION_NAME,
    ipType: getIpType(),
  });
  const dbConfig = {
    // Please note that the `server` property here is not used and is only
    // defined due to a bug in the tedious driver
    // (ref: https://github.com/tediousjs/tedious/issues/1541)
    // With that in mind, do not try to change this value since it will have no
    // impact in how the connector works, this sample will be updated to remove
    // this property declaration as soon as the tedious driver bug is fixed
    server: '0.0.0.0', // e.g. '127.0.0.1'
    authentication: {
      type: 'default',
      options: {
        userName: process.env.DB_USER, // e.g. 'my-db-user'
        password: process.env.DB_PASS, // e.g. 'my-db-password'
      },
    },
    options: {
      ...clientOpts,
      // Please note that the `port` property here is not used and is only
      // defined due to a bug in the tedious driver
      // (ref: https://github.com/tediousjs/tedious/issues/1541)
      // With that in mind, do not try to change this value since it will have
      // no impact in how the connector works, this sample will be updated to
      // remove this property declaration as soon as the tedious driver bug is
      // fixed
      port: 9999,
      database: process.env.DB_NAME, // e.g. 'my-database'
      useColumnNames: true,
    },
    // ... Specify additional properties here.
    ...config,
  };

  // Establish a connection to the database.
  return new Connection(dbConfig);
};

לאכוף

באמצעות אכיפת מחברים, אתם יכולים לאכוף שימוש רק בשרת proxy ל-Cloud SQL Auth או במחברים של Cloud SQL Language כדי להתחבר למכונות Cloud SQL. כשהאכיפה של המחבר מופעלת, Cloud SQL דוחה חיבורים ישירים למסד הנתונים.

אם אתם משתמשים במופע עם Private Service Connect, יש הגבלה. אם האכיפה של המחבר מופעלת במופע, אי אפשר ליצור רפליקות לקריאה עבור המופע. באופן דומה, אם למופע יש עותקים לקריאה, אי אפשר להפעיל את האכיפה של המחבר במופע.

gcloud

כדי לאכוף שימוש רק בשרת proxy ל-Cloud SQL Auth או במחברי שפה של Cloud SQL כדי להתחבר למכונה, משתמשים בפקודה gcloud sql instances patch:

gcloud sql instances patch INSTANCE_NAME \
--connector-enforcement=REQUIRED

מחליפים את INSTANCE_NAME בשם של מופע Cloud SQL.

REST

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

‫PROJECT_ID: המזהה או מספר הפרויקט של פרויקט Google Cloud שמכיל את המופע
‫INSTANCE_NAME: השם של מכונת Cloud SQL

הערה: אם מגדירים את הערך של הפרמטר connectorEnforcement ל-REQUIRED, כל החיבורים חייבים להשתמש ב-Cloud SQL Language Connectors, כולל שרת ה-proxy ל-Cloud SQL Auth והמחברים של Java,‏ Python,‏ Go ו-Node.js.

ה-method של ה-HTTP וכתובת ה-URL:

PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

תוכן בקשת JSON:

{
  "kind": "sql#instance",
  "name": INSTANCE_NAME,
  "project": PROJECT_ID,
  "settings": {
  "connectorEnforcement": "REQUIRED",
  "kind": "sql#settings"
  }
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

‫Curl (Linux,‏ macOS או Cloud Shell)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME"

‎PowerShell (Windows)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_NAME",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

פתרון בעיות

גרסאות מנהלי ההתקנים

כדי למנוע בעיות תאימות, חשוב לוודא שאתם משתמשים בגרסה העדכנית ביותר של Cloud SQL Connectors ומנהל התקן מסד הנתונים. חלק מהגרסאות הישנות יותר של מנהלי ההתקנים לא נתמכות.

נתיבי המרות

המחברים של Cloud SQL מספקים הרשאה לחיבורים, אבל הם לא מספקים נתיבים חדשים לקישוריות. לדוגמה, כדי להתחבר למכונת Cloud SQL באמצעות כתובת IP פרטית, לאפליקציה שלכם כבר צריכה להיות גישה ל-VPC.

ניפוי באגים בבעיות בחיבור

לקבלת עזרה נוספת בפתרון בעיות בחיבור, אפשר לעיין בדפים פתרון בעיות וניפוי באגים בבעיות בחיבור.

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

אפשר לעיין בדף הבית של Cloud SQL Java Connector ב-GitHub.
אפשר לעיין בדף הבית של Cloud SQL Python Connector ב-GitHub.
מידע נוסף על שרת proxy ל-Cloud SQL Auth
מידע נוסף על IAM
מידע על אפשרויות התמיכה

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

יתרונות

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

הגדרה

Java

התקנה

אמת

התחברות באמצעות Intellij

Python

התקנה

אמת

המשך

התקנה

Node.js

התקנה

שימוש

Java

Python

המשך

Node.js

לאכוף

gcloud

REST

‫Curl (Linux,‏ macOS או Cloud Shell)

‎PowerShell (Windows)

פתרון בעיות

גרסאות מנהלי ההתקנים

נתיבי המרות

ניפוי באגים בבעיות בחיבור

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

חיבור באמצעות מחברי שפה של Cloud SQL