Airbyte

Airbyte 는 여러 곳에 흩어진 데이터를 한곳으로 옮겨 담는 오픈 소스 도구입니다. 서비스의 데이터베이스나 외부 서비스에 쌓인 데이터를 정해진 때마다 꺼내 분석용 저장소에 넣습니다. 꺼내는 쪽과 넣는 쪽마다 커넥터라는 작은 프로그램을 끼워 씁니다. 데이터를 다듬는 일은 하지 않고 옮기는 일만 합니다.

상세

Airbyte 는 ELT(Extract Load Transform, 추출·적재·변환)의 세 단계 가운데 앞의 두 단계를 맡는 도구입니다. 원천에서 데이터를 꺼내는 추출과, 그 데이터를 손대지 않고 저장소에 넣는 적재입니다.

이 절은 쇼핑몰 하나를 예로 듭니다. 주문은 서비스의 PostgreSQL 에 있고 결제 내역은 외부 결제 서비스에 있습니다. 이 둘을 분석용 저장소 하나로 모으는 과정을 따라갑니다. 꺼내는 쪽, 넣는 쪽, 어디까지 옮겼는지 기억하는 법을 차례로 봅니다.

Airbyte 가 맡는 단계

데이터 웨어하우스는 여러 서비스의 데이터를 모아 분석 조회를 빠르게 돌리는 분석 전용 데이터베이스입니다. 앞에서 분석용 저장소라 부른 것이 대개 이것입니다. Airbyte 에서는 데이터를 넣는 이쪽을 목적지(destination)라고 합니다. 데이터를 꺼내는 쪽은 원천(source)입니다.

ELT 는 원천의 데이터를 먼저 웨어하우스에 그대로 옮겨 둡니다. 다듬는 일은 웨어하우스 안에서 나중에 합니다.

Airbyte 는 옮기는 데까지만 합니다. 옮겨 온 원본을 분석용 표로 바꾸는 변환은 dbt 같은 변환 도구가 맡습니다. 그래서 두 도구가 한 데이터 파이프라인의 앞뒤에 나란히 서는 일이 많습니다.

flowchart TD
    subgraph 원천
        P["서비스 PostgreSQL · 주문"]
        S["결제 서비스 · 결제 내역"]
    end
    subgraph Airbyte
        SC1["PostgreSQL 원천 커넥터"]
        SC2["결제 서비스 원천 커넥터"]
        DC["목적지 커넥터"]
    end
    W["데이터 웨어하우스"]
    D["dbt · 분석용 표로 변환"]
    P --> SC1
    S --> SC2
    SC1 --> DC
    SC2 --> DC
    DC --> W
    W --> D

원천마다 원천 커넥터가 하나씩 붙어 데이터를 꺼냅니다. 목적지 커넥터는 그 데이터를 웨어하우스에 넣습니다. 둘은 아래 「원천 커넥터와 목적지 커넥터」 소절에서 풉니다.

Airbyte 없이 옮길 때

처음에는 스크립트 하나로 충분해 보입니다. 주문 표를 조회해 웨어하우스에 넣는 코드 몇십 줄입니다. 원천이 늘면 곤란한 일이 셋 생깁니다.

첫째는 원천마다 다른 꺼내는 법입니다. 결제 서비스는 API(Application Programming Interface, 프로그램끼리 부르는 접점)로 데이터를 내줍니다. 그런데 API 마다 인증 방식이 다릅니다. 결과를 여러 쪽으로 나눠 주는 페이지네이션 방식도 다릅니다. 원천 하나에 스크립트 하나가 붙습니다.

둘째는 어디까지 옮겼는지입니다. 매번 표 전체를 옮기면 표가 커질수록 느려집니다. 새로 바뀐 행만 옮기려면 지난번에 어디까지 옮겼는지를 어딘가에 적어 둬야 합니다. 옮기다 중간에 죽으면 어디서부터 다시 할지도 정해야 합니다.

셋째는 넣는 쪽의 수입니다. 웨어하우스를 하나 더 쓰거나 바꾸면 모든 스크립트의 넣는 부분을 고쳐야 합니다. 원천이 다섯이고 목적지가 둘이면 짜야 할 조합이 열 개가 됩니다.

Airbyte 는 이 셋을 각각 받아 줍니다. 꺼내는 법은 원천 커넥터 안에 가둡니다. 어디까지 옮겼는지는 상태로 기록합니다(아래 「상태와 이어 받기」에서 풉니다). 넣는 법은 목적지 커넥터 안에 가둡니다.

