PostgreSQL용 Cloud SQL을 사용하여 Cloud Run에 풀 스택 JavaScript 애플리케이션 배포

1. 개요

Cloud Run은 Google의 확장 가능한 인프라에서 직접 코드를 실행할 수 있게 해주는 완전 관리형 플랫폼입니다. 이 Codelab에서는 Cloud Run의 Next.js 애플리케이션을 PostgreSQL용 Cloud SQL 데이터베이스에 연결하는 방법을 보여줍니다.

이 실습에서는 다음 작업을 수행하는 방법을 배웁니다.

  • PostgreSQL용 Cloud SQL 인스턴스 만들기 (Private Service Connect를 사용하도록 구성됨)
  • Cloud SQL 데이터베이스에 연결되는 애플리케이션을 Cloud Run에 배포
  • Gemini Code Assist를 사용하여 애플리케이션에 기능 추가

2. 기본 요건

  1. 아직 Google 계정이 없다면 Google 계정을 만들어야 합니다.
    • 직장 또는 학교 계정이 아닌 개인 계정을 사용합니다. 직장 및 학교 계정에는 이 실습에 필요한 API를 사용 설정할 수 없도록 하는 제한사항이 있을 수 있습니다.

3. 프로젝트 설정

  1. Google Cloud 콘솔에 로그인합니다.
  2. Cloud 콘솔에서 결제를 사용 설정합니다.
    • 이 실습을 완료하는 데 드는 Cloud 리소스 비용은 미화 1달러 미만입니다.
    • 이 실습의 끝에 있는 단계에 따라 리소스를 삭제하면 추가 비용이 발생하지 않습니다.
    • 신규 사용자는 미화 300달러 상당의 무료 체험판을 이용할 수 있습니다.
  3. 새 프로젝트를 만들거나 기존 프로젝트를 재사용합니다.

4. Cloud Shell 편집기 열기

  1. Cloud Shell 편집기로 이동합니다.
  2. 터미널이 화면 하단에 표시되지 않으면 다음과 같이 엽니다.
    • 햄버거 메뉴 햄버거 메뉴 아이콘를 클릭합니다.
    • 터미널을 클릭합니다.
    • 새 터미널을 클릭합니다.Cloud Shell 편집기에서 새 터미널 열기
  3. 터미널에서 다음 명령어를 사용하여 프로젝트를 설정합니다.
    • 형식:
      gcloud config set project [PROJECT_ID]
      
    • 예:
      gcloud config set project lab-project-id-example
      
    • 프로젝트 ID를 기억할 수 없는 경우 다음 안내를 따르세요.
      • 다음을 사용하여 모든 프로젝트 ID를 나열할 수 있습니다.
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
        
      Cloud Shell 편집기 터미널에서 프로젝트 ID 설정
  4. 승인하라는 메시지가 표시되면 승인을 클릭하여 계속 진행합니다. Cloud Shell을 승인하려면 클릭합니다.
  5. 다음 메시지가 표시되어야 합니다.
    Updated property [core/project].
    
    WARNING이 표시되고 Do you want to continue (Y/N)? 메시지가 표시되면 프로젝트 ID를 잘못 입력했을 가능성이 큽니다. N를 누른 다음 Enter를 누르고 gcloud config set project 명령어를 다시 실행해 봅니다.

5. API 사용 설정

터미널에서 API를 사용 설정합니다.

gcloud services enable \
  compute.googleapis.com \
  sqladmin.googleapis.com \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  networkconnectivity.googleapis.com \
  servicenetworking.googleapis.com \
  cloudaicompanion.googleapis.com

승인하라는 메시지가 표시되면 승인을 클릭하여 계속 진행합니다. Cloud Shell을 승인하려면 클릭합니다.

이 명령어를 완료하는 데 몇 분 정도 걸릴 수 있지만 결국 다음과 유사한 성공 메시지가 표시됩니다.

Operation "operations/acf.p2-73d90d00-47ee-447a-b600" finished successfully.

6. 서비스 계정 설정

