&Axum SQLx를 활용한 데이터베이스 중급 - Docker를 활용한 PostgreSQL 환경 설정

이 글에서는 Docker와 Docker Compose를 활용하여 PostgreSQL 데이터베이스를 설정하는 방법을 알아보겠습니다. Docker를 사용하면 로컬 환경에 직접 설치하지 않고도 데이터베이스를 컨테이너로 관리할 수 있어 개발 환경 설정이 간편해지고 일관성을 유지할 수 있습니다.

---

1. Docker와 Docker Compose 소개 및 설치

1.1 Docker 소개

Docker는 애플리케이션을 컨테이너로 패키징하여 배포하고 실행할 수 있는 플랫폼입니다. 컨테이너는 애플리케이션과 그 실행 환경을 함께 묶어 일관된 환경에서 실행할 수 있도록 도와줍니다.

1.2 Docker 설치

운영체제별 Docker 설치 방법은 다음과 같습니다.

Windows

• Docker Desktop for Windows를 설치합니다.
• 설치 링크: Docker Desktop for Windows
• 설치 시 WSL 2(Windows Subsystem for Linux) 기능을 활성화해야 합니다.

macOS

• Docker Desktop for Mac을 설치합니다.
• 설치 링크: Docker Desktop for Mac

Linux

• 패키지 매니저를 통해 Docker Engine을 설치합니다.
• 예시(Ubuntu):
• sudo apt-get update sudo apt-get install -y docker.io
• 자세한 설치 가이드: Docker Engine 설치

1.3 Docker Compose 소개

Docker Compose는 여러 개의 컨테이너로 구성된 애플리케이션을 정의하고 실행할 수 있는 도구입니다. 단일 YAML 파일로 서비스 구성을 정의하고, 한 번의 명령어로 모든 서비스를 실행할 수 있습니다.

1.4 Docker Compose 설치

• Docker Desktop을 설치하면 Docker Compose가 기본적으로 포함되어 있습니다.
• Linux에서는 별도로 설치해야 할 수 있습니다.
• sudo curl -L "https://github.com/docker/compose/releases/download/v2.0.1/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose sudo chmod +x /usr/local/bin/docker-compose
• 설치 확인:
• docker-compose --version

---

2. Docker Compose로 PostgreSQL 설정 및 실행

2.1 프로젝트 디렉토리 생성

터미널에서 프로젝트를 위한 디렉토리를 생성하고 이동합니다.

mkdir docker-postgres-setup
cd docker-postgres-setup

2.2 docker-compose.yml 파일 작성

프로젝트 디렉토리에 docker-compose.yml 파일을 생성하고 다음 내용을 입력합니다.

version: "3"

services:
  db:
    image: postgres:latest
    environment:
      - POSTGRES_USER=test
      - POSTGRES_PASSWORD=test1234
      - POSTGRES_DB=test_db
    ports:
      - "5432:5432"
    volumes:
      - ./db/init/:/docker-entrypoint-initdb.d/
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U test"]
      interval: 5s
      retries: 5

설정 설명

• image: 사용할 PostgreSQL Docker 이미지를 지정합니다.
• environment: 컨테이너 내부에서 사용할 환경 변수를 설정합니다.
  • POSTGRES_USER: PostgreSQL 사용자 이름
  • POSTGRES_PASSWORD: 해당 사용자의 비밀번호
  • POSTGRES_DB: 초기 생성할 데이터베이스 이름
• ports: 호스트와 컨테이너의 포트를 매핑합니다. (호스트 포트:컨테이너 포트)
• volumes: 호스트의 디렉토리를 컨테이너 내부에 마운트합니다.
  • ./db/init/ 디렉토리에 있는 스크립트를 컨테이너의 /docker-entrypoint-initdb.d/에 마운트하여 컨테이너 시작 시 실행되도록 합니다.
• healthcheck: 컨테이너의 상태를 확인하는 방법을 정의합니다.
  • pg_isready 명령어를 사용하여 PostgreSQL이 준비되었는지 확인합니다.

2.3 초기화 스크립트 작성 (선택 사항)

초기 데이터베이스 설정이나 테이블 생성을 자동화하려면 ./db/init/ 디렉토리에 SQL 스크립트를 작성합니다.

mkdir -p db/init

 

db/init/init.sql 파일을 생성하고 다음 내용을 입력합니다.

-- 초기 테이블 생성 예시
CREATE TABLE IF NOT EXISTS test_table (
  id SERIAL PRIMARY KEY,
  name VARCHAR(50) NOT NULL
);

2.4 Docker Compose로 PostgreSQL 실행

터미널에서 다음 명령어를 실행하여 컨테이너를 시작합니다.

docker-compose up -d

• -d 옵션은 백그라운드에서 컨테이너를 실행합니다.
• 컨테이너가 정상적으로 실행되었는지 확인하려면
• docker-compose ps

---

3. 데이터베이스 접속 및 기본 설정

3.1 psql 클라이언트를 사용하여 접속

PostgreSQL 컨테이너에 접속하여 데이터베이스에 접근합니다.

docker-compose exec db psql -U test -d test_db

• -U: 사용자 이름 지정
• -d: 데이터베이스 이름 지정

3.2 데이터베이스 확인

psql 프롬프트에서 다음 명령어를 입력하여 데이터베이스와 테이블을 확인합니다.

\l -- 데이터베이스 목록 확인
\dt -- 테이블 목록 확인

출력 예시:

test_db=# \l
                                   List of databases
   Name    | Owner | Encoding |   Collate   |    Ctype    |   Access privileges
-----------+-------+----------+-------------+-------------+-----------------------
 test_db   | test  | UTF8     | en_US.utf8  | en_US.utf8  |
 postgres  | test  | UTF8     | en_US.utf8  | en_US.utf8  |
 template0 | test  | UTF8     | en_US.utf8  | en_US.utf8  | =c/test              +
           |       |          |             |             | test=CTc/test
 template1 | test  | UTF8     | en_US.utf8  | en_US.utf8  | =c/test              +
           |       |          |             |             | test=CTc/test
(4 rows)

test_db=# \dt
          List of relations
 Schema |   Name    | Type  | Owner
--------+-----------+-------+-------
 public | test_table | table | test
(1 row)

3.3 간단한 쿼리 실행

테이블 조회

SELECT * FROM test_table;

만약 초기화 스크립트에서 데이터를 삽입했다면 결과가 나타납니다. 그렇지 않다면 데이터를 삽입해 봅시다.

 

데이터 삽입

INSERT INTO test_table (name) VALUES ('Alice'), ('Bob');

 

데이터 확인

SELECT * FROM test_table;

출력 예시:

 id | name
----+-------
  1 | Alice
  2 | Bob
(2 rows)

3.4 종료

\q 명령어를 입력하여 psql을 종료합니다.

---

4. 애플리케이션에서의 접속 정보 설정

애플리케이션(Rust 등)에서 데이터베이스에 접속하기 위해서는 접속 정보를 설정해야 합니다.

4.1 환경 변수 설정

애플리케이션에서 민감한 정보를 관리하기 위해 환경 변수를 사용합니다. .env 파일을 생성하고 다음과 같이 설정합니다.

DATABASE_URL=postgres://test:test1234@localhost:5432/test_db

4.2 Rust 애플리케이션에서의 사용 예시

Cargo.toml에 dotenvy와 sqlx 의존성을 추가합니다.

[dependencies]
dotenvy = "0.15"
sqlx = { version = "0.6", features = ["postgres", "runtime-tokio-native-tls", "macros"] }

main.rs 파일에서 환경 변수를 로드하고 데이터베이스에 연결합니다.

use sqlx::postgres::PgPoolOptions;
use std::env;
use dotenvy::dotenv;

#[tokio::main]
async fn main() -> Result<(), sqlx::Error> {
    // .env 파일 로드
    dotenv().ok();

    // 환경 변수에서 데이터베이스 URL 가져오기
    let database_url = env::var("DATABASE_URL").expect("DATABASE_URL must be set");

    // 데이터베이스 풀 생성
    let pool = PgPoolOptions::new()
        .max_connections(5)
        .connect(&database_url)
        .await?;

    // 간단한 쿼리 실행 예시
    let row: (i64,) = sqlx::query_as("SELECT 1")
        .fetch_one(&pool)
        .await?;

    println!("쿼리 결과: {}", row.0);

    Ok(())
}

---

결론

Docker와 Docker Compose를 활용하면 PostgreSQL 데이터베이스를 손쉽게 설정하고 관리할 수 있습니다. 이를 통해 개발 환경을 일관되게 유지하고, 팀원들과 동일한 환경에서 개발할 수 있습니다. 또한 Docker를 사용하면 시스템에 직접 데이터베이스를 설치하지 않아도 되므로 환경 간 충돌을 방지할 수 있습니다.

---

참고 자료

• Docker 공식 문서
• Docker Compose 공식 문서
• PostgreSQL Docker 이미지
• psql 사용법
• SQLx 공식 문서
• dotenvy 크레이트

---

주의: 이 가이드는 학습 목적을 위해 작성되었으며, 실제 환경에서는 보안 및 구성에 대한 추가 고려 사항이 필요할 수 있습니다.