원천 커넥터와 목적지 커넥터

커넥터는 한쪽 끝을 맡는 작은 프로그램입니다. 원천 커넥터는 데이터를 읽어 내보내기만 합니다. 목적지 커넥터는 받은 데이터를 저장소에 쓰기만 합니다.

두 커넥터 사이로는 데이터가 한 건씩 오갑니다. 이 한 건이 레코드(record)입니다. 데이터베이스라면 표의 한 행이 레코드 하나입니다.

레코드는 언제나 같은 모양입니다. 레코드 하나가 JSON(JavaScript Object Notation) 객체 하나입니다. JSON 은 중괄호 안에 이름과 값을 짝지어 적는 글자 형식입니다.

모양이 하나로 정해져 있으니 원천 커넥터는 어느 목적지로 가는지 몰라도 됩니다. 목적지 커넥터도 어디서 왔는지 몰라도 됩니다. 그래서 원천 다섯과 목적지 둘이면 앞 소절의 조합 열 개 대신 커넥터 일곱 개로 끝납니다.

커넥터 하나는 Docker 이미지 하나로 배포됩니다. Docker 는 프로그램과 그 프로그램이 필요로 하는 실행 환경을 이미지 하나로 묶어 어디서나 같은 모습으로 띄우는 도구입니다. 이미지를 띄워 돌고 있는 것을 컨테이너라고 합니다.

이미지로 묶여 있으니 커넥터를 무슨 언어로 짰든 Airbyte 는 똑같이 컨테이너로 띄워서 부릅니다.

연결과 스트림

스트림은 원천이 내놓는 데이터 묶음 하나입니다. 데이터베이스면 표 하나가 스트림 하나입니다. API 면 「주문 목록」·「고객 목록」처럼 엔드포인트 하나가 대개 스트림 하나입니다.

원천 커넥터는 자기가 내놓을 수 있는 스트림의 목록을 알려 줍니다. 이 목록이 카탈로그(catalog)입니다. 카탈로그에는 스트림마다 어떤 열이 어떤 타입으로 들어 있는지가 적혀 있습니다.

그 모양은 JSON 스키마로 적습니다. JSON 스키마는 JSON 데이터의 모양을 JSON 으로 적어 두는 규칙입니다. 어떤 열이 어떤 타입인지 미리 알아야 목적지가 표를 알맞게 만들 수 있습니다.

연결(connection)은 원천 하나와 목적지 하나를 묶은 설정입니다. 연결이 한 번 도는 것이 동기화(sync)입니다. 원천에서 읽어 목적지에 다 쓰기까지가 동기화 한 번입니다. 연결에는 세 가지를 정합니다.

일정이 되면 Airbyte 가 동기화를 하나 시작합니다. 동기화마다 두 커넥터를 띄웁니다.

동기화 방식

스트림마다 「얼마나 읽나」와 「어떻게 쓰나」를 하나씩 고릅니다. 둘을 합친 것이 그 스트림의 동기화 방식입니다.

읽는 쪽은 둘입니다. 전체 새로 고침(Full Refresh)은 동기화할 때마다 스트림을 처음부터 끝까지 다 읽습니다. 증분(Incremental)은 지난번 이후에 새로 생기거나 바뀐 행만 읽습니다. 바뀐 것만 다루는 방식 일반은 증분 처리라고 부릅니다.

쓰는 쪽은 셋입니다. 덮어쓰기(Overwrite)는 목적지의 표를 비우고 새로 씁니다. 덧붙이기(Append)는 이미 있는 행 뒤에 이어 붙입니다. 중복 제거 덧붙이기(Append + Deduped)는 이어 붙이되, 같은 행이 여럿이면 가장 최근 것 하나만 남깁니다.

대표 조합은 넷입니다.

커서와 기본 키

증분으로 읽으려면 「어디까지 읽었나」를 가를 열이 하나 있어야 합니다. 이 열이 커서 필드(cursor field)입니다. 행이 생기거나 바뀔 때마다 값이 커지는 열이 커서가 됩니다. 주문 표의 updated_at 이 대표입니다.

읽은 행 가운데 커서의 가장 큰 값은 상태로 남습니다(아래 「상태와 이어 받기」). 다음 동기화 때 Airbyte 가 이 값을 원천 커넥터에 넘깁니다. 원천 커넥터는 그 값보다 큰 행만 읽습니다. 예를 들어 지난번 마지막 값이 새벽 세 시였다면, 이번에는 updated_at 이 새벽 세 시보다 늦은 행만 가져옵니다.