Cloud SQL에 연결할 수 있는 올바른 권한이 있도록 Cloud Run에서 사용할 Google Cloud 서비스 계정을 만들고 구성합니다.

  1. 다음과 같이 gcloud iam service-accounts create 명령어를 실행하여 새 서비스 계정을 만듭니다.
    gcloud iam service-accounts create quickstart-service-account \
      --display-name="Quickstart Service Account"
    
  2. 다음과 같이 gcloud projects add-iam-policy-binding 명령어를 실행하여 방금 만든 Google Cloud 서비스 계정에 로그 작성자 역할을 추가합니다.
    gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
      --member="serviceAccount:quickstart-service-account@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com" \
      --role="roles/logging.logWriter"
    

7. Cloud SQL 인스턴스 만들기

  1. Private Service Connect를 사용하여 Cloud Run에서 Cloud SQL로의 네트워크 연결을 허용하는 서비스 연결 정책 만들기
    gcloud network-connectivity service-connection-policies create quickstart-policy \
        --network=default \
        --project=${GOOGLE_CLOUD_PROJECT} \
        --region=us-central1 \
        --service-class=google-cloud-sql \
        --subnets=https://www.googleapis.com/compute/v1/projects/${GOOGLE_CLOUD_PROJECT}/regions/us-central1/subnetworks/default
    
  2. 데이터베이스의 고유한 비밀번호 생성
    export DB_PASSWORD=$(openssl rand -base64 20)
    
  3. gcloud sql instances create 명령어를 실행하여 Cloud SQL 인스턴스 만들기
    gcloud sql instances create quickstart-instance \
        --project=${GOOGLE_CLOUD_PROJECT} \
        --root-password=${DB_PASSWORD} \
        --database-version=POSTGRES_17 \
        --tier=db-perf-optimized-N-2 \
        --region=us-central1 \
        --ssl-mode=ENCRYPTED_ONLY \
        --no-assign-ip \
        --enable-private-service-connect \
        --psc-auto-connections=network=projects/${GOOGLE_CLOUD_PROJECT}/global/networks/default
    

이 명령어를 완료하는 데 몇 분 정도 걸릴 수 있습니다.

  1. gcloud sql databases create 명령어를 실행하여 quickstart-instance 내에 Cloud SQL 데이터베이스를 만듭니다.
    gcloud sql databases create quickstart_db \
      --instance=quickstart-instance
    

8. 신청 준비

