GitLab 내부 사용자는 Database Lab Engine(DLE)과 postgres.ai에 접근해 복제된 프로덕션 데이터에서 데이터베이스 쿼리 성능을 테스트할 수 있습니다. 일반적인 읽기 전용 프로덕션 복제본과 달리 DLE에서는 행을 생성, 수정, 삭제할 수도 있습니다. 또한 격리된 프로덕션 데이터 사본에서 인덱스나 칼럼 추가와 같은 스키마 변경의 성능도 테스트할 수 있습니다. 데이터베이스 스냅샷은 보통 4시간마다 새로 생성됩니다.

Database Lab 빠른 시작#

1. 콘솔을 방문합니다.
2. Sign in with Google을 선택합니다. (GitLab 이 아닙니다. 프로젝트에 연결하려면 Google SSO가 필요합니다.)
3. 로그인한 뒤 GitLab 조직을 선택하고, 사이드바에서 "Joe Bot" 을 선택한 다음 "Ask Joe" 로 이동합니다.
4. 테스트 대상 데이터베이스를 선택합니다.
   • GitLab 프로젝트의 쿼리는 대부분 gitlab-production-main에서 실행됩니다.
   • CI 테이블에 대한 쿼리라면 gitlab-production-ci를 선택합니다.
   • 컨테이너 레지스트리에 대한 쿼리라면 gitlab-production-registry를 선택합니다.
5. 채팅 입력란에 explain 를 입력해 플랜을 확인합니다.

Database Lab Engine 접근#

DLE 접근은 다음 경우에 유용합니다.

• 데이터베이스 리뷰어 및 메인테이너.
• 데이터베이스에 큰 영향을 주는 머지 리퀘스트를 작업하는 엔지니어.

DLE 서비스는 다음과 같이 이용할 수 있습니다.

• Postgres.ai 웹 콘솔에서 쿼리를 테스트합니다. 직원은 GitLab Google 계정으로 두 서비스 모두에 접근합니다. 쿼리 테스트는 그곳에서 실행한 쿼리의 EXPLAIN(analyze, buffers) 플랜을 제공합니다.
• Postgres.ai CLI로 터미널에서 쿼리를 테스트합니다. 액세스 요청은 필요하지 않습니다.
• 머지 리퀘스트의 일부로 job을 실행해 마이그레이션을 테스트합니다.
• 프로덕션 복제본 대신 DLE에 psql로 직접 접근합니다. 승인된 사용자만 사용할 수 있습니다. psql 접근을 요청하려면 액세스 요청을 등록합니다.

추가 지원이 필요하면 #database Slack 채널을 이용합니다.

쿼리 테스트#

Database Lab의 쿼리 분석 기능은 다음 두 가지 방법으로 사용할 수 있습니다.

• Postgres.ai 웹 콘솔에서 사용합니다. 본인이 실행한 명령만 표시됩니다.
• Postgres.ai CLI로 터미널에서 사용합니다.

Postgres.ai CLI 사용#

Postgres.ai CLI를 사용하면 액세스 요청이나 SSH 구성 없이 터미널에서 Joe 명령을 실행할 수 있습니다. 한 번에 많은 쿼리 플랜을 생성하거나, AI 에이전트와 스크립트가 플랜을 대신 생성할 때 CLI를 사용합니다.

CLI를 설정하는 방법은 다음과 같습니다.

1. postgresai npm 패키지를 설치합니다.

   npm install -g postgresai
   

   전역 설치 없이 CLI를 실행하려면 이후 명령에서 postgresai를 npx postgresai@latest로 바꿉니다.

2. Postgres.ai 계정으로 로그인합니다.

   postgresai login
   

   이 명령은 브라우저 창을 엽니다. Google로 로그인한 뒤 GitLab 조직을 선택합니다.

3. 선택 사항. Joe 명령을 실행할 수 있는 프로젝트를 나열한 다음 기본값을 설정합니다.

   postgresai projects
   postgresai set-default-project gitlab-production-main
   

Joe 명령을 실행하려면 프로젝트 이름과 함께 postgresai joe에 전달합니다.