중복 제거는 「같은 행」을 가를 열도 필요로 합니다. 이 열이 기본 키입니다. 주문 표라면 id 입니다. 같은 id 가 여러 번 들어오면 커서 값이 가장 큰 줄이 최신으로 남습니다.

커서로 읽는 증분에는 빈틈이 하나 있습니다. 원천에서 지워진 행은 아예 사라져서 「바뀐 행」으로 잡히지 않습니다. 목적지에는 지워진 주문이 계속 남습니다. 이 빈틈은 아래 「변경 데이터 캡처」 소절이 메웁니다.

상태와 이어 받기

동기화 도중에 커넥터가 죽을 수 있습니다. 그때 처음부터 다시 읽지 않으려고 Airbyte 는 상태(state)를 남깁니다. 상태는 「이 스트림은 여기까지 옮겼다」를 적은 작은 기록입니다. 커서 필드의 마지막 값이 대개 그 내용입니다.

커넥터는 결과를 한 줄씩 내보냅니다. 이 한 줄 한 줄이 메시지입니다. 원천 커넥터가 내는 메시지는 대부분 레코드를 싣습니다. 그 사이사이에 상태를 실은 메시지가 끼어 나옵니다.

상태는 이렇게 저장됩니다. 원천 커넥터가 레코드와 상태 메시지를 섞어 내보냅니다. Airbyte 가 그 사이에서 원천의 출력을 목적지의 입력으로 넘겨 줍니다.

목적지 커넥터는 상태 앞의 레코드를 저장소에 다 쓴 뒤에 같은 상태를 되돌려 보냅니다. Airbyte 는 목적지가 되돌려 보낸 상태만 저장합니다.

sequenceDiagram
    participant 원천 as 원천 커넥터
    participant AB as Airbyte
    participant 목적지 as 목적지 커넥터
    원천->>AB: 레코드 여러 건
    원천->>AB: 상태 · updated_at 03:00 까지
    AB->>목적지: 레코드 여러 건과 상태를 그대로 넘긴다
    목적지->>목적지: 레코드를 저장소에 다 쓴다
    목적지-->>AB: 같은 상태를 되돌려 보낸다
    AB->>AB: 되돌아온 상태를 저장한다
    Note over 원천,목적지: 다음 동기화는 저장된 상태부터 읽는다

원천이 낸 상태를 바로 저장하면, 목적지가 쓰기 전에 죽었을 때 그 레코드들이 영영 빠집니다. 목적지가 다 썼다고 확인한 상태만 저장하므로 빠지는 레코드가 없습니다. 이렇게 진행 위치를 확정해 두는 일이 체크포인트입니다.

대신 겹칠 수는 있습니다. 목적지가 레코드 일부를 쓰고 상태를 돌려주기 전에 죽으면, 다음 동기화가 그 레코드들을 한 번 더 옮깁니다. 그래서 Airbyte 에서 레코드는 「적어도 한 번」 옮겨집니다. 앞 소절의 중복 제거 덧붙이기가 이 겹침을 걸러 줍니다.

변경 데이터 캡처

변경 데이터 캡처(CDC, Change Data Capture)는 데이터베이스가 바뀐 내용을 적어 두는 로그를 읽어 바뀐 행을 뽑아내는 방식입니다. 표를 조회하는 대신 로그를 따라 읽으니 지운 행도 「지워졌다」는 기록으로 잡힙니다.

데이터베이스는 데이터를 바꾸기 전에 그 변경을 먼저 로그에 적습니다. PostgreSQL 에서는 이 로그를 WAL(Write-Ahead Log, 먼저 쓰는 로그)이라고 부릅니다. MySQL 에서는 바이너리 로그가 같은 노릇을 합니다.

Airbyte 의 데이터베이스 원천 커넥터 가운데 여럿이 CDC 로 읽는 방식을 고를 수 있게 해 줍니다. 그 안에서는 Debezium 이 로그를 읽습니다. Debezium 은 여러 데이터베이스의 변경 로그를 읽어 바뀐 행을 한 건씩 내주는 오픈 소스 도구입니다.

CDC 로 읽으면 상태에는 커서 값 대신 로그의 어디까지 읽었는지가 적힙니다. 지운 행은 목적지에 「지워졌음」 표시가 붙은 줄로 들어옵니다.

대가로 원천 데이터베이스 쪽 설정이 필요합니다. 로그를 바깥에서 읽을 수 있게 켜 둬야 합니다. 읽기 권한도 따로 줘야 합니다.