HTTP 요청에 응답하는 Next.js 애플리케이션을 준비합니다.

  1. task-app라는 새 Next.js 프로젝트를 만들려면 다음 명령어를 사용합니다.
    npx create-next-app@15.0.3 task-app \
      --ts \
      --eslint \
      --tailwind \
      --no-src-dir \
      --turbopack \
      --app \
      --no-import-alias
    
  2. create-next-app를 설치하라는 메시지가 표시되면 Enter를 눌러 계속 진행합니다.
    Need to install the following packages:
    create-next-app@15.0.3
    Ok to proceed? (y)
    
  3. 디렉터리를 task-app으로 변경합니다.
    cd task-app
    
  4. pg를 설치하여 PostgreSQL 데이터베이스와 상호작용합니다.
    npm install pg
    
  5. TypeScript Next.js 애플리케이션을 사용하려면 @types/pg를 개발 종속 항목으로 설치합니다.
    npm install --save-dev @types/pg
    
  6. actions.ts 파일을 생성합니다.
    touch app/actions.ts
    
  7. Cloud Shell 편집기에서 actions.ts 파일을 엽니다.
    cloudshell edit app/actions.ts
    
    이제 빈 파일이 화면 상단에 표시됩니다. 여기에서 이 actions.ts 파일을 수정할 수 있습니다. 화면 상단 섹션에 표시되는 코드
  8. 다음 코드를 복사하여 열려 있는 actions.ts 파일에 붙여넣습니다.
    'use server'
    import pg from 'pg';
    
    type Task = {
      id: string;
      title: string;
      status: 'IN_PROGRESS' | 'COMPLETE';
    };
    
    const { Pool } = pg;
    
    const pool = new Pool({
      host: process.env.DB_HOST,
      user: process.env.DB_USER,
      password: process.env.DB_PASSWORD,
      database: process.env.DB_NAME,
      ssl: {
        // @ts-expect-error require true is not recognized by @types/pg, but does exist on pg
        require: true,
        rejectUnauthorized: false, // required for self-signed certs
        // https://node-postgres.com/features/ssl#self-signed-cert
      }
    });
    
    const tableCreationIfDoesNotExist = async () => {
      await pool.query(`CREATE TABLE IF NOT EXISTS visits (
        id SERIAL NOT NULL,
        created_at timestamp NOT NULL,
        PRIMARY KEY (id)
      );`);
      await pool.query(`CREATE TABLE IF NOT EXISTS tasks (
        id SERIAL NOT NULL,
        created_at timestamp NOT NULL,
        status VARCHAR(255) NOT NULL default 'IN_PROGRESS',
        title VARCHAR(1024) NOT NULL,
        PRIMARY KEY (id)
      );`);
    }
    
    // CREATE
    export async function addNewTaskToDatabase(newTask: string) {
      await tableCreationIfDoesNotExist();
      await pool.query(`INSERT INTO tasks(created_at, status, title) VALUES(NOW(), 'IN_PROGRESS', $1)`, [newTask]);
      return;
    }
    
    // READ
    export async function getTasksFromDatabase() {
      await tableCreationIfDoesNotExist();
      const { rows } = await pool.query(`SELECT id, created_at, status, title FROM tasks ORDER BY created_at DESC LIMIT 100`);
      console.table(rows); // logs the last 5 visits on the server
      return rows; // sends the last 5 visits to the client
    }
    
    // UPDATE
    export async function updateTaskInDatabase(task: Task) {
      await tableCreationIfDoesNotExist();
      await pool.query(
        `UPDATE tasks SET status = $1, title = $2 WHERE id = $3`,
        [task.status, task.title, task.id]
      );
      return;
    }
    
    // DELETE
    export async function deleteTaskFromDatabase(taskId: string) {
      await tableCreationIfDoesNotExist();
      await pool.query(`DELETE FROM tasks WHERE id = $1`, [taskId]);
      return;
    }
    
  9. Cloud Shell 편집기에서 page.tsx 파일을 엽니다.
    cloudshell edit app/page.tsx
    
    이제 기존 파일이 화면 상단에 표시됩니다. 여기에서 이 page.tsx 파일을 수정할 수 있습니다. 화면 상단 섹션에 표시되는 코드
  10. page.tsx 파일의 기존 콘텐츠를 삭제합니다.
  11. 다음 코드를 복사하여 열려 있는 page.tsx 파일에 붙여넣습니다.
    'use client'
    import React, { useEffect, useState } from "react";
    import { addNewTaskToDatabase, getTasksFromDatabase, deleteTaskFromDatabase, updateTaskInDatabase } from "./actions";
    
    type Task = {
      id: string;
      title: string;
      status: 'IN_PROGRESS' | 'COMPLETE';
    };
    
    export default function Home() {
      const [newTaskTitle, setNewTaskTitle] = useState('');
      const [tasks, setTasks] = useState<Task[]>([]);
    
      async function getTasks() {
        const updatedListOfTasks = await getTasksFromDatabase();
        setTasks(updatedListOfTasks);
      }
    
      useEffect(() => {
        getTasks();
      }, []);
    
      async function addTask() {
        await addNewTaskToDatabase(newTaskTitle);
        await getTasks();
        setNewTaskTitle('');
      }
    
      async function updateTask(task: Task, newTaskValues: Partial<Task>) {
        await updateTaskInDatabase({ ...task, ...newTaskValues });
        await getTasks();
      }
    
      async function deleteTask(taskId: string) {
        await deleteTaskFromDatabase(taskId);
        await getTasks();
      }
    
      return (
        <main className="p-4">
          <h2 className="text-2xl font-bold mb-4">To Do List</h2>
          <div className="flex mb-4">
            <form onSubmit={handleSubmit} className="flex mb-8">
              <input
                type="text"
                placeholder="New Task Title"
                value={newTaskTitle}
                onChange={(e) => setNewTaskTitle(e.target.value)}
                className="flex-grow border border-gray-400 rounded px-3 py-2 mr-2 bg-inherit"
              />
              <button
                type="submit"
                className="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded text-nowrap"
              >
                Add New Task
              </button>
            </form>
          </div>
          <table className="w-full">
            <tbody>
              {tasks.map(function (task) {
                const isComplete = task.status === 'COMPLETE';
                return (
                  <tr key={task.id} className="border-b border-gray-200">
                    <td className="py-2 px-4">
                      <input
                        type="checkbox"
                        checked={isComplete}
                        onClick={() => updateTask(task, { status: isComplete ? 'IN_PROGRESS' : 'COMPLETE' })}
                        className="transition-transform duration-300 ease-in-out transform scale-100 checked:scale-125 checked:bg-green-500"
                      />
                    </td>
                    <td className="py-2 px-4">
                      <span className={`transition-all duration-300 ease-in-out ${isComplete ? 'line-through text-gray-400 opacity-50' : 'opacity-100'}`}>
                        {task.title}
                      </span>
                    </td>
                    <td className="py-2 px-4">
                      <button
                        onClick={() => deleteTask(task.id)}
                        className="bg-red-500 hover:bg-red-700 text-white font-bold py-2 px-4 rounded"
                      >
                        Delete
                      </button>
                    </td>
                  </tr>
                );
              })}
            </tbody>
          </table>
        </main>
      );
    }
    

