Compute Engine에서 psql 클라이언트 연결

이 페이지에서는 Compute Engine 인스턴스에 설치된 psql 클라이언트를 사용하여 Cloud SQL에 연결하는 방법을 설명합니다.

비공개 IP, 공개 IP, Cloud SQL 프록시 또는 프록시 Docker 이미지를 사용할 수 있습니다.

시작하기 전에

Cloud SQL 인스턴스에 연결하기 위해서는 인스턴스에 기본 데이터베이스 사용자(postgre)가 있어야 합니다.

이 태스크에는 Compute Engine 인스턴스를 설정하는 방법에 대한 안내가 포함되어 있지 않습니다. Compute Engine 인스턴스 만들기 및 구성에 도움이 필요한 경우 Compute Engine 문서를 참조하세요.

비공개 IP를 사용하여 연결

비공개 IP를 사용하여 Compute Engine 인스턴스에서 Cloud SQL에 연결하려면 비공개 서비스 액세스가 사용 환경에 맞게 설정되어 있고 Cloud SQL 인스턴스가 비공개 IP를 사용할 수 있도록 구성되어 있어야 합니다. Compute Engine 인스턴스는 Cloud SQL 인스턴스와 같은 리전에 있어야 하며 비공개로 연결할 수 있도록 구성된 네트워크에 있어야 합니다. 자세히 알아보기

  1. 비공개 IP 연결 구성의 안내에 따라 인스턴스에서 비공개 IP를 사용하도록 구성합니다.
  2. Compute Engine 인스턴스와의 터미널 연결을 엽니다.

    인스턴스의 운영체제에 따라 적절한 안내를 사용합니다.

  3. psql 클라이언트가 Compute Engine 인스턴스에 아직 설치되어 있지 않으면 지금 설치합니다.

    Debian/Ubuntu

    패키지 관리자에서 psql 클라이언트를 설치합니다.

    sudo apt-get update
    sudo apt-get install postgresql-client
    

    CentOS/RHEL

    패키지 관리자에서 psql 클라이언트를 설치합니다.

    sudo yum install postgresql
    

    openSUSE

    패키지 관리자에서 psql 클라이언트를 설치합니다.

    sudo zypper install postgresql
    

    기타 플랫폼

    1. PostgreSQL 다운로드 페이지에서 플랫폼에 맞는 PostgreSQL Core Distribution을 다운로드합니다.
      Core Distribution에는 psql 클라이언트가 포함되어 있습니다.
    2. 다운로드 페이지의 안내에 따라 PostgreSQL 데이터베이스를 설치합니다.
  4. psql 클라이언트에 연결합니다.
    psql -h [CLOUD_SQL_PRIVATE_IP_ADDR] -U postgres
    

공개 IP 주소를 사용하여 연결

  1. Compute Engine 인스턴스에 아직 고정 IPv4 IP 주소가 없다면 추가합니다. IPv6을 사용하여 Compute Engine에 연결할 수는 없습니다. 고정 IP 주소를 추가하는 방법에 대한 자세한 내용은 Compute Engine 문서의 새 고정 외부 IP 주소 예약하기를 참조하세요.
  2. Compute Engine 인스턴스의 고정 IP 주소를 Cloud SQL 인스턴스에 연결할 수 있는 네트워크로 승인합니다.

    자세한 내용은 IP 연결을 위한 액세스 구성을 참조하세요.

  3. Compute Engine 인스턴스와의 터미널 연결을 엽니다.

    인스턴스의 운영체제에 따라 적절한 안내를 사용합니다.

  4. psql 클라이언트가 Compute Engine 인스턴스에 아직 설치되어 있지 않으면 지금 설치합니다.

    Debian/Ubuntu

    패키지 관리자에서 psql 클라이언트를 설치합니다.

    sudo apt-get update
    sudo apt-get install postgresql-client
    

    CentOS/RHEL

    패키지 관리자에서 psql 클라이언트를 설치합니다.

    sudo yum install postgresql
    

    openSUSE

    패키지 관리자에서 psql 클라이언트를 설치합니다.

    sudo zypper install postgresql
    

    기타 플랫폼

    1. PostgreSQL 다운로드 페이지에서 플랫폼에 맞는 PostgreSQL Core Distribution을 다운로드합니다.
      Core Distribution에는 psql 클라이언트가 포함되어 있습니다.
    2. 다운로드 페이지의 안내에 따라 PostgreSQL 데이터베이스를 설치합니다.
  5. psql 클라이언트에 연결합니다.
    psql -h [CLOUD_SQL_PUBLIC_IP_ADDR] -U postgres
    
    다음 gcloud 명령어를 실행하여 CLOUD_SQL_PUBLIC_IP_ADDR을 찾습니다.
    gcloud sql instances list
    

    SSL을 사용하여 연결하는 방법의 예시는 SSL로 연결하기를 참조하세요.

  6. psql 프롬프트가 표시됩니다.
  7. 사용되지 않은 연결을 활성 상태로 유지해야 하면 TCP 연결 유지를 설정합니다.

    자세한 내용은 Compute Engine 문서의 인스턴스 및 인터넷 간의 커뮤니케이션을 참조하세요.

    인스턴스의 연결은 자동으로 유지됩니다.