Airbyte 프로토콜

커넥터와 Airbyte 사이의 약속이 Airbyte 프로토콜입니다. 커넥터가 어떤 언어로 짜였든 이 약속만 지키면 Airbyte 가 부를 수 있습니다.

약속은 단순합니다. 커넥터는 명령 하나를 받습니다. 명령은 커넥터를 실행할 때 명령 줄 인자로 건넵니다. 설정 같은 값은 JSON 파일로 함께 넘깁니다.

커넥터는 결과를 JSON 한 줄씩 표준 출력에 씁니다. 표준 출력은 프로그램이 결과를 내보내는 기본 통로입니다. 터미널에서 실행하면 화면에 찍히는 바로 그 출력입니다. 앞 「상태와 이어 받기」에서 본 메시지가 이 한 줄 한 줄입니다.

반대로 프로그램이 읽어 들이는 기본 통로는 표준 입력입니다. 목적지 커넥터는 레코드를 여기로 받습니다. Airbyte 가 원천의 표준 출력을 목적지의 표준 입력으로 이어 줍니다.

명령은 다섯입니다. 앞의 넷은 원천 커넥터가, 마지막 하나는 목적지 커넥터가 받습니다.

spec 이 내놓는 설정 항목이 Airbyte 웹 화면의 입력 칸이 됩니다. 접속 주소·계정·비밀번호 같은 칸입니다. check 는 연결을 만들 때 그 값으로 실제 접속이 되는지 미리 시험하는 데 씁니다.

메시지마다 type 칸이 있어서 무슨 메시지인지 가릅니다. read 가 내놓는 메시지는 주로 둘입니다. 데이터 한 건을 실은 RECORD 와 진행 위치를 실은 STATE 입니다.

아래는 주문 한 건을 실은 RECORD 메시지를 보기 좋게 줄바꿈한 것입니다. 실제로는 이 전체가 한 줄로 나옵니다.

{
  "type": "RECORD",
  "record": {
    "stream": "orders",
    "data": {
      "id": 1042,
      "amount": 32000,
      "updated_at": "2026-10-16T02:41:00Z"
    },
    "emitted_at": 1792118465000
  }
}

stream 은 이 행이 어느 스트림의 것인지를, data 는 행의 값을 담습니다. emitted_at 은 커넥터가 이 메시지를 낸 시각을 밀리초로 적은 수입니다. 이 밖에 진행 로그를 싣는 LOG, 카탈로그를 싣는 CATALOG 같은 메시지도 있습니다.

커넥터를 만드는 방법

원하는 원천의 커넥터가 없으면 직접 만듭니다. 길은 셋입니다. 코드를 덜 짜는 쪽부터 봅니다.

첫째는 커넥터 빌더입니다. Airbyte 웹 화면 안에서 주소·인증·페이지네이션 같은 칸을 채워 커넥터를 만듭니다. 이렇게 코드를 거의 짜지 않고 정해진 항목만 채워 프로그램을 만드는 방식을 로우코드라고 합니다.