이제 애플리케이션을 배포할 수 있습니다.

9. Cloud Run에 애플리케이션 배포

  1. 다음과 같이 gcloud projects add-iam-policy-binding 명령어를 실행하여 만들려는 Cloud Run 서비스의 Cloud Run 서비스 계정에 네트워크 사용자 역할을 추가합니다.
    gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
    --member "serviceAccount:service-$(gcloud projects describe ${GOOGLE_CLOUD_PROJECT} --format="value(projectNumber)")@serverless-robot-prod.iam.gserviceaccount.com" \
    --role "roles/compute.networkUser"
    
  1. 아래 명령어를 실행하여 Cloud Run에 애플리케이션을 배포합니다.
    gcloud run deploy helloworld \
      --region=us-central1 \
      --source=. \
      --set-env-vars DB_NAME="quickstart_db" \
      --set-env-vars DB_USER="postgres" \
      --set-env-vars DB_PASSWORD=${DB_PASSWORD} \
      --set-env-vars DB_HOST="$(gcloud sql instances describe quickstart-instance --project=${GOOGLE_CLOUD_PROJECT} --format='value(settings.ipConfiguration.pscConfig.pscAutoConnections.ipAddress)')" \
      --service-account="quickstart-service-account@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com" \
      --network=default \
      --subnet=default \
      --allow-unauthenticated
    
  2. 메시지가 표시되면 YEnter를 눌러 계속 진행하겠다고 확인합니다.
    Do you want to continue (Y/n)? Y
    

몇 분 후 애플리케이션에서 방문할 URL을 제공합니다.

URL로 이동하여 애플리케이션이 작동하는 모습을 확인합니다. URL을 방문하거나 페이지를 새로고침할 때마다 할 일 앱이 표시됩니다.

10. Gemini Code Assist로 기능 추가

