개발 앱에 로컬 PostgreSQL 사용하기

새 앱은 별도 설정 없이 Nexia가 제공하는 샌드박스 DB를 사용합니다. 개발자 PC의 PostgreSQL에 앱 데이터를 두려면 그 앱의 첫 nexia dev 또는 DB 마이그레이션 전에 아래 절차를 마치세요. 이미 제공 DB에 할당된 앱의 데이터는 이 명령으로 이전되지 않습니다. 프로젝트에 연결된 앱 폴더와 Console 개발 환경에서 준비된 활성 샌드박스가 필요합니다. 앱이 아직 등록되지 않았다면 nexia db local이 앱 메타데이터만 먼저 등록합니다.

선택	준비할 것	앱 DB 위치
Nexia 제공 DB	로컬 PostgreSQL 불필요	Nexia 샌드박스
기존 로컬 PostgreSQL	실행 중인 서버와 앱 전용 빈 DB	개발자 PC
Docker로 실행한 로컬 PostgreSQL	개발자 PC의 Docker와 앱 전용 데이터 볼륨	개발자 PC

nexia db local은 PostgreSQL을 설치·시작하거나 DB 자체를 생성하지 않습니다. 이미 준비한 전용 DB 안에 앱의 migrator·runtime 계정 두 개와 스키마를 만들고, 앱 외래 키에 필요한 Core 참조 테이블의 ID만 복사합니다. Core 사용자 이름이나 업무 데이터 전체를 복제하지 않습니다. DB 관리자 비밀번호는 Nexia 서버로 보내거나 앱 연결 파일에 저장하지 않습니다.

기존 로컬 서버와 DBeaver

로컬 PostgreSQL 서버가 실행 중인지 확인합니다. DBeaver는 서버가 아니라 접속 도구입니다.
DBeaver에서 서버의 기존 postgres DB에 관리자 계정으로 접속합니다. 호스트는 127.0.0.1, 포트는 실제 서버 포트(보통 5432)를 사용합니다.
SQL 편집기에서 앱 전용 빈 DB를 만듭니다. 앱마다 다른 이름을 사용하세요.

코드 예시

SQL

CREATE DATABASE nexia_app;1

DBeaver에서 nexia_app에 다시 접속해 DB 생성 결과를 확인합니다. 이미 앱 전용 빈 DB가 있다면 생성 단계는 건너뛰세요. 다음 단계에 쓰는 관리자 계정은 PostgreSQL 로그인 역할과 스키마를 만들 권한이 있어야 합니다.

macOS의 Homebrew 서비스나 Linux의 시스템 서비스로 PostgreSQL을 실행 중이어도 같은 절차입니다. 설치 방식이 아니라 CLI를 실행하는 PC에서 루프백 주소로 접속되는지가 중요합니다.

로컬 DB에 앱 연결하기

앱 폴더의 터미널에서 실제 접속 정보를 설정합니다. 다음은 macOS/zsh 또는 Linux/bash 예시이며 포트·DB 이름·관리자 계정은 본인 환경에 맞춰 바꾸세요. 비밀번호는 셸 기록에 직접 입력하지 않도록 프롬프트로 받습니다.

코드 예시

Shell

export PGHOST=127.0.0.1 PGPORT=5432 PGDATABASE=nexia_app PGUSER=postgres
printf 'PostgreSQL administrator password: '
read -rs PGPASSWORD
printf '\n'
export PGPASSWORD
nexia db local
unset PGPASSWORD
nexia dev12345678

Windows PowerShell에서는 앱 폴더에서 다음과 같이 설정합니다. Read-Host가 비밀번호를 화면에 표시하지 않고 받습니다.

코드 예시

POWERSHELL

$env:PGHOST = '127.0.0.1'
$env:PGPORT = '5432'
$env:PGDATABASE = 'nexia_app'
$env:PGUSER = 'postgres'
$secret = Read-Host 'PostgreSQL administrator password' -AsSecureString
$env:PGPASSWORD = [System.Net.NetworkCredential]::new('', $secret).Password
nexia db local
Remove-Item Env:PGPASSWORD
nexia dev123456789

CLI는 PGHOST로 127.0.0.1 또는 ::1만 허용합니다. PGUSER는 앱 런타임 계정이 아니라 본인 로컬 DB의 관리자 계정입니다. 초기 설정이 끝나면 그 비밀번호를 셸에서 지우세요.

nexia db local은 종료되는 초기 설정 명령입니다. .nexia/local-database.json에는 앱·DB·루프백 주소만 기록하고 비밀번호를 넣지 않습니다. 이 파일을 저장소에 커밋하지 마세요. 이후 터미널 1에서 nexia dev를 계속 실행하면 인증된 터널이 샌드박스 앱과 로컬 DB를 연결합니다. 같은 앱 폴더의 터미널 2에서 마이그레이션을 실행하세요.

코드 예시

Shell

nexia db migrate
nexia db status12

새 Core 참조 ID가 필요해지면 nexia db local을 다시 실행해 ID를 추가합니다. 기존 ID는 로컬 앱의 외래 키를 지키기 위해 남깁니다. nexia dev 또는 로컬 PostgreSQL이 중단되면 앱의 DB 연결도 끊기므로 다시 실행하세요. 로컬 DB 모드에서는 현재 db reset과 db fresh를 사용할 수 없습니다. migrate, status, rollback, refresh는 선택한 로컬 DB를 사용합니다.

PostgreSQL이 설치되지 않은 경우