postgresai joe explain "SELECT * FROM application_settings" --project gitlab-production-main

CLI는 명령이 완료될 때까지 최대 25초(기본 예산)를 기다립니다. 명령이 더 오래 걸리면 CLI는 대신 명령 ID를 출력합니다. 나중에 결과를 가져오려면 이 ID를 사용합니다.

postgresai joe result <command-id>

기본 프로젝트를 설정해 두었다면 --project 옵션을 생략할 수 있습니다.

이어지는 절에서 설명하는 explain, exec, reset 명령은 CLI에서도 웹 콘솔과 동일하게 동작합니다. \d 메타 명령은 대신 postgresai joe describe <object_name>을 사용합니다. 스크립트와 AI 에이전트를 위해 기계가 읽을 수 있는 출력이 필요하면 --json 플래그를 추가합니다.

이 npm 패키지는 더 짧은 pgai 명령도 함께 설치하며, 이는 pgai Ruby gem과는 무관합니다.

쿼리 플랜 생성#

쿼리 플랜은 데이터베이스 리뷰 과정에서 빼놓을 수 없는 요소입니다. 이 플랜이 있으면 해당 쿼리가 GitLab.com에서 충분한 성능을 낼 수 있는지 빠르게 판단할 수 있습니다. explain 명령을 실행하면 explain 플랜과 함께 더 자세한 쿼리 분석이 담긴 Postgres.ai 콘솔 링크가 생성됩니다. 예를 들어 EXPLAIN SELECT * FROM application_settings를 실행하면 다음과 같이 동작합니다.

1. 데이터베이스 클론을 대상으로 explain (analyze, buffers) select * from application_settings;를 실행합니다.
2. 실행 결과의 타이밍과 버퍼 세부 정보를 응답합니다.
3. 결과에 대한 상세하고 공유 가능한 보고서를 제공합니다.

스키마 변경하기#

쿼리를 테스트하다 보면 추가한 쿼리의 성능을 높이기 위해 인덱스나 다른 스키마 변경이 필요하다는 것을 알게 될 때가 있습니다. 이러한 쿼리를 테스트하려면 exec 명령을 실행합니다. 예를 들어 다음 명령을 실행하면

exec CREATE INDEX on application_settings USING btree (restricted_visibility_levels)

지정한 인덱스가 테이블에 생성됩니다. 이후 새 인덱스를 활용해 쿼리를 테스트할 수 있습니다. exec는 결과를 반환하지 않고 쿼리 실행에 걸린 시간만 반환합니다.

클론 초기화#

파괴적인 쿼리를 실행했거나 효과 없는 인덱스를 만드는 등 변경이 많이 쌓이면 처음부터 다시 시작해야 합니다. 지정한 클론을 초기화하려면 reset을 실행합니다.

인덱스 확인#

Database Lab에서 메타 명령 \d <index_name>으로 인덱스 상태를 확인할 수 있습니다.

유의 사항은 다음과 같습니다.

• 인덱스는 main과 ci 데이터베이스 양쪽에 생성되므로, 해당 테이블의 gitlab_schema에 맞는 인스턴스를 사용해야 합니다. 예를 들어 인덱스가 ci_builds에 추가되었다면 gitlab-production-ci를 사용합니다.
• Database Lab은 보통 몇 시간 정도 지연됩니다. 더 최신 정보가 필요하다면 Teleport를 통해 복제본 접근을 요청할 수 있습니다.

예를 들어 \d index_design_management_designs_on_project_id를 실행하면 다음이 출력됩니다.

Index "public.index_design_management_designs_on_project_id"
   Column   |  Type   | Key? | Definition
------------+---------+------+------------
 project_id | integer | yes  | project_id
btree, for table "public.design_management_designs"

유효하지 않은 인덱스라면 다음과 같이 출력 끝에 invalid가 붙습니다.

Index "public.index_design_management_designs_on_project_id"
   Column   |  Type   | Key? | Definition
------------+---------+------+------------
 project_id | integer | yes  | project_id