이제 데이터베이스가 포함된 웹 앱을 배포했습니다. 다음으로 AI 지원 기능을 사용하여 next.js 앱에 새 기능을 추가합니다.

  1. Cloud Shell 편집기로 돌아가기
  2. page.tsx 다시 열기
    cd ~/task-app
    cloudshell edit app/page.tsx
    
  3. Cloud Shell 편집기에서 Gemini Code Assist로 이동합니다.
    • 화면 왼쪽의 툴바에서 Gemini 아이콘 Gemini Code Assist 아이콘을 클릭합니다.
    • 메시지가 표시되면 Google 계정 사용자 인증 정보로 로그인합니다.
    • 프로젝트를 선택하라는 메시지가 표시되면 이 Codelab Gemini 프로젝트 선택을 위해 만든 프로젝트를 선택합니다.
  4. 프롬프트 Add the ability to update the title of the task. The code in your output should be complete and working code.를 입력합니다. 응답에는 handleEditStarthandleEditCancel 함수를 추가하는 다음과 같은 스니펫이 포함되어야 합니다.
    const [editingTaskId, setEditingTaskId] = useState<string>('');
    const [editedTaskTitle, setEditedTaskTitle] = useState('');
    
    const handleEditStart = (task: Task) => {
      setEditingTaskId(task.id);
      setEditedTaskTitle(task.title);
    };
    
    const handleEditCancel = () => {
      setEditingTaskId('');
      setEditedTaskTitle('');
    };
    
    <td className="py-2 px-4">
      {editingTaskId === task.id ? (
        <form onSubmit={(e) => {
          e.preventDefault();
          updateTask(task, { title: editedTaskTitle });
        }}>
          <input
            type="text"
            value={editedTaskTitle}
            onChange={(e) => setEditedTaskTitle(e.target.value)}
            onBlur={() => handleEditCancel} // Handle clicking outside input
            className="border border-gray-400 rounded px-3 py-1 mr-2"
          />
            <button type="submit" className="text-green-600 hover:text-green-900 mr-1">Save</button>
        </form>
    
      ) : (
        <span onClick={() => handleEditStart(task)} className="cursor-pointer">
          {task.title}
        </span>
      )}
    </td>
    
  5. page.tsx를 Gemini Code Assist의 출력으로 바꿉니다. 다음은 작동하는 예시입니다.
    'use client'
    import React, { useEffect, useState } from "react";
    import { addNewTaskToDatabase, getTasksFromDatabase, deleteTaskFromDatabase, updateTaskInDatabase } from "./actions";
    
    type Task = {
      id: string;
      title: string;
      status: 'IN_PROGRESS' | 'COMPLETE';
    };
    
    export default function Home() {
      const [newTaskTitle, setNewTaskTitle] = useState('');
      const [tasks, setTasks] = useState<Task[]>([]);
      const [editingTaskId, setEditingTaskId] = useState<string>('');
      const [editedTaskTitle, setEditedTaskTitle] = useState('');
    
      async function getTasks() {
        const updatedListOfTasks = await getTasksFromDatabase();
        setTasks(updatedListOfTasks);
      }
    
      useEffect(() => {
        getTasks();
      }, []);
    
      async function addTask() {
        await addNewTaskToDatabase(newTaskTitle);
        await getTasks();
        setNewTaskTitle('');
      }
    
      async function updateTask(task: Task, newTaskValues: Partial<Task>) {
        await updateTaskInDatabase({ ...task, ...newTaskValues });
        await getTasks();
        setEditingTaskId(''); // Clear editing state after update
        setEditedTaskTitle('');
      }
    
      async function deleteTask(taskId: string) {
        await deleteTaskFromDatabase(taskId);
        await getTasks();
      }
    
      const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
        e.preventDefault();
        addTask();
      };
    
    
      const handleEditStart = (task: Task) => {
        setEditingTaskId(task.id);
        setEditedTaskTitle(task.title);
      };
    
      const handleEditCancel = () => {
        setEditingTaskId('');
        setEditedTaskTitle('');
      };
    
      return (
        <main className="p-4">
          <h2 className="text-2xl font-bold mb-4">To Do List</h2>
          <form onSubmit={handleSubmit} className="flex mb-8">
            <input
              type="text"
              placeholder="New Task Title"
              value={newTaskTitle}
              onChange={(e) => setNewTaskTitle(e.target.value)}
              className="flex-grow border border-gray-400 rounded px-3 py-2 mr-2 bg-inherit"
            />
            <button
              type="submit"
              className="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded text-nowrap"
            >
              Add New Task
            </button>
          </form>
          <table className="w-full">
            <tbody>
              {tasks.map(task => {
                const isComplete = task.status === 'COMPLETE';
                return (
                  <tr key={task.id} className="border-b border-gray-200">
                    <td className="py-2 px-4">
                      <input
                        type="checkbox"
                        checked={isComplete}
                        onClick={() => updateTask(task, { status: isComplete ? 'IN_PROGRESS' : 'COMPLETE' })}
                        className="transition-transform duration-300 ease-in-out transform scale-100 checked:scale-125 checked:bg-green-500"
                      />
                    </td>
                    <td className="py-2 px-4">
                      {editingTaskId === task.id ? (
                        <form 
                          onSubmit={(e) => {
                            e.preventDefault();
                            updateTask(task, { title: editedTaskTitle });
                          }}
                          className="flex"
                        >
                          <input
                            type="text"
                            value={editedTaskTitle}
                            onChange={(e) => setEditedTaskTitle(e.target.value)}
                            onBlur={() => handleEditCancel()} // Handle clicking outside input
                            className="flex-grow border border-gray-400 rounded px-3 py-1 mr-2 bg-inherit"
                          />
                          <button
                            type="submit"
                            className="bg-green-600 hover:bg-green-900 m-1 text-white font-bold py-2 px-4 rounded"
                          >
                            Save
                          </button>
                        </form>
                      ) : (
                        <span
                          onClick={() => handleEditStart(task)}
                          className={`transition-all duration-300 ease-in-out cursor-pointer ${isComplete ? 'line-through text-gray-400 opacity-50' : 'opacity-100'}`}
                        >
                          {task.title}
                        </span>
                      )}
                    </td>
                    <td className="py-2 px-4">
                      <button
                        onClick={() => deleteTask(task.id)}
                        className="bg-red-500 hover:bg-red-700 text-white font-bold py-2 px-4 rounded float-right"
                      >
                        Delete
                      </button>
                    </td>
                  </tr>
                );
              })}
            </tbody>
          </table>
        </main>
      );
    }
    