Docker는 선택 사항입니다. 개발자 PC에서 아래와 같이 실행하면 컨테이너의 PostgreSQL 포트 5432가 **PC의 루프백 포트 55432**에 연결됩니다. nexia db local과 DBeaver에는 컨테이너 이름이나 내부 포트가 아니라 127.0.0.1:55432를 입력합니다. 앱 폴더의 macOS/zsh 또는 Linux/bash 터미널에서 실행하세요.

코드 예시

Shell

printf 'Local PostgreSQL administrator password: '
read -rs POSTGRES_PASSWORD
printf '\n'
export POSTGRES_PASSWORD
docker run -d --name nexia-local-pg \
  -e POSTGRES_PASSWORD -e POSTGRES_DB=nexia_app \
  -p 127.0.0.1:55432:5432 \
  -v nexia-local-pg-data:/var/lib/postgresql/data \
  postgres:17
docker exec nexia-local-pg pg_isready -U postgres -d nexia_app12345678910

pg_isready가 접속 가능하다고 표시될 때까지 기다립니다. Docker는 새 데이터 볼륨을 처음 초기화할 때만 POSTGRES_DB=nexia_app을 생성합니다. 이미 사용 중인 볼륨에는 기존 DB와 비밀번호가 유지됩니다. 다음 명령으로 앱을 연결하세요.

코드 예시

Shell

export PGHOST=127.0.0.1 PGPORT=55432 PGDATABASE=nexia_app PGUSER=postgres
export PGPASSWORD="$POSTGRES_PASSWORD"
nexia db local
unset POSTGRES_PASSWORD PGPASSWORD
nexia dev12345

이미 Docker에서 PostgreSQL을 실행 중이라면 docker port <컨테이너 이름> 5432/tcp로 PC에 게시된 포트를 확인하고 그 값을 PGPORT와 DBeaver 포트에 사용하세요. 호스트에 포트가 게시되지 않았다면 이 CLI의 루프백 연결로는 접근할 수 없습니다. 데이터 볼륨을 보존한 채 포트 게시 설정을 준비해야 합니다. DBeaver에는 Host 127.0.0.1, Port 55432(또는 실제 게시 포트), Database nexia_app, User postgres, Docker 시작 때 정한 Password를 입력합니다. 컨테이너를 중지했다가 다시 쓸 때는 docker start nexia-local-pg를 실행하세요. 앱 데이터는 명명한 볼륨에 남습니다.

Windows PowerShell에서 Docker를 사용하는 경우에는 같은 설정을 한 줄로 실행할 수 있습니다. 비밀번호를 입력한 뒤 아래 명령을 실행하고, 이어서 위의 PowerShell 앱 연결 명령에서 PGPORT를 55432로 지정하세요.

코드 예시

POWERSHELL

$secret = Read-Host 'Local PostgreSQL administrator password' -AsSecureString
$env:POSTGRES_PASSWORD = [System.Net.NetworkCredential]::new('', $secret).Password
docker run -d --name nexia-local-pg -e POSTGRES_PASSWORD -e POSTGRES_DB=nexia_app -p 127.0.0.1:55432:5432 -v nexia-local-pg-data:/var/lib/postgresql/data postgres:17
docker exec nexia-local-pg pg_isready -U postgres -d nexia_app
$env:PGHOST = '127.0.0.1'
$env:PGPORT = '55432'
$env:PGDATABASE = 'nexia_app'
$env:PGUSER = 'postgres'
$env:PGPASSWORD = $env:POSTGRES_PASSWORD
nexia db local
Remove-Item Env:POSTGRES_PASSWORD
Remove-Item Env:PGPASSWORD
nexia dev12345678910111213

CLI를 앱 개발 컨테이너 안에서 실행한다면 그 컨테이너의 127.0.0.1은 개발자 PC가 아닙니다. 이 로컬 DB 절차에서는 CLI와 nexia dev를 PostgreSQL의 루프백 포트에 접속할 수 있는 PC에서 실행하세요. 다른 컴퓨터의 DB 주소나 고객사 내부망 DB를 PGHOST로 등록하는 기능은 이 개발자 로컬 DB 모드에 포함되지 않습니다.

DBeaver로 데이터 확인하기

초기화 후 DBeaver에서 같은 127.0.0.1·포트·nexia_app으로 접속하면 앱 스키마의 테이블을 조회하고 SQL·가져오기를 사용할 수 있습니다. 개발자 소유의 로컬 DB 관리자 계정을 사용할 수 있지만, 앱 실행에는 nexia db local이 만든 제한된 runtime 계정이 사용됩니다. 앱 테이블은 public이 아니라 앱 전용 dev_... 스키마에 있습니다. DBeaver에서 스키마 목록을 표시해 해당 스키마를 선택하세요.

연결 확인

nexia db local이 로컬 앱 DB 준비 완료를 표시하는지 확인하세요. nexia dev를 계속 실행해 로컬 PostgreSQL 터널 연결 메시지가 나오는지 확인합니다. 다른 터미널에서 nexia db status로 앱 마이그레이션 상태를 조회하고, nexia db migrate 후 DBeaver의 dev_... 스키마에 앱 테이블이 나타나는지 확인하세요.

데이터 모델과 마이그레이션에서 앱 테이블 작성과 DB 명령의 복구 절차를 확인할 수 있습니다.

개발 앱에 로컬 PostgreSQL 사용하기

개발 앱에 로컬 PostgreSQL 사용하기

기존 로컬 서버와 DBeaver

로컬 DB에 앱 연결하기

PostgreSQL이 설치되지 않은 경우

DBeaver로 데이터 확인하기

연결 확인

관련 업데이트와 공개 소스