도움이 필요하신가요? 프록시 문제를 해결하는 데 도움이 필요하면 Cloud SQL 프록시 연결 문제해결 또는 Cloud SQL 지원 페이지를 참조하세요.

Cloud SQL 프록시를 사용하여 연결

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

    API 사용 설정

  2. 프록시에 서비스 계정을 만듭니다.
  3. 서비스 계정을 사용하여 프록시 사용자 인증 정보를 제공하는 경우 충분한 권한을 부여해야 합니다. 세분화된 Identity Access and Management(IAM) 역할을 사용하여 Cloud SQL 권한을 관리하는 경우 서비스 계정에 cloudsql.instances.connect 권한이 있는 역할을 부여해야 합니다. 이 권한이 포함된 사전 정의된 Cloud SQL의 역할은 다음과 같습니다.

    • Cloud SQL 클라이언트
    • Cloud SQL 편집자
    • Cloud SQL 관리자

    기존 프로젝트 역할(뷰어, 편집자, 소유자)을 사용하는 경우 서비스 계정에 최소한 편집자 역할이 있어야 합니다.

    1. Google Cloud Console의 서비스 계정 페이지로 이동합니다.

      서비스 계정 페이지로 이동

    2. Cloud SQL 인스턴스가 포함된 프로젝트를 선택합니다.
    3. 서비스 계정 만들기를 클릭합니다.
    4. 서비스 계정 만들기 대화상자에 서비스 계정을 설명하는 이름을 입력합니다.
    5. 역할에서 다음 중 하나를 선택합니다.
      • Cloud SQL > Cloud SQL 클라이언트
      • Cloud SQL > Cloud SQL 편집자
      • Cloud SQL > Cloud SQL 관리자

      또는 프로젝트 > 편집자를 선택하여 기본 편집자 역할을 사용할 수 있습니다. 하지만 편집자 역할은 Google Cloud 전반에 대한 권한을 가집니다.

      이러한 역할이 표시되지 않으면 Google Cloud 사용자에게 resourcemanager.projects.setIamPolicy 권한이 없는 것일 수 있습니다. Google Cloud Console의 IAM 페이지로 이동하고 사용자 ID를 검색하여 권한을 확인할 수 있습니다.

    6. 서비스 계정 ID를 고유하고 알아볼 수 있는 값으로 변경합니다.
    7. 새 비공개 키 제공을 클릭하고 키 유형이 JSON인지 확인합니다.
    8. 만들기를 클릭합니다.

      비공개 키 파일이 머신에 다운로드됩니다. 파일을 다른 위치로 이동할 수 있습니다. 키 파일을 안전하게 보관하세요.

  4. Compute Engine 인스턴스가 Cloud SQL 인스턴스와 다른 프로젝트에 있는 경우, Cloud SQL 인스턴스가 포함된 프로젝트에서 서비스 계정에 적절한 권한이 있는지 확인합니다.
    1. Google Cloud Console에서 Compute Engine 인스턴스 목록으로 이동합니다.

      Compute Engine 인스턴스 목록으로 이동

    2. 필요한 경우 Compute Engine 인스턴스와 연결된 프로젝트를 선택합니다.
    3. Compute Engine 인스턴스를 선택하여 속성을 표시합니다.
    4. Compute Engine 인스턴스 속성에서 서비스 계정의 이름을 복사합니다.
    5. Google Cloud Console에서 IAM 및 관리자 프로젝트 페이지로 이동합니다.

      IAM 및 관리자 프로젝트 페이지로 이동

    6. Cloud SQL 인스턴스가 포함된 프로젝트를 선택합니다.
    7. 서비스 계정 이름을 검색합니다.
    8. 이미 서비스 계정이 있고 이 계정의 역할에 cloudsql.instances.connect 권한이 포함되어 있으면 4단계를 진행합니다.

      Cloud SQL Client, Cloud SQL Editor, Cloud SQL Admin 역할은 모두 기존 EditorOwner 프로젝트 역할과 마찬가지로 필요한 권한을 제공합니다.

    9. 그렇지 않은 경우 추가를 클릭하여 서비스 계정을 추가합니다.
    10. 구성원 추가 대화상자에서 서비스 계정 이름을 지정하고 cloudsql.instances.connect 권한이 있는 역할을 선택합니다. 뷰어를 제외하고 사전 정의된 모든 Cloud SQL 역할을 선택할 수 있습니다.

      또는 프로젝트 > 편집자를 선택하여 기본 편집자 역할을 사용할 수 있습니다. 하지만 편집자 역할은 Google Cloud 전반에 대한 권한을 가집니다.

      이러한 역할이 표시되지 않으면 Google Cloud 사용자에게 resourcemanager.projects.setIamPolicy 권한이 없는 것일 수 있습니다. Google Cloud Console의 IAM 페이지로 이동하고 사용자 ID를 검색하여 권한을 확인할 수 있습니다.

    11. 추가를 클릭합니다.

      이제 지정한 역할을 포함한 서비스 계정이 나열된 것을 볼 수 있습니다.

  5. Compute Engine 인스턴스와의 터미널 연결을 엽니다.

    인스턴스의 운영체제에 따라 적절한 안내를 사용합니다.

  6. Compute Engine 인스턴스가 RHEL 또는 CentOS 공개 이미지를 실행할 경우, SELinux가 프록시 연결을 차단할 수 있습니다. 이 경우에는 SELinux 기능이 연결을 허용하도록 구성해야 합니다.

    RHEL과 관련한 SELinux에 대한 자세한 내용은 RHEL 문서를 참조하세요. CentOS용 SELinux에 대한 자세한 내용은 CentOS 문서를 참조하세요.

  7. psql 클라이언트가 아직 설치되어 있지 않다면 Compute Engine 인스턴스에 설치합니다.

    Debian/Ubuntu

    패키지 관리자에서 psql 클라이언트를 설치합니다.

    sudo apt-get update
    sudo apt-get install postgresql-client
    

    CentOS/RHEL

    패키지 관리자에서 psql 클라이언트를 설치합니다.

    sudo yum install postgresql
    

    openSUSE

    패키지 관리자에서 psql 클라이언트를 설치합니다.

    sudo zypper install postgresql
    

    기타 플랫폼

    1. PostgreSQL 다운로드 페이지에서 플랫폼에 맞는 PostgreSQL Core Distribution을 다운로드합니다.
      Core Distribution에는 psql 클라이언트가 포함되어 있습니다.
    2. 다운로드 페이지의 안내에 따라 PostgreSQL 데이터베이스를 설치합니다.
  8. Compute Engine 인스턴스에 Cloud SQL 프록시를 설치합니다.

    Linux 64비트

    1. 프록시를 다운로드합니다.
      wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy
      
    2. 프록시를 실행 가능하도록 합니다.
      chmod +x cloud_sql_proxy
      

    Linux 32비트

    1. 프록시를 다운로드합니다.
      wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy
      
    2. 프록시를 실행 가능하도록 합니다.
      chmod +x cloud_sql_proxy
      

    Windows 64비트

    https://dl.google.com/cloudsql/cloud_sql_proxy_x64.exe를 마우스 오른쪽 버튼으로 클릭하고 다른 이름으로 링크 저장을 선택하여 프록시를 다운로드합니다. 파일 이름을 cloud_sql_proxy.exe로 바꿉니다.

    Windows 32비트

    https://dl.google.com/cloudsql/cloud_sql_proxy_x86.exe를 마우스 오른쪽 버튼으로 클릭하고 다른 이름으로 링크 저장을 선택하여 프록시를 다운로드합니다. 파일 이름을 cloud_sql_proxy.exe로 바꿉니다.
    사용 중인 운영체제가 여기에 포함되어 있지 않으면 소스에서 프록시를 컴파일할 수도 있습니다.

  9. 프록시를 시작합니다.

    언어와 환경에 따라 TCP 소켓이나 Unix 소켓을 사용하여 프록시를 시작할 수 있습니다.

    TCP 소켓

    1. 인스턴스 세부정보 페이지에서 인스턴스 연결 이름을 복사합니다.

      예를 들면 myproject:myregion:myinstance입니다.

    2. 서비스 계정을 사용하여 프록시를 인증하는 경우 서비스 계정을 만들 때 생성된 비공개 키 파일의 클라이언트 머신 내 위치를 기록해 둡니다.
    3. 프록시를 시작합니다.

      사용할 수 있는 프록시 호출 문자열은 다음과 같습니다.

      • Cloud SDK 인증 사용:
        ./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:5432
        
        지정된 포트는 로컬 데이터베이스 서버 등에서 이미 사용하지 않는 포트여야 합니다.
      • 서비스 계정 사용 및 명시적으로 인스턴스 연결 이름 포함(프로덕션 환경에 권장):
        ./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:5432 \
                          -credential_file=<PATH_TO_KEY_FILE> &
        

      프록시 옵션에 대한 자세한 내용은 프록시 인증 옵션인스턴스 지정 옵션을 참조하세요.

    Unix 소켓

    1. 명시적 인스턴스 지정을 사용하는 경우 인스턴스 세부정보 페이지에서 인스턴스 연결 이름을 복사합니다.
    2. 프록시 소켓이 위치할 디렉터리를 만듭니다.
      sudo mkdir /cloudsql; sudo chmod 777 /cloudsql
    3. 서비스 계정을 사용하여 프록시를 인증하는 경우 서비스 계정을 만들 때 생성된 비공개 키 파일의 클라이언트 머신 내 위치를 기록해 둡니다.
    4. 새 터미널 창을 열고 프록시를 시작합니다.

      사용할 수 있는 프록시 호출 문자열은 다음과 같습니다.

      • 서비스 계정 사용 및 명시적으로 인스턴스 연결 이름 포함(프로덕션 환경에 권장):
        ./cloud_sql_proxy -dir=/cloudsql -instances=<INSTANCE_CONNECTION_NAME> \
                          -credential_file=<PATH_TO_KEY_FILE> &
      • Cloud SDK 인증과 자동 인스턴스 검색 사용:
        ./cloud_sql_proxy -dir=/cloudsql &

      프록시 출력을 다른 프로그램의 출력과 별도로 모니터링할 수 있도록 자체 터미널에서 프록시를 시작하는 것이 가장 좋습니다.

      프록시 옵션에 대한 자세한 내용은 프록시 인증 옵션인스턴스 지정 옵션을 참조하세요.

    5. Unix 소켓을 사용하여 Cloud SQL 프록시로 Cloud SQL에 연결할 때 소켓 파일 이름의 길이가 시스템 제한을 초과하지 않는지 확인합니다. 시스템에 따라 다르지만 이는 일반적으로 91~108자입니다. Linux에서 길이는 일반적으로 108자로 정의되며 다음 명령어를 사용하여 확인할 수 있습니다.
      cat /usr/include/linux/un.h | grep "define UNIX_PATH_MAX"
  10. psql 세션을 시작합니다.

    사용하는 연결 문자열은 TCP 소켓과 UNIX 소켓 중에서 어떤 소켓을 사용하여 프록시를 시작했는지에 따라 다릅니다.

    TCP 소켓

    1. psql 클라이언트를 시작합니다.
      psql "host=127.0.0.1 sslmode=disable dbname=<DB_NAME> user=<USER_NAME>"
      

      sslmode 매개변수가 disable로 설정되어 있어도 프록시는 암호화된 연결을 제공합니다.

      TCP 소켓을 사용하여 연결하면 127.0.0.1을 통해 프록시에 액세스합니다.

    2. 메시지가 표시되면 비밀번호를 입력합니다.
    3. psql 프롬프트가 표시됩니다.

    Unix 소켓

    1. psql 클라이언트를 시작합니다.
      psql "sslmode=disable host=/cloudsql/<INSTANCE_CONNECTION_NAME> user=<USERNAME>"
      

      sslmode 매개변수가 disable로 설정되어 있어도 프록시는 암호화된 연결을 제공합니다.

    2. 비밀번호를 입력합니다.
    3. psql 프롬프트가 표시됩니다.

도움이 필요하신가요? 프록시 문제를 해결하는 데 도움이 필요하면 Cloud SQL 프록시 연결 문제해결 또는 Cloud SQL 지원 페이지를 참조하세요.

다음 단계