11. Cloud Run에 애플리케이션 다시 배포

  1. 아래 명령어를 실행하여 Cloud Run에 애플리케이션을 배포합니다.
    gcloud run deploy helloworld \
      --region=us-central1 \
      --source=. \
      --set-env-vars DB_NAME="quickstart_db" \
      --set-env-vars DB_USER="postgres" \
      --set-env-vars DB_PASSWORD=${DB_PASSWORD} \
      --set-env-vars DB_HOST="$(gcloud sql instances describe quickstart-instance --project=${GOOGLE_CLOUD_PROJECT} --format='value(settings.ipConfiguration.pscConfig.pscAutoConnections.ipAddress)')" \
      --service-account="quickstart-service-account@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com" \
      --network=default \
      --subnet=default \
      --allow-unauthenticated
    
  2. 메시지가 표시되면 YEnter를 눌러 계속 진행하겠다고 확인합니다.
    Do you want to continue (Y/n)? Y
    

12. 축하합니다

이 실습에서는 다음을 수행하는 방법을 알아봤습니다.

  • PostgreSQL용 Cloud SQL 인스턴스 만들기 (Private Service Connect를 사용하도록 구성됨)
  • Cloud SQL 데이터베이스에 연결되는 애플리케이션을 Cloud Run에 배포
  • Gemini Code Assist를 사용하여 애플리케이션에 기능 추가

삭제

Cloud SQL에는 무료 등급이 없으며 계속 사용하면 요금이 청구됩니다. Cloud 프로젝트를 삭제하여 추가 비용이 청구되지 않도록 할 수 있습니다.

Cloud Run에서는 서비스를 사용하지 않을 때 비용이 청구되지 않지만 Artifact Registry에 컨테이너 이미지를 저장하는 데 요금이 부과될 수 있습니다. Cloud 프로젝트를 삭제하면 해당 프로젝트 내에서 사용되는 모든 리소스에 대한 청구가 중단됩니다.

원하는 경우 프로젝트를 삭제합니다.

gcloud projects delete $GOOGLE_CLOUD_PROJECT

CloudShell 디스크에서 불필요한 리소스를 삭제할 수도 있습니다. 다음과 같은 작업을 할 수 있습니다.

  1. Codelab 프로젝트 디렉터리를 삭제합니다.
    rm -rf ~/task-app
    
  2. 경고 다음 작업은 실행취소할 수 없습니다. Cloud Shell에서 모든 항목을 삭제하여 공간을 확보하려면 전체 홈 디렉터리를 삭제하면 됩니다. 보관하려는 모든 항목이 다른 곳에 저장되어 있는지 확인합니다.
    sudo rm -rf $HOME