둘째는 로우코드 선언입니다. 커넥터 빌더에서 채우는 내용을 YAML(YAML Ain't Markup Language) 파일로 직접 적습니다. YAML 은 들여쓰기로 계층을 나타내는 설정 파일 형식입니다. 「선언」은 어떻게 부를지를 코드로 짜지 않고 무엇을 부를지만 적는다는 뜻입니다.

셋째는 CDK(Connector Development Kit)입니다. CDK 는 Airbyte 가 내주는 커넥터 개발용 라이브러리입니다. Python 등으로 코드를 짭니다. 프로토콜 메시지를 만들고 상태를 다루는 반복 코드는 CDK 가 대신 맡습니다.

셋을 견주면 아래 표와 같습니다.

커넥터 빌더와 로우코드 선언은 웹 API 의 공통 모양에 기댑니다. 주소를 부르고, 인증하고, 쪽을 넘기며 결과를 모으는 흐름입니다. 그 흐름에서 벗어나는 원천은 CDK 로 코드를 짭니다.

CDK 를 안 써도 커넥터는 만들 수 있습니다. 커넥터가 Docker 이미지이고 프로토콜이 표준 출력의 JSON 이므로, 그 둘만 맞추면 어떤 언어로 짜도 됩니다.

Airbyte Cloud 와 자체 설치

Airbyte 는 두 형태로 씁니다. 하나는 오픈 소스판을 내 서버에 직접 설치하는 것입니다. 자체 설치판은 쿠버네티스 위에서 돕니다. 쿠버네티스는 컨테이너 여럿을 여러 서버에 나눠 띄우고 관리하는 도구입니다. 동기화 한 번마다 커넥터 컨테이너가 떴다 내려가므로 이런 관리 도구가 밑에 깔립니다.

다른 하나는 Airbyte Cloud 입니다. Airbyte 를 만드는 회사가 직접 운영하는 유료 서비스입니다. 설치와 업그레이드는 그 회사가 맡습니다. 사용자는 웹 화면에서 연결만 만듭니다.

Airbyte 에는 자체 일정 기능이 있습니다. 그래도 큰 파이프라인에서는 Apache Airflow 같은 워크플로우 오케스트레이션 도구가 Airbyte 의 API 로 동기화를 시작시키기도 합니다. 워크플로우 오케스트레이션 도구는 여러 작업의 실행 순서와 일정을 한곳에서 정하는 도구입니다. 예를 들어 동기화가 끝나면 이어서 dbt 를 돌리게 합니다.

맞는 경우와 안 맞는 경우

Airbyte 는 원천이 여럿이고 그 대부분에 이미 만들어진 커넥터가 있을 때 씁니다. 특히 외부 SaaS(Software as a Service, 웹으로 빌려 쓰는 소프트웨어)가 많을 때 쓸모가 큽니다. API 마다 스크립트를 짜고 고치는 일을 커넥터가 대신 집니다.

실시간 흐름에는 맞지 않습니다. Airbyte 는 일정이 될 때마다 한 번씩 도는 배치 처리 도구입니다. 이벤트가 생기는 즉시 다음 시스템으로 넘겨야 하면 Apache Kafka 같은 스트림 처리 쪽 도구를 씁니다. 여기서 「스트림」은 앞에서 본 표 단위 스트림과 다른 말입니다. 끝없이 이어지는 이벤트의 흐름을 뜻합니다.

옮기는 도중에 데이터를 다듬는 일도 맡지 않습니다. 원본을 그대로 넣습니다. 다듬는 일은 웨어하우스 안의 dbt 같은 도구에 넘깁니다. 원천이 하나나 둘뿐이면 이 구조를 띄우고 굴리는 비용이 스크립트 몇 개보다 클 수 있습니다.

대가도 있습니다. 동기화마다 컨테이너가 여럿 떴다 내려가므로 돌리는 데 메모리와 CPU(Central Processing Unit, 중앙 처리 장치)가 듭니다. 커넥터마다 만든 쪽과 손보는 정도가 달라서 품질이 고르지 않습니다. 레코드가 겹쳐 옮겨질 수 있으므로 목적지에서 중복을 걸러 내야 할 때가 있습니다. 같은 일을 하는 상용 서비스로 Fivetran 이 있습니다.

관련 항목

Airbyte 가 맡는 데이터 처리 단계

ELT · ETL · 추출 · 적재 · 변환 · 데이터 파이프라인 · 배치 처리 · 데이터 통합

Airbyte 가 속하는 분야

데이터 엔지니어링 · 데이터 플랫폼 · 데이터 웨어하우스 · 데이터 레이크

Airbyte 가 데이터를 꺼내는 원천

PostgreSQL · MySQL · MongoDB · REST API · SaaS · API · 페이지네이션

Airbyte 가 데이터를 넣는 저장소

Snowflake · BigQuery · Amazon Redshift · Amazon S3 · Databricks · DuckDB

Airbyte 를 이루는 구성 요소

커넥터 · 스트림 · 카탈로그 (Airbyte) · 연결 (Airbyte) · Airbyte 프로토콜 · 커넥터 빌더 · CDK (Airbyte)

Airbyte 동기화가 다루는 개념

증분 처리 · 전체 새로 고침 · 커서 필드 · 기본 키 · 중복 처리 · 중복 적재 · 체크포인트 · 적어도 한 번 전달 · 멱등성

Airbyte 가 기대는 형식과 기술

JSON · JSON 스키마 · YAML · 표준 출력 · Docker · Kubernetes · Python

Airbyte 가 바뀐 행을 읽는 방식

변경 데이터 캡처 · Debezium · WAL · 바이너리 로그 · 논리 복제

Airbyte 앞뒤에서 함께 도는 도구

dbt · Apache Airflow · Dagster · 워크플로우 오케스트레이션 · cron

Airbyte 와 같은 일을 두고 겨루는 도구

Fivetran · Meltano · Singer · Stitch · Apache NiFi · Apache Kafka · 스트림 처리