Cloud SQL 커넥터를 사용하여 연결

Cloud SQL 커넥터는 Cloud SQL 인스턴스에 연결할 때 암호화 및 IAM 기반 승인을 제공하는 라이브러리입니다. Cloud SQL 인스턴스가 아직 없는 경우 Cloud SQL 인스턴스에 대한 네트워크 경로를 제공할 수 없습니다.

Cloud SQL 인스턴스에 연결하는 다른 방법으로는 데이터베이스 클라이언트 사용 또는 Cloud SQL 인증 프록시가 있습니다. Cloud SQL 인스턴스에 연결하는 방법에 대한 자세한 내용은 연결 개요 페이지를 참조하세요.

이 페이지에서는 다음 Cloud SQL 커넥터에 대해 설명합니다.

  • Cloud SQL 자바 커넥터
  • Cloud SQL Python 커넥터

시작하기 전에

Cloud SQL 인스턴스에 연결하려면 먼저 다음이 필요합니다.

  • Cloud SQL API를 사용 설정합니다.

    API 사용 설정

  • Cloud SQL 인스턴스를 만들고 기본 사용자를 구성합니다.

    인스턴스를 만드는 방법에 대한 자세한 내용은 인스턴스 만들기를 참조하세요.

    기본 사용자를 구성하는 방법에 대한 자세한 내용은 기본 사용자 계정 구성을 참조하세요.

  • Cloud SQL 인스턴스에 연결하는 데 필요한 역할과 권한이 구성되었습니다.
  • Cloud SQL 인스턴스에 연결하는 방법에 대한 자세한 내용은 연결 개요 페이지를 참조하세요.

설정

자바

Cloud SQL 자바 커넥터는 Cloud SQL 인스턴스에 연결할 때 IAM 기반 승인 및 암호화를 제공하는 라이브러리입니다. Cloud SQL 인스턴스가 아직 없으면 네트워크 경로를 제공할 수 없습니다.

설치

Cloud SQL 자바 커넥터를 사용하여 JDBC 및 R2DBC용 드라이버를 빌드하고 사용하는 방법은 다음 링크를 참조하세요.

JDBC: JDBC를 사용하여 MySQL에 연결

R2DBC: R2DBC를 사용하여 MySQL에 연결

애플리케이션의 컨텍스트에서 사용되는 이 라이브러리의 예시는 다음 샘플 애플리케이션을 참조하세요.

인증

이 라이브러리는 애플리케이션 기본 사용자 인증 정보를 사용하여 Cloud SQL 서버와의 연결을 인증합니다.

사용자 인증 정보를 로컬에서 활성화하려면 다음 gcloud 명령어를 사용하세요.

    gcloud auth application-default login
    

Intellij와 연결

Cloud SQL 인스턴스에 IntelliJ를 연결하려면 드라이버 설정 페이지의 추가 파일 섹션에서 종속 항목을 사용하여 라이브러리를 jar로 추가해야 합니다. 예를 들어 이를 위해 Cloud SQL 자바 커넥터 출시 페이지에서 사전 빌드된 fat jar를 찾아볼 수 있습니다.

Python

Cloud SQL Python 커넥터는 Cloud SQL 데이터베이스에 연결할 수 있는 충분한 권한이 있는 사용자가 IP를 직접 허용 목록에 추가하거나 SSL 인증서를 관리할 필요 없이 데이터베이스 드라이버와 함께 사용할 수 있는 라이브러리입니다.

현재 MySQL에 지원되는 드라이버는 pymysql입니다.

설치

최신 출시 버전을 설치하려면 이 안내를 따르세요.

인증

이 라이브러리는 애플리케이션 기본 사용자 인증 정보를 사용하여 Cloud SQL 서버와의 연결을 인증합니다.

사용자 인증 정보를 로컬에서 활성화하려면 다음 gcloud 명령어를 사용하세요.

    gcloud auth application-default login
    

