PostgREST API 설치 및 사용법: 초보자 가이드

개발자들이 PostgreSQL 데이터베이스 위에 RESTful API를 구축하는 데 얼마나 많은 시간을 보내는지 생각해 본 적이 있으신가요? 이는 종종 CRUD 작업을 위한 상용구 코드 작성, 쿼리 처리, 보안 보장 등 프로젝트 진행 속도를 늦출 수 있는 작업들을 수반합니다. 바로 이 지점에서 PostgREST API가 등장하여, 최소한의 노력으로 데이터베이스를 즉시 사용 가능한 API로 전환하는 간소화된 대안을 제공합니다. 이 종합 가이드에서는 PostgREST API의 기본 개념부터 실제 구현까지 심층적으로 탐구할 것입니다. 개발 속도를 높이려는 백엔드 엔지니어든 효율성을 추구하는 풀스택 개발자든, PostgREST API를 마스터하면 작업 흐름을 혁신할 수 있습니다.

이 주제를 함께 살펴보면서, 저는 실제 경험에서 얻은 통찰력을 공유하고 각 섹션이 이전 섹션에 논리적으로 기반을 두도록 할 것입니다. 결론에 도달할 때쯤에는 다음 프로젝트에 PostgREST API를 통합할 준비가 되었다고 느끼실 것입니다. 이제 필수 사항부터 시작해 봅시다.

💡

아름다운 API 문서를 생성하는 훌륭한 API 테스트 도구를 원하십니까?

개발팀이 최고의 생산성으로 함께 작업할 수 있는 통합된 올인원 플랫폼을 원하십니까?

Apidog는 모든 요구 사항을 충족하며, 훨씬 더 저렴한 가격으로 Postman을 대체합니다!

버튼

PostgREST API란 무엇인가요? 개요

PostgREST API는 PostgreSQL 데이터베이스를 완전한 기능을 갖춘 RESTful 웹 서비스로 자동 노출시키는 독립 실행형 도구입니다. Beowulf가 개발한 이 API는 PostgreSQL의 쿼리 언어(SQL)의 강력한 기능을 활용하여 HTTP 엔드포인트를 동적으로 생성하며, 많은 경우 사용자 지정 서버 측 로직의 필요성을 없앱니다. 본질적으로 PostgREST API는 데이터베이스 스키마, 테이블, 뷰, 저장 프로시저를 API 리소스로 해석하여 GET, POST, PUT, DELETE와 같은 표준 HTTP 메서드를 통해 생성, 읽기, 업데이트, 삭제(CRUD) 작업을 수행할 수 있도록 합니다.

PostgREST API가 특히 매력적인 이유는 REST 원칙을 준수하면서도 세분화된 접근 제어를 위한 행 수준 보안(RLS)과 같은 고급 PostgreSQL 기능을 통합한다는 점입니다. 예를 들어, URL 매개변수를 사용하여 필터, 정렬 및 페이지 매김으로 데이터를 쿼리할 수 있으며, 추가 미들웨어는 필요하지 않습니다. 이 접근 방식은 코드 복잡성을 줄일 뿐만 아니라 API가 데이터베이스 변경 사항과 자동으로 동기화되도록 보장합니다.

ORM과 API 프레임워크가 지배하는 환경에서 PostgREST API는 "데이터베이스 우선" 철학으로 두각을 나타냅니다. OpenAPI(Swagger) 문서를 기본적으로 지원하여 Apidog 또는 Swagger UI와 같은 도구와의 통합에 개발자 친화적입니다. 분석 대시보드, 모바일 백엔드 또는 마이크로서비스와 같은 데이터 집약적인 애플리케이션을 관리하는 경우, PostgREST API는 PostgreSQL의 견고성과 함께 확장되는 경량의 고성능 솔루션을 제공합니다. 계속 진행하면서 이 API가 데이터 계층과 클라이언트 애플리케이션 간의 격차를 어떻게 원활하게 연결하는지 보게 될 것입니다.

PostgREST API 시작하기: 설치 및 설정

