데이터베이스(Database)
대상 독자: 관리자(Admins)
출처: 문서
본문
대상 독자: 관리자(Admins)
요약(Summary)
이 가이드는 Backstage 데이터를 호스팅할 PostgreSQL 데이터베이스를 설정하는 방법을 안내해요. Backstage 앱 만들기 가이드를 따라 이미 스캐폴딩된 Backstage 앱이 있다고 가정해요.
이 튜토리얼이 끝나면 Backstage 설치에 연결된 동작하는 PostgreSQL 데이터베이스를 갖게 돼요.
전제 조건(Prerequisites)
이 가이드는 Linux 기반 운영체제에서 작업하는 기본 지식과 터미널 경험, 특히 apt-get, psql, yarn 명령에 대한 경험이 있다고 가정해요.
-
Linux, MacOS, Windows Subsystem for Linux 같은 Linux 기반 운영체제에 대한 접근
-
운영체제에 전제 조건을 설치할 권한이 올려진 계정
-
데이터베이스가 Backstage 앱과 같은 서버에서 호스팅되지 않는다면 PostgreSQL 포트가 접근 가능해야 함(기본값은
5432또는5433)
1. PostgreSQL 설치 및 구성
이미 데이터베이스를 구성했나요?
이미 PostgreSQL을 설치하고 스키마와 사용자를 만들었다면 2단계로 건너뛰어도 돼요.
PostgreSQL을 설치하고 Backstage 앱을 위해 설정해 봅시다. 먼저 SQL 서버를 실제로 설치해야 해요.
caution
아래 명령은 Linux용이에요. Linux가 아니거나 패키지 관리자에 문제가 있다면 PostgreSQL 설치 방법을 확인해 정리하세요.
sudo apt-get install postgresql
데이터베이스가 동작하는지 테스트하려면:
sudo -u postgres psql
아주 반가운 메시지가 보일 거예요. 예:
psql (12.9 (Ubuntu 12.9-0ubuntu0.20.04.1))
Type "help" for help.
postgres=#
이 튜토리얼에서는 기존 postgres 사용자를 사용할게요. 다음 단계는 이 사용자의 비밀번호를 설정하는 것이에요. 아래 명령에서 <secret>을 실제 비밀번호로 바꾸세요. 여기서 고른 비밀번호를 기록해 두세요. 나중에 필요해요.
postgres=# ALTER USER postgres PASSWORD '<secret>';
시작하기에 충분한 데이터베이스 관리 작업이 끝났어요. \q를 입력하고 엔터를 누른 다음, exit를 입력하고 엔터를 누르세요. 다음으로 클라이언트를 설치하고 구성해야 해요.
2. Backstage pg 클라이언트 구성하기
좋아하는 편집기로 app-config.yaml을 열고, 이전 단계의 자격 증명을 사용해 Backstage 앱 루트 디렉터리에 PostgreSQL 구성을 추가하세요.
app-config.yaml
backend:
database:
client: better-sqlite3
connection: ':memory:'
# config options: https://node-postgres.com/apis/client
client: pg
connection:
host: ${POSTGRES_HOST}
port: ${POSTGRES_PORT}
user: ${POSTGRES_USER}
password: ${POSTGRES_PASSWORD}
${...} 구문은 환경 변수를 나타내요. 구체적으로는:
-
POSTGRES_HOST- PostgreSQL 데이터베이스에 접근할 수 있는 URL/IP. PostgreSQL을 로컬로 설치했다면 아마 127.0.0.1일 거예요. -
POSTGRES_PORT- PostgreSQL 데이터베이스에 접근할 포트. PostgreSQL을 로컬로 설치했다면5432또는5433일 거예요. -
POSTGRES_USER- 위 SQL 명령의 사용자,postgres. -
POSTGRES_PASSWORD- 위 SQL 명령에서 설정한 비밀번호.
이것들을 채울 때 두 가지 선택이 있어요.
-
Backstage를 실행할 때 환경 변수를 사용하세요.
dotenv-cli나env-cmd같은 환경 변수 주입기를 쓰거나EXPORT POSTGRES_...=...로 변수를 직접 로드하는 방식이에요. -
전체
${POSTGRES_...}문자열을 앞서 파악한 값으로 바꾸세요. 이건 덜 안전한 옵션이지만 환경 변수에 경험이 많지 않다면 해 볼 가치가 있어요.
danger
두 번째 옵션(전체 문자열 바꾸기)을 선택한다면 app-config.yaml을 소스 제어에 커밋하지 않도록 주의하세요. 유출하고 싶지 않은 비밀번호가 들어 있을 수 있어요.
클라우드에서의 무비밀번호 PostgreSQL(Passwordless PostgreSQL in the Cloud)
PostgreSQL 서버를 무비밀번호 인증으로 클라우드에서 호스팅하고 싶다면, Microsoft Entra 인증을 사용하는 Azure Database for PostgreSQL이나 Cloud IAM을 사용하는 Google Cloud SQL for PostgreSQL을 쓸 수 있어요.
Entra 인증을 사용하는 Azure
연결 구성에서 password를 제거하고 type을 azure로 설정하세요.
선택적으로 tokenCredential을 다음 속성들과 함께 설정할 수 있어요. 자격 증명 정보가 제공되지 않으면 Default Azure Credential과 5분의 tokenRenewalOffsetTime을 사용하는 것이 기본값이에요.
자격 증명 선택(Credential Selection)
자격 증명 유형은 제공하는 필드에 기반해 자동으로 추론돼요.
-
Client Secret Credential은 세 가지 모두 제공될 때 사용돼요.
-
tenantId -
clientId -
clientSecret
-
-
Managed Identity Credential은
clientId만 제공될 때 사용돼요. 이는 사용자 할당 관리 ID(user-assigned managed identity)를 활성화해요. -
Default Azure Credential은 자격 증명 필드가 아무것도 제공되지 않을 때 사용돼요. Default Azure Credential은 많은 자격 증명 유형을 지원하며, 런타임 환경에 기반해 하나를 선택해요.
토큰 갱신(Token Renewal)
tokenRenewalOffsetTime을 설정해 OAuth 토큰을 얼마나 일찍 갱신할지 제어하세요.
값은 다음과 같을 수 있어요.
-
'1d', '2 hours', '30 seconds' 같은 사람이 읽을 수 있는 문자열
-
{ minutes: 3, seconds: 30 } 같은 기간(duration) 객체
Azure PostgreSQL은 수명이 짧은 Entra ID 접근 토큰을 사용해요. 기본적으로 데이터베이스 커넥터는 토큰이 만료되기 5분 전에 토큰을 갱신해요.
사용자 구성(User Configuration)
user를 Entra ID 그룹, 서비스 주체, 또는 관리 ID의 표시 이름으로 설정하세요. 사용자의 자격 증명으로 인증한다면 user principal name으로 설정하세요.
예시
app-config.yaml
backend:
database:
client: pg
connection:
type: azure
tokenCredential:
tokenRenewalOffsetTime: 5 minutes
host: ${POSTGRES_HOST}
port: ${POSTGRES_PORT}
user: ${POSTGRES_USER}
password: ${POSTGRES_PASSWORD}
Cloud IAM을 사용하는 Google
연결 구성에서 password를 제거하고 type을 cloudsql로 설정하세요.
내부적으로 이것은 Automatic IAM Database Authentication을 구현해요.
IAM 사용자 계정의 경우 user를 사용자의 이메일 주소로 설정하세요. 서비스 계정의 경우 user를 .gserviceaccount.com 도메인 접미사가 없는 서비스 계정의 이메일로 설정하세요.
app-config.yaml
backend:
database:
client: pg
connection:
type: cloudsql
instance: my-project:region:my-instance
host: ${POSTGRES_HOST}
port: ${POSTGRES_PORT}
user: ${POSTGRES_USER}
password: ${POSTGRES_PASSWORD}
Backstage 앱을 시작하세요.
yarn start
Backstage 프런트엔드가 실행된 뒤 아무것도 바뀌지 않았다는 것을 알아차릴 거예요. 이것은 좋은 신호예요. 위의 모든 것이 올바르게 설정됐다면, 이는 데이터가 데모 데이터 파일에서 데이터베이스로 직접 흐르고 있다는 뜻이에요!
이제 데이터가 Backstage 데이터베이스에 영속되게 만들었어요.
대안(Alternatives)
Postgres를 로컬에 설치하고 싶지 않을 수도 있는데, 다음 섹션들이 대안을 설명해요.
Docker
Docker 컨테이너에서 Postgres를 실행할 수 있어요. 로컬 개발이나 Backstage POC를 빠르게 구동하는 데 훌륭해요. 방법은 다음과 같아요.
먼저 컨테이너 이미지를 끌어와야 해요. Postgres 18을 사용할게요. 어떤 버전이 지원되는지 알아보려면 Postgres 버전 정책을 확인하세요.
docker pull postgres:18-trixie
그다음 컨테이너를 시작하기만 하면 돼요.
docker run -d --name postgres --restart=always -p 5432:5432 -e POSTGRES_PASSWORD=<secret> postgres:18-trixie
이 명령은 Postgres를 백그라운드에서 실행해 주지만, 시스템을 재부팅하면 다시 시작해야 한다는 점을 기억하세요.
Docker Compose
Postgres를 실행하는 또 다른 방법은 Docker Compose를 사용하는 것이에요. 다음과 같을 거예요.
docker-compose.local.yaml
services:
postgres:
image: postgres:18-trixie
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: <secret>
# If you want to set a timezone you can use the following environment variables, this is handy when trying to figure out when scheduled tasks will run!
# TZ: Europe/Stockholm
# PGTZ: Europe/Stockholm
ports:
- 5432:5432
그다음 docker compose -f docker-compose.local.yaml up을 실행해 Postgres를 시작하면 돼요.
다음 단계(Next Steps)
다음으로 인증 설정하기(Setting up authentication)를 읽는 것을 권장해요.
더 읽을거리(Further Reading)
데이터베이스 구성에 대해 더 알고 싶다면 도움이 되는 링크가 있어요.
-
플러그인 데이터베이스 구성(Configuring Plugin Databases)
-
수동 Knex 롤백(Manual Knex Rollback)
-
우리가 사용하는 데이터베이스 래퍼인 Knex에 대해 더 읽어보기
-
데이터베이스를 쿼리하는 데 도움이 되는 도구인
pgAdmin4 설치하기