용도

자바

웹 애플리케이션의 컨텍스트에서 이 스니펫을 보려면 GitHub의 README를 참조하세요.

// Note: For Java users, the Cloud SQL JDBC Socket Factory can provide authenticated connections
// which is preferred to using the Cloud SQL Proxy with Unix sockets.
// See https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory for details.

// The configuration object specifies behaviors for the connection pool.
HikariConfig config = new HikariConfig();

// The following URL is equivalent to setting the config options below:
// jdbc:mysql:///<DB_NAME>?cloudSqlInstance=<CLOUD_SQL_CONNECTION_NAME>&
// socketFactory=com.google.cloud.sql.mysql.SocketFactory&user=<DB_USER>&password=<DB_PASS>
// 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.setJdbcUrl(String.format("jdbc:mysql:///%s", DB_NAME));
config.setUsername(DB_USER); // e.g. "root", "mysql"
config.setPassword(DB_PASS); // e.g. "my-password"

config.addDataSourceProperty("socketFactory", "com.google.cloud.sql.mysql.SocketFactory");
config.addDataSourceProperty("cloudSqlInstance", CLOUD_SQL_CONNECTION_NAME);

// The ipTypes argument can be used to specify a comma delimited list of preferred IP types
// for connecting to a Cloud SQL instance. The argument ipTypes=PRIVATE will force the
// SocketFactory to connect with an instance's associated private IP.
config.addDataSourceProperty("ipTypes", "PUBLIC,PRIVATE");

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

// Initialize the connection pool using the configuration object.
DataSource pool = new HikariDataSource(config);

Python

라이브러리를 사용하는 방법에 대한 자세한 내용은 커넥터 사용 방법을 참조하세요. GitHub에서 연결 테스트 코드 예시를 봅니다.

# The Cloud SQL Python Connector can be used along with SQLAlchemy using the
# 'creator' argument to 'create_engine'
def init_connection_engine() -> sqlalchemy.engine.Engine:
    def getconn() -> pymysql.connections.Connection:
        conn: pymysql.connections.Connection = connector.connect(
            os.environ["MYSQL_CONNECTION_NAME"],
            "pymysql",
            user=os.environ["MYSQL_USER"],
            password=os.environ["MYSQL_PASS"],
            db=os.environ["MYSQL_DB"],
        )
        return conn

    engine = sqlalchemy.create_engine(
        "mysql+pymysql://",
        creator=getconn,
    )
    return engine

문제 해결

방화벽 구성

Cloud SQL 인증 프록시는 포트 3307을 사용하여 Cloud SQL 인스턴스에 대한 연결을 설정합니다. 방화벽으로 보호되는 애플리케이션은 TCP 포트 3307에서 발신 연결을 허용하도록 구성해야 할 수 있습니다. 방화벽에 의해 연결이 차단되면 일반적으로 연결 실패를 나타내는 오류가 발생합니다. com.mysql.jdbc.exceptions.jdbc4.CommunicationsException: Communications link failure).

드라이버 버전

비호환성을 방지하려면 최신 버전의 Cloud SQL 커넥터 및 데이터베이스 드라이버를 사용해야 합니다. 일부 이전 버전의 드라이버는 지원되지 않습니다.

연결 경로

Cloud SQL 커넥터는 연결에 대한 승인을 제공하지만 연결에 대한 새 경로는 제공하지 않습니다. 예를 들어 비공개 IP 주소를 사용하여 Cloud SQL 인스턴스에 연결하려면 애플리케이션에 이미 VPC 액세스 권한이 있어야 합니다. 공개 IP 주소를 사용하여 Cloud SQL 인스턴스에 연결하려면 애플리케이션이 승인된 네트워크에 있어야 합니다.

연결 문제 디버깅

연결 문제와 관련해 추가 도움이 필요하면 문제 해결연결 문제 디버깅 페이지를 참조하세요.

다음 단계