PostgREST API 작업을 시작하려면 기반이 되는 PostgreSQL 인스턴스가 필요합니다. 다행히 설정은 간단하며, 특히 종속성을 격리하고 배포를 단순화하는 Docker와 같은 컨테이너화 도구를 사용할 때 더욱 그렇습니다. 먼저 Docker Desktop이 머신에 설치되어 있는지 확인하십시오. 운영 체제(macOS, Windows 또는 Linux)에 맞는 공식 웹사이트에서 다운로드할 수 있습니다.

Docker가 준비되면 필요한 이미지를 가져옵니다. Docker Desktop을 열고 검색 창으로 이동하여 API 서버 자체를 위한 "postgrest/postgrest" 이미지를 설치합니다. 마찬가지로,

PostgreSQL 데이터베이스를 시각적으로 관리하기 위해 "dpage/pgadmin4"를 검색하여 설치합니다.

그리고 경량 PostgreSQL 컨테이너를 위한 "postgres:alpine"을 설치합니다. 이 구성 요소들은 PostgREST API 주변의 생태계를 형성합니다.

터미널을 통한 수동 PostgreSQL 설정(권장)의 경우, 다음 명령을 실행하여 컨테이너를 실행합니다:

docker run --name postgres-1 -e POSTGRES_PASSWORD=password -d -p 5431:5432 postgres:alpine

여기서 "password"를 보안 값으로 대체하십시오. 이 명령은 PostgreSQL을 5431 포트에서 시작하며, 내부 5432 포트에 매핑됩니다. 성공하면 Docker는 컨테이너 ID(긴 영숫자 문자열)를 반환합니다. 이를 확인을 위해 기록해 두십시오. `docker ps`를 실행하여 컨테이너 상태를 확인하십시오.

PostgREST API 구성에 중요한 사용자 역할을 확인하려면 컨테이너 셸에 접속합니다:

docker exec -it <container_id> sh

`<container_id>`를 자신의 ID 또는 컨테이너 이름으로 대체하십시오. 셸 내부에서 PostgreSQL에 연결합니다:

psql -U postgres -d postgres

(기본 사용자로 "postgres"를 가정합니다; 사용자 지정한 경우 조정하십시오. 저의 경우 `username`으로 변경되었습니다.) 그런 다음 `\du`로 역할을 나열합니다. "postgres" 또는 사용자 지정 역할 이름이 포함된 이 출력은 나중에 참조될 것입니다. 여기서 추가 사용자를 생성하고 스키마에 대한 SELECT, INSERT, UPDATE 또는 DELETE 권한 부여와 같은 권한을 할당할 수 있습니다.

이러한 전제 조건이 갖춰지면, 여러 컨테이너 애플리케이션을 정의하는 YAML 파일인 Docker Compose를 사용하여 환경을 오케스트레이션할 준비가 된 것입니다. 프로젝트 디렉터리에 `docker-compose.yaml` 파일을 생성하십시오:

version: "3.9"
services:
  postgres_host:
    image: postgres:alpine
    environment:
      POSTGRES_USER: username
      POSTGRES_PASSWORD: password
      POSTGRES_DB: postgres
    volumes:
      - pgdata:/var/lib/postgresql/data
    ports:
      - "5431:5432"
  pgadmin:
    image: dpage/pgadmin4
    ports:
      - "5050:80"
    depends_on:
      - postgres_host
    environment:
      PGADMIN_DEFAULT_EMAIL: postgres@pgadmin.com
      PGADMIN_DEFAULT_PASSWORD: postgres
  postgrest:
    image: postgrest/postgrest
    depends_on:
      - postgres_host
    ports:
      - "3000:3000"
    environment:
      PGRST_DB_URI: "postgres://username:password@postgres_host:5432/postgres"
      PGRST_DB_SCHEMA: "public"
      PGRST_DB_ANON_ROLE: "username"
volumes:
  pgdata:

설정에 맞게 "username"과 "password"를 사용자 지정하고, 익명 액세스를 위해 `\du` 출력에서 가져온 역할로 `PGRST_DB_ANON_ROLE`을 설정하십시오. 이 구성은 PostgreSQL, pgAdmin 및 PostgREST API 서버를 연결합니다. 파일을 저장한 다음 터미널(예: Docker 확장을 설치한 후 VS Code의 통합 터미널)에서 다음을 실행하십시오:

docker compose up --build

이것은 서비스를 빌드하고 시작합니다. YAML 자격 증명을 사용하여 `http://localhost:5050`에서 pgAdmin에 접속하고, 연결 세부 정보(호스트 이름: postgres_host, 포트: 5432, 사용자 이름: username, 비밀번호: password)를 사용하여 "postgres_host"라는 서버를 추가한 후 저장하십시오. 이제 `http://localhost:3000`에서 실행 중인 PostgREST API를 통해 데이터베이스와 상호 작용할 준비가 되었습니다.

샘플 프로젝트 구축: PostgREST API 단계별 테스트

PostgREST API의 진정한 가치를 이해하려면, 직원 기록 관리를 위한 간단한 인사 데이터베이스 API라는 실제 프로젝트를 구축해 봅시다. 이 예시는 "humans" 테이블에 대한 CRUD 작업을 시연하며, 오케스트레이션에는 Docker를, API 테스트에는 Apidog를 사용합니다.

1단계: 환경 준비

Docker Desktop이 설치되고 이미지가 가져와진 상태(PostgREST, pgAdmin4, postgres:alpine)에서, 이전에 설명한 대로 초기 PostgreSQL 컨테이너를 실행합니다. `docker ps`로 확인하고 `\du`를 통해 사용자 역할을 기록해 둡니다.

2단계: 스택 구성

VS Code와 같은 코드 편집기(원활한 컨테이너 관리를 위한 Docker 확장 기능 강화)에서 위 `docker-compose.yaml` 파일을 작성하십시오. 이미지 이름이 정확히 일치하는지 확인하십시오. 불일치는 시작을 중단시킬 수 있습니다. 필요한 경우 포트를 조정하되, PostgreSQL의 외부 포트(5431)는 수동 설정과 일치하도록 유지하십시오. `docker compose up --build`로 시작하십시오. 오류가 있는지 로그를 모니터링하십시오. 성공적인 시작은 서비스가 5431(DB), 5050(pgAdmin) 및 3000(PostgREST) 포트에 바인딩되었음을 보여줍니다.

3단계: pgAdmin 구성 및 테이블 생성

`http://localhost:5050`으로 이동하여 YAML의 PGADMIN_DEFAULT_EMAIL 및 PASSWORD로 로그인합니다.

대시보드 아래에서,

새 서버를 추가합니다: 이름을 "postgres_host"로 지정하고,

그런 다음 연결 탭에서 호스트 이름: postgres_host, 포트: 5432, 사용자 이름: username, 비밀번호: password를 입력합니다. 저장하여 인터페이스에 접속합니다.

테이블을 생성합니다: 데이터베이스 > postgres > 스키마 > public > 테이블로 이동하여 테이블을 마우스 오른쪽 버튼으로 클릭하고 생성 > 테이블을 선택합니다. 이름을 "humans"로 지정합니다. 열에 다음을 추가합니다:

id: INTEGER, Not Null, Primary Key
name: VARCHAR(50), Not Null
job: VARCHAR(50)

저장을 클릭합니다. 데이터를 삽입하려면 "humans" 테이블을 마우스 오른쪽 버튼으로 클릭 > 스크립트 > INSERT 스크립트를 선택합니다. 샘플 SQL로 수정합니다. 예:

INSERT INTO public.humans (id, name, job) VALUES (1, 'Steph Curry', 'Pro Basketball Player');

레코드를 유지하기 위해 실행합니다.

4단계: PostgREST API 가용성 확인

브라우저에서 `http://localhost:3000`을 엽니다. /humans와 같은 리소스가 나열된 Swagger 2.0 사양 문서가 표시되어야 합니다. 이는 PostgREST API가 작동 중이며 스키마를 인식하고 있음을 확인하는 것입니다.

5단계: Apidog로 테스트

Apidog를 실행하고 새 프로젝트를 생성한 다음 `http://localhost:3000/humans`에 GET 요청을 추가합니다("humans"를 테이블 이름으로 대체). 요청을 보내면 다음과 같은 JSON이 반환됩니다:

[
  {
    "id": 1,
    "name": "Steph Curry",
    "job": "Pro Basketball Player"
  }
]

쿼리를 위해 쿼리 매개변수를 추가합니다: 키 "name", 값 "eq.Steph Curry"("eq"는 같음을 나타냄). 이는 일치하는 레코드를 필터링합니다. 일치하지 않는 경우 빈 배열이 반환됩니다.

잘못된 데이터로 PostgREST 테스트 — 잘못된 데이터를 사용하여 검색

PostgREST API를 사용하여 Apidog에서 올바른 데이터로 검색 — 올바른 정보를 사용하여 검색

6단계: CRUD 작업 탐색

PostgREST API는 전체 CRUD에서 빛을 발합니다. POST(생성)의 경우, Apidog의 본문을 JSON으로 사용합니다: `{"name": "New Employee", "job": "Developer"}`를 `http://localhost:3000/humans`로 보냅니다. PUT은 `http://localhost:3000/humans?id=eq.1`을 통해 패치된 데이터로 업데이트합니다. DELETE는 `http://localhost:3000/humans?id=eq.1`을 사용합니다. 정렬(`order=name.asc`) 또는 제한(`limit=5`)과 같은 고급 필터는 사용성을 향상시킵니다. 자세한 예시는 https://docs.postgrest.org/en/v14/references/api/tables_views.html의 공식 문서를 참조하십시오.

한 시간 이내에 완료된 이 프로젝트는 신속한 프로토타이핑에서 PostgREST API의 탁월한 능력을 보여줍니다. PostgreSQL에 RLS 정책을 추가하여 안전한 역할 기반 액세스를 위해 확장하십시오.

자주 묻는 질문

Q1. PostgREST API를 실행하기 위한 시스템 요구 사항은 무엇인가요?

답변: PostgREST API는 PostgreSQL 9.4 이상이 필요하며, 컨테이너화된 설정에는 Docker가 권장됩니다. 기본 작업에 최소 512MB RAM이 필요하며, 적당한 하드웨어에서도 효율적으로 실행됩니다.

Q2. PostgREST API는 기본적인 CRUD를 넘어 복잡한 쿼리를 처리할 수 있나요?

답변: 네, 임베디드 RPC 호출과 뷰를 통해 PostgreSQL의 모든 SQL 기능을 지원하여 조인, 집계 및 엔드포인트로 노출되는 사용자 지정 함수를 허용합니다.

Q3. PostgREST API는 데이터 보안을 어떻게 보장하나요?

답변: PostgreSQL의 행 수준 보안 및 역할 기반 권한과 기본적으로 통합되어 API 측 취약점 없이 데이터베이스 수준에서 접근 제어를 강제합니다.

Q4. PostgREST API는 프로덕션 환경에 적합한가요?

답변: 물론입니다. JWT 인증, 스키마 격리, 여러 인스턴스를 통한 수평 확장을 포함한 기능을 갖추고 있습니다. 성능을 모니터링하고 규정 준수를 위해 RLS를 적용하십시오.

Q5. PostgREST API를 프런트엔드 프레임워크와 어떻게 통합하나요?

답변: Axios 또는 Fetch와 같은 HTTP 클라이언트를 사용하십시오. React, Vue 또는 Angular 애플리케이션에서 타입 안전성을 위해 OpenAPI 사양에서 TypeScript 타입을 생성하십시오.

결론

우리의 탐구를 되돌아보면, PostgREST API는 데이터베이스 중심 개발을 위한 우아한 솔루션으로 부상하며, PostgreSQL의 강점을 접근 가능한 웹 서비스로 전환합니다. 손쉬운 설정부터 정교한 쿼리에 이르기까지, 적은 오버헤드로 강력한 API를 제공할 수 있도록 지원합니다. 샘플 프로젝트를 재현하고 추가로 실험해 보시기를 권장합니다. 아마도 인증 기능을 추가하여 확장할 수도 있을 것입니다. 애플리케이션이 발전함에 따라 PostgREST API는 민첩성과 안정성을 유지하는 데 없어서는 안 될 동반자가 될 것입니다.

💡

버튼