btree, for table "public.design_management_designs", invalid

인덱스가 없으면 JoeBot은 다음과 같은 오류를 발생시킵니다.

ERROR: psql error: psql:/tmp/psql-query-932227396:1: error: Did not find any relation named "no_index".

마이그레이션 테스트#

마이그레이션 테스트에 관한 정보는 데이터베이스 마이그레이션 테스트 문서를 참고합니다.

psql로 콘솔 접근#

Database Lab 인스턴스에 접근하려면 다음 조건을 충족해야 합니다.

• chef-repo에 SSH 키와 db-lab 권한이 포함된 사용자 데이터 백 항목이 있어야 합니다. 예: MR.
• AllFeaturesUser는 postgres.ai에서 기본으로 부여되는 권한입니다. 아직 없다면 #g_database_frameworks Slack 채널에 글을 올리고 @db-team을 태그해 권한 추가를 요청합니다.
• ssh를 다음과 같이 구성합니다.

Host lb-bastion.db-lab.gitlab.com
  # Typically, the username is `name` in `name@gitlab.com`
  # or your GitLab's username.
  # Check with the access provisioner if it is not working.
  # If not provided, defaults to your system username.
  User YOUR_USERNAME_HERE

  # Path to your SSH key. Adjust or remove if using a different key or SSH agent.
  IdentityFile ~/.ssh/id_ed25519

Host *.gitlab-db-lab.internal
  User YOUR_USERNAME_HERE  # Same as above.
  PreferredAuthentications publickey
  IdentityFile ~/.ssh/id_ed25519  # Same as above.
  ProxyCommand ssh lb-bastion.db-lab.gitlab.com -W %h:%p

Postgres.ai 인스턴스 페이지를 통한 수동 접근#

psql 접근 권한이 있는 팀원은 psql로 클론에 직접 접근할 수 있습니다. psql 접근 권한이 있으면 메타데이터뿐 아니라 데이터도 볼 수 있습니다.

psql로 클론에 연결하는 방법은 다음과 같습니다.

1. 원하는 인스턴스에서 클론을 생성합니다.
   1. Clone ID를 입력합니다. yourname-testing-gitlabissue처럼 클론을 고유하게 식별할 수 있는 값을 사용합니다.
   2. Database username과 Database password를 입력합니다. psql 이 클론에 연결할 때 사용합니다.
   3. 클론을 보존해야 한다면 Enable deletion protection을 선택합니다. 이 옵션은 가급적 선택하지 않습니다. 클론은 12시간 후에 제거됩니다.
2. Postgres.ai 웹 인터페이스의 Clone details 페이지에서 해당 클론의 SSH 포트 포워딩을 시작하는 명령을 복사해 실행합니다.
   1. 이 명령은 -N 플래그와 함께 실행하도록 안내되는데, 이는 셸을 시작하지 않는다는 뜻이므로 정상적으로 실행되더라도 출력이 없습니다.
   2. 선택적으로 ~/.ssh/config에 LogLevel DEBUG3을 추가하면 상세한 디버깅 정보를 출력할 수 있습니다.
   3. 명령을 실행한 뒤에는 포트 포워딩을 유지하기 위해 그대로 실행 상태로 두고, 새 터미널 탭을 열어 다음 단계를 진행합니다.
3. Postgres.ai 웹 인터페이스의 Clone details 페이지에서 psql 연결 문자열을 복사해 실행합니다. 설정 시 제공된 비밀번호를 사용하고 dbname을 gitlabhq_dblab으로 설정합니다(또는 같은 연결 문자열에서 dbname=postgres로 지정해 psql -l을 실행하면 사용 가능한 데이터베이스를 확인할 수 있습니다).

연결한 뒤에는 프로덕션의 일반적인 psql 콘솔처럼 클론을 사용하되, 격리된 쓰기 가능 환경이라는 이점과 안전성을 함께 누릴 수 있습니다.

pgai Ruby gem을 통한 간편 접근#

pgai Ruby gem 사용 방법은 pgai Ruby gem을 사용한 Database Lab 접근을 참고합니다.