데이터베이스 시스템

데이터베이스 시스템

SQL 데이터베이스 연결 풀링 및 설정. PostgreSQL, MySQL, SQLite를 지원합니다.

엔트리 종류

Kind	설명
db.sql.postgres	PostgreSQL 데이터베이스
db.sql.mysql	MySQL 데이터베이스
db.sql.sqlite	SQLite 데이터베이스

설정

표준 데이터베이스 (PostgreSQL, MySQL)

src/data/_index.yaml

version: "1.0"
namespace: app.data

entries:
  - name: main_db
    kind: db.sql.postgres
    host: "localhost"
    port: 5432
    database: "myapp"
    username: "dbuser"
    password: "dbpass"
    pool:
      max_open: 25
      max_idle: 5
      max_lifetime: "1h"
    options:
      sslmode: "disable"
    lifecycle:
      auto_start: true

SQLite

  - name: cache_db
    kind: db.sql.sqlite
    file: "/var/data/cache.db"  # 인메모리는 :memory: 사용
    pool:
      max_open: 1
      max_idle: 1
      max_lifetime: "1h"
    options:
      cache: "shared"
    lifecycle:
      auto_start: true

연결 필드

표준 데이터베이스 필드

필드	타입	설명
host	string	데이터베이스 호스트 주소
port	int	데이터베이스 포트 번호
database	string	데이터베이스 이름
username	string	데이터베이스 사용자
password	string	데이터베이스 비밀번호
pool	object	연결 풀 설정
options	map	데이터베이스별 옵션
lifecycle	object	라이프사이클 설정

SQLite 필드

필드	타입	설명
file	string	데이터베이스 파일 경로 또는 :memory:
pool	object	연결 풀 설정
options	map	SQLite별 옵션
lifecycle	object	라이프사이클 설정

환경 변수 필드

_env 접미사를 사용하여 환경 변수나 env.variable 엔트리에서 값을 로드:

필드	설명
host_env	환경 변수에서 호스트
port_env	환경 변수에서 포트
database_env	환경에서 데이터베이스 이름
username_env	환경에서 사용자명
password_env	환경에서 비밀번호

- name: prod_db
  kind: db.sql.postgres
  host_env: "DB_HOST"
  port_env: "DB_PORT"
  database_env: "DB_NAME"
  username_env: "DB_USER"
  password_env: "app.secrets:db_password"  # env.variable 엔트리 참조

설정에 비밀번호를 직접 입력하지 마세요. 자격 증명에는 환경 변수나 env.variable 엔트리를 사용하세요. 안전한 시크릿 관리는 환경을 참조하세요.

연결 풀

연결 풀링 동작 설정. 풀 설정은 Go의 database/sql 연결 풀에 매핑됩니다.

필드	타입	기본값	설명
max_open	int	0	최대 열린 연결 (0 = 무제한)
max_idle	int	0	최대 유휴 연결 (0 = 무제한)
max_lifetime	duration	1h	최대 연결 수명

pool:
  max_open: 25      # 동시 연결 제한
  max_idle: 5       # 5개 연결 준비 상태 유지
  max_lifetime: "30m"  # 30분마다 연결 재활용

max_idle을 max_open 이하로 설정하세요. max_lifetime을 초과하는 연결은 닫히고 교체되어 오래된 연결에서 복구하는 데 도움이 됩니다.

DSN 형식

각 데이터베이스 타입은 설정에서 DSN을 구성합니다:

PostgreSQL {id=“dsn-postgresql”}

postgres://username:password@host:port/database?sslmode=disable

MySQL {id=“dsn-mysql”}

username:password@tcp(host:port)/database?charset=utf8mb4

SQLite {id=“dsn-sqlite”}

file:/path/to/database.db?cache=shared
:memory:?mode=memory

데이터베이스 옵션

일반적인 데이터베이스별 옵션:

PostgreSQL {id=“options-postgresql”}

options:
  sslmode: "require"      # disable, require, verify-ca, verify-full
  connect_timeout: "10"   # 연결 타임아웃(초)
  application_name: "myapp"

MySQL {id=“options-mysql”}

options:
  charset: "utf8mb4"
  parseTime: "true"       # 시간 값을 time.Time으로 파싱
  loc: "Local"            # 시간대

SQLite {id=“options-sqlite”}

options:
  cache: "shared"         # shared, private
  mode: "rwc"            # ro, rw, rwc, memory
  _journal_mode: "WAL"   # DELETE, TRUNCATE, PERSIST, MEMORY, WAL, OFF

예제

SSL을 사용하는 PostgreSQL

- name: secure_postgres
  kind: db.sql.postgres
  host: "db.example.com"
  port: 5432
  database: "production"
  username: "app_user"
  password: "${DB_PASSWORD}"
  pool:
    max_open: 50
    max_idle: 10
    max_lifetime: "1h"
  options:
    sslmode: "verify-full"
    sslcert: "/certs/client.crt"
    sslkey: "/certs/client.key"
    sslrootcert: "/certs/ca.crt"
  lifecycle:
    auto_start: true

MySQL 읽기 전용 복제본

- name: mysql_replica
  kind: db.sql.mysql
  host: "replica.db.example.com"
  port: 3306
  database: "app"
  username: "readonly"
  password_env: "REPLICA_PASSWORD"
  pool:
    max_open: 20
    max_idle: 5
    max_lifetime: "30m"
  options:
    charset: "utf8mb4"
    parseTime: "true"
    readTimeout: "30s"

SQLite 인메모리

- name: test_db
  kind: db.sql.sqlite
  file: ":memory:"
  pool:
    max_open: 1
    max_idle: 1
  options:
    cache: "shared"
    mode: "memory"

여러 데이터베이스 구성

entries:
  # 기본 데이터베이스
  - name: users_db
    kind: db.sql.postgres
    host_env: "USERS_DB_HOST"
    port: 5432
    database: "users"
    username_env: "USERS_DB_USER"
    password_env: "USERS_DB_PASSWORD"
    lifecycle:
      auto_start: true

  # 분석 데이터베이스
  - name: analytics_db
    kind: db.sql.mysql
    host_env: "ANALYTICS_DB_HOST"
    port: 3306
    database: "analytics"
    username_env: "ANALYTICS_DB_USER"
    password_env: "ANALYTICS_DB_PASSWORD"
    lifecycle:
      auto_start: true

  # 로컬 캐시
  - name: cache
    kind: db.sql.sqlite
    file: "/var/cache/app.db"
    lifecycle:
      auto_start: true

런타임 등록

레지스트리 모듈을 사용하여 런타임에 데이터베이스를 등록할 수 있으며, 애플리케이션 상태나 외부 설정에 따라 동적으로 데이터베이스를 구성할 수 있습니다.

Lua API

데이터베이스 작업 API는 SQL 모듈을 참조하세요.

참고

• SQL 모듈 - Lua API 레퍼런스
• Store - database.sql 기반의 키-값 저장소
• Queue - SQL 기반 큐 핸들러