pip install duckdb

-- CSV 파일 읽기 (자동으로 헤더와 타입을 유추함)
SELECT * FROM 'data.csv' LIMIT 10;

-- 특정 조건으로 필터링 및 집계
SELECT 
    department, 
    AVG(salary) AS avg_salary 
FROM 'employees.csv'
GROUP BY department;

-- 여러 개의 Parquet 파일 한 번에 읽기
SELECT COUNT(*) FROM 'sales_2023_*.parquet';

import duckdb
import pandas as pd
맞습니다! 아주 예리하십니다. 

Cloudflare Workers는 브라우저와 다른 런타임(V8 엔진)을 쓰고, 일반 브라우저에서 쓰는 Web Worker나 공유 메모리(`SharedArrayBuffer`), 동기식 I/O 등을 지원하지 않기 때문에 일반적인 `@duckdb/duckdb-wasm` 패키지로는 작동하지 않습니다.

하지만 이 한계를 뚫어내기 위해, 개발자들이 Cloudflare Workers 환경에 맞춰 **동기식 처리를 비동기식(Asyncify)으로 변환하고 단일 스레드로 최적화한 전용 WASM 빌드**들을 만들어 두었습니다 (대표적으로 `@ducklings/workers` 같은 프로젝트가 있습니다).

이를 활용해 **Cloudflare Workers + R2 저장소 + DuckDB WASM**을 조합하는 상세 실전 메뉴얼을 공유해 드립니다.

---

### ⚠️ 1. 구현 전 필수 체크 리스트

* **유료 플랜 필수 (Paid Plan):** Cloudflare Workers의 무료 플랜은 업로드할 수 있는 코드 및 에셋 크기가 **3MB**로 제한됩니다. 하지만 Workers용 DuckDB WASM 파일은 압축해도 약 **9.7MB**에 달합니다. 따라서 월 $5의 유료 플랜(최대 10MB 허용)을 구독하셔야만 배포가 가능합니다.
* **메모리 제한:** Workers는 인스턴스당 메모리가 **128MB**로 엄격하게 제한됩니다. 너무 방대한 양의 데이터를 통째로 메모리에 올리는 쿼리는 실행 시 Worker가 터질 수 있으므로, 적절한 크기의 파일이나 요약된 Parquet 파일을 다루는 것이 좋습니다.
* **데이터 적재(R2):** Workers 자체는 상태가 없는(Stateless) 서버리스 환경이므로 데이터를 저장할 수 없습니다. 분석할 데이터는 Cloudflare의 S3 호환 저장소인 **R2**에 올려두고 HTTP를 통해 읽어야 합니다.

---

### 📦 2. 패키지 설치

Workers 전용으로 빌드된 DuckDB WASM 패키지를 설치합니다.

```bash
npm install @ducklings/workers

// src/index.ts
import { init, DuckDB } from '@ducklings/workers';
import wasmModule from '@ducklings/workers/wasm';

// ⚠️ 전역 스코프에 변수를 선언하여 동일한 Isolates(인스턴스)로 
// 들어오는 요청들이 DB 인스턴스를 공유할 수 있게 합니다.
let db: DuckDB | null = null;

export default {
  async fetch(request: Request, env: any, ctx: any): Promise<Response> {
    try {
      // 1. DuckDB 인스턴스가 없다면 최초 1회 초기화
      if (!db) {
        db = await init(wasmModule);
      }
      
      // 2. 데이터베이스 커넥션 열기
      const conn = await db.connect();
      
      // 3. 쿼리 실행
      // Workers 전용 빌드에는 Parquet 및 httpfs 익스텐션이 내장되어 있습니다.
      // ⚠️ R2 버킷의 데이터를 쿼리할 때는 공개된 URL(또는 커스텀 도메인)을 사용합니다.
      const sql = `
        SELECT category, COUNT(*) as total
        FROM 'https://data.your-domain.com/sales_logs.parquet'
        GROUP BY category
        ORDER BY total DESC
        LIMIT 5;
      `;
      
      const queryResult = await conn.query(sql);
      
      // 4. 결과를 JSON으로 변환
      const results = queryResult.toArray().map(r => r.toJSON());
      
      // 5. 커넥션 종료 (Isolates가 유지되더라도 커넥션은 닫아주는 것이 안전합니다)
      await conn.close();
      
      return new Response(JSON.stringify(results), {
        headers: { 'Content-Type': 'application/json' },
      });
      
    } catch (error: any) {
      return new Response(JSON.stringify({ error: error.message }), {
        status: 500,
        headers: { 'Content-Type': 'application/json' },
      });
    }
  },
};

// 쿼리 실행 전 S3 호환 시크릿을 먼저 생성합니다.
await conn.query(`
  CREATE SECRET (
    TYPE s3,
    KEY_ID '${env.R2_ACCESS_KEY_ID}',
    SECRET '${env.R2_SECRET_ACCESS_KEY}',
    REGION 'auto',
    ENDPOINT 'https://${env.ACCOUNT_ID}.r2.cloudflarestorage.com'
  );
`);

// 이후 s3:// 프로토콜을 사용해 안전하게 비공개 파일을 가져옵니다.
const sql = `SELECT * FROM 's3://my-private-bucket/data.parquet' LIMIT 10;`;
const result = await conn.query(sql);

#### ③ 결과 데이터를 파일로 내보내기
분석이 끝난 데이터를 빠르고 쉽게 다른 포맷으로 저장할 수 있습니다.

```sql
-- 쿼리 결과를 CSV 파일로 저장
COPY (SELECT * FROM my_table WHERE age > 30) TO 'output.csv' (HEADER, DELIMITER ',');

-- 쿼리 결과를 Parquet 파일로 저장 (가장 추천하는 방식)
COPY my_table TO 'output.parquet' (FORMAT PARQUET);

D> .mode box
D> SELECT * FROM 'data.csv' LIMIT 3;
┌───────┬───────┬────────┐
│  id   │ name  │  age   │
│ int32 │ varchar │ int32  │
├───────┼───────┼────────┤
│     1 │ Alice │     30 │
│     2 │ Bob   │     25 │
│     3 │ Carol │     35 │
└───────┴───────┴────────┘

-- 1. CSV에서 데이터를 필터링하여 새로운 CSV로 저장
COPY (
    SELECT * FROM 'huge_data.csv' 
    WHERE status = 'ACTIVE'
) TO 'active_data.csv' (HEADER, DELIMITER ',');

-- 2. CSV를 빠르고 압축률이 좋은 Parquet 포맷으로 변환
COPY (
    SELECT * FROM 'huge_data.csv'
) TO 'compressed_data.parquet' (FORMAT PARQUET);

D> .output report.txt   -- 지금부터 출력은 report.txt로 보냄
D> SELECT department, COUNT(*) FROM 'employees.csv' GROUP BY department;
D> .output stdout       -- 다시 터미널 화면으로 출력 방향 복구

# 옵션 '-c'를 사용하여 쿼리 하나만 실행하고 빠져나오기
duckdb -c "SELECT count(*) FROM 'data.csv';"

# 결과를 CSV 형태로 출력해서 다른 터미널 명령어(grep, awk 등)로 넘기기
duckdb -csv -c "SELECT * FROM 'data.csv';" | grep "Alice"

# SQL 파일에 있는 쿼리를 실행하기
duckdb my_database.db < query.sql

-- DuckDB가 알아서 헤더와 데이터 타입을 분석하여 읽음
SELECT * FROM 'data.csv' LIMIT 5;

SELECT * FROM read_csv(
    'data.csv',
    delim = ',',            -- 구분자 (쉼표, 탭 등)
    header = true,          -- 첫 번째 줄을 컬럼명으로 사용
    nullstr = 'NA',         -- null 값으로 취급할 문자열
    columns = {             -- 명시적으로 데이터 타입 지정 (성능 향상 및 에러 방지)
        'id': 'INTEGER', 
        'name': 'VARCHAR', 
        'joined_date': 'DATE'
    }
);

-- logs_2026_01.csv, logs_2026_02.csv 등을 모두 합쳐서 조회
SELECT count(*) FROM 'logs_2026_*.csv';

SELECT * FROM 'data.json' LIMIT 5;

-- user 객체 안의 name 추출
SELECT 
    id, 
    user->>'name' AS user_name,
    (user->>'age')::INTEGER AS user_age  -- 숫자로 형변환
FROM 'data.json';

SELECT 
    dept, 
    unnest(employees) AS employee 
FROM 'department.json';
-- 결과는 (IT, Alice), (IT, Bob) 총 2개의 행이 됩니다.

-- 1. 텍스트 파일을 'line'이라는 단일 컬럼을 가진 테이블로 읽기
WITH raw_logs AS (
    SELECT * FROM read_csv(
        'app.log', 
        delim = '\n',                   -- 줄바꿈을 구분자로 써서 한 줄씩 읽음
        columns = {'line': 'VARCHAR'},   -- 컬럼명은 line, 타입은 문자열
        header = false
    )
)
-- 2. 정규식을 이용해 IP와 로그 레벨 추출하기
SELECT 
    -- 정규식 그룹()에 매칭된 첫 번째(1), 두 번째(2) 값을 가져옴
    regexp_extract(line, '^(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})', 1) AS ip_address,
    regexp_extract(line, '\[(INFO|ERROR|WARN)\]', 1) AS log_level,
    line AS original_message
FROM raw_logs;

-- 구분자가 공백(' ')인 로그 읽기
SELECT * FROM read_csv(
    'access.log',
    delim = ' ',
    header = false,
    columns = {
        'ip': 'VARCHAR',
        'identity': 'VARCHAR',
        'userid': 'VARCHAR',
        'time': 'VARCHAR',
        'request': 'VARCHAR',
        'status': 'INTEGER',
        'size': 'INTEGER'
    }
);

# 1. 10GB짜리 대용량 로그 파일에서 'ERROR'가 포함된 줄만 찾아 
#    IP별로 카운트한 결과를 터미널 표(box)로 즉시 확인
duckdb -c ".mode box" -c "
  SELECT 
    regexp_extract(line, '^(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})', 1) AS ip,
    count(*) as error_count
  FROM read_csv('app.log', delim='\n', columns={'line':'VARCHAR'})
  WHERE line LIKE '%ERROR%'
  GROUP BY ip
  ORDER BY error_count DESC
  LIMIT 10;
"

npm install duckdb

import { useLoaderData } from "react-router";
import duckdb from "duckdb";

// ⚠️ 주의: 매 요청마다 DB를 새로 띄우면 성능이 저하되므로, 
// 전역 공간에 싱글톤 인스턴스로 선언하여 재사용하는 것이 좋습니다.
const db = new duckdb.Database(":memory:"); // 혹은 영구 저장용 파일 경로 지정

export async function loader() {
  return new Promise((resolve, reject) => {
    // 서버에 적재된 대용량 CSV나 로그 파일을 직접 쿼리
    db.all(
      `SELECT category, COUNT(*) as cnt 
       FROM 'server/data/large_logs.csv' 
       GROUP BY category 
       ORDER BY cnt DESC`,
      (err, rows) => {
        if (err) reject(err);
        resolve({ rows }); // 결과 데이터를 React 컴포넌트로 전달
      }
    );
  });
}

export default function AnalyticsPage() {
  // 타입 세이프하게 로더 데이터를 가져옵니다.
  const { rows } = useLoaderData<typeof loader>();
  
  return (
    <div className="p-6">
      <h1 className="text-xl font-bold mb-4">서버에서 DuckDB로 집계한 결과</h1>
      <ul className="space-y-2">
        {rows.map((row: any) => (
          <li key={row.category} className="border-b pb-1">
            <span className="font-semibold">{row.category}</span>: {row.cnt}개
          </li>
        ))}
      </ul>
    </div>
  );
}

npm install @duckdb/duckdb-wasm

import { useEffect, useState } from "react";
import * as duckdb from "@duckdb/duckdb-wasm";

export default function BrowserAnalytics() {
  const [results, setResults] = useState<any[]>([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function initDuckDB() {
      try {
        // 1. CDN을 통해 WASM 번들 로드
        const JSDELIVR_BUNDLES = duckdb.getJsDelivrBundles();
        const bundle = await duckdb.selectBundle(JSDELIVR_BUNDLES);
        
        const worker = new Worker(bundle.mainWorker!);
        const db = new duckdb.AsyncDuckDB(new duckdb.ConsoleLogger(), worker);
        await db.instantiate(bundle.mainModule, bundle.pthreadWorker);
        
        const conn = await db.connect();
        
        // 2. 외부 URL의 CSV를 브라우저 내 가상 파일로 등록
        await db.registerFileURL(
          'data.csv', 
          'https://raw.githubusercontent.com/.../data.csv', 
          duckdb.DuckDBDataProtocol.HTTP, 
          false
        );
        
        // 3. 쿼리 실행
        const res = await conn.query(`SELECT * FROM 'data.csv' LIMIT 5`);
        setResults(res.toArray().map(r => r.toJSON()));
        
        // 4. 리소스 정리
        await conn.close();
        await db.terminate();
      } catch (err) {
        console.error("DuckDB WASM 에러:", err);
      } finally {
        setLoading(false);
      }
    }
    
    initDuckDB();
  }, []);

  if (loading) return <div>DuckDB WASM 로딩 중...</div>;

  return (
    <div className="p-6">
      <h1 className="text-xl font-bold">브라우저 내 DuckDB WASM 실행 결과</h1>
      <pre className="bg-gray-100 p-4 rounded mt-2">
        {JSON.stringify(results, null, 2)}
      </pre>
    </div>
  );
}

# 서버 사이드(Node.js)용
npm install duckdb

# 클라이언트 사이드(브라우저 WASM)용
npm install @duckdb/duckdb-wasm

import duckdb from 'duckdb';

// 개발 모드에서 HMR(Hot Module Replacement) 시 DB가 계속 재성장하는 것을 방지
declare global {
  var __duckdb: duckdb.Database | undefined;
}

// 싱글톤 인스턴스 반환
if (!global.__duckdb) {
  // 메모리 모드: global.__duckdb = new duckdb.Database(':memory:');
  // 파일 저장 모드:
  global.__duckdb = new duckdb.Database('server_data.db');
}

export const db = global.__duckdb;

// 가독성을 위한 Promise 래퍼 함수
export function queryAsync<T = any>(sql: string): Promise<T[]> {
  return new Promise((resolve, reject) => {
    db.all(sql, (err, rows) => {
      if (err) reject(err);
      else resolve(rows as T[]);
    });
  });
}

import { useLoaderData } from "react-router";
import { queryAsync } from "~/lib/duckdb.server";

// 1. 서버 로더에서 무거운 CSV 데이터 가공
export async function loader() {
  const sql = `
    SELECT product_id, SUM(quantity) as total_sales 
    FROM 'server/data/orders.csv' 
    GROUP BY product_id 
    LIMIT 10
  `;
  const salesData = await queryAsync(sql);
  return { salesData };
}

// 2. 가공된 결과만 브라우저로 전달하여 가볍게 렌더링
export default function SalesPage() {
  const { salesData } = useLoaderData<typeof loader>();

  return (
    <div className="p-4">
      <h1 className="text-xl font-bold">서버 DuckDB 집계 데이터</h1>
      {/* 데이터 렌더링 코드... */}
    </div>
  );
}

import { useState, useEffect } from "react";
import * as duckdb from "@duckdb/duckdb-wasm";

export function useDuckDb() {
  const [db, setDb] = useState<duckdb.AsyncDuckDB | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function init() {
      try {
        const JSDELIVR_BUNDLES = duckdb.getJsDelivrBundles();
        const bundle = await duckdb.selectBundle(JSDELIVR_BUNDLES);
        
        const worker = new Worker(bundle.mainWorker!);
        const asyncDb = new duckdb.AsyncDuckDB(new duckdb.ConsoleLogger(), worker);
        await asyncDb.instantiate(bundle.mainModule, bundle.pthreadWorker);
        
        setDb(asyncDb);
      } catch (error) {
        console.error("DuckDB WASM 초기화 실패:", error);
      } finally {
        setLoading(false);
      }
    }
    
    init();
  }, []);

  return { db, loading };
}

import { useState } from "react";
import { useDuckDb } from "~/hooks/useDuckDb";

export default function ClientUpload() {
  const { db, loading } = useDuckDb();
  const [results, setResults] = useState<any[]>([]);

  const handleFileChange = async (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0];
    if (!file || !db) return;

    // 브라우저로 들어온 파일을 DuckDB WASM의 가상 파일 시스템에 등록
    await db.registerFileHandle('user_upload.csv', file, duckdb.DuckDBDataProtocol.BROWSER_FILEREADER, false);
    
    const conn = await db.connect();
    const res = await conn.query(`SELECT * FROM 'user_upload.csv' LIMIT 10`);
    
    setResults(res.toArray().map(r => r.toJSON()));
    await conn.close();
  };

  if (loading) return <div>브라우저 내 DuckDB 엔진 로딩 중...</div>;

  return (
    <div className="p-4">
      <h1 className="text-xl font-bold">클라이언트 DuckDB 분석</h1>
      <input type="file" accept=".csv" onChange={handleFileChange} />
      {/* 결과 렌더링... */}
    </div>
  );
}

// vite.config.ts
import { reactRouter } from "@react-router/dev/vite";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [reactRouter()],
  ssr: {
    // ⚠️ 서버 전용 라이브러리인 duckdb를 Vite 번들링에서 제외합니다. (필수!)
    external: ['duckdb'], 
  },
  optimizeDeps: {
    // 클라이언트 WASM 모듈을 최적화 사전 로드 목록에 추가합니다.
    include: ['@duckdb/duckdb-wasm']
  }
});

npm install @ducklings/workers

// src/index.ts
import { init, DuckDB } from '@ducklings/workers';
import wasmModule from '@ducklings/workers/wasm';

// ⚠️ 전역 스코프에 변수를 선언하여 동일한 Isolates(인스턴스)로 
// 들어오는 요청들이 DB 인스턴스를 공유할 수 있게 합니다.
let db: DuckDB | null = null;

export default {
  async fetch(request: Request, env: any, ctx: any): Promise<Response> {
    try {
      // 1. DuckDB 인스턴스가 없다면 최초 1회 초기화
      if (!db) {
        db = await init(wasmModule);
      }
      
      // 2. 데이터베이스 커넥션 열기
      const conn = await db.connect();
      
      // 3. 쿼리 실행
      // Workers 전용 빌드에는 Parquet 및 httpfs 익스텐션이 내장되어 있습니다.
      // ⚠️ R2 버킷의 데이터를 쿼리할 때는 공개된 URL(또는 커스텀 도메인)을 사용합니다.
      const sql = `
        SELECT category, COUNT(*) as total
        FROM 'https://data.your-domain.com/sales_logs.parquet'
        GROUP BY category
        ORDER BY total DESC
        LIMIT 5;
      `;
      
      const queryResult = await conn.query(sql);
      
      // 4. 결과를 JSON으로 변환
      const results = queryResult.toArray().map(r => r.toJSON());
      
      // 5. 커넥션 종료 (Isolates가 유지되더라도 커넥션은 닫아주는 것이 안전합니다)
      await conn.close();
      
      return new Response(JSON.stringify(results), {
        headers: { 'Content-Type': 'application/json' },
      });
      
    } catch (error: any) {
      return new Response(JSON.stringify({ error: error.message }), {
        status: 500,
        headers: { 'Content-Type': 'application/json' },
      });
    }
  },
};

// 쿼리 실행 전 S3 호환 시크릿을 먼저 생성합니다.
await conn.query(`
  CREATE SECRET (
    TYPE s3,
    KEY_ID '${env.R2_ACCESS_KEY_ID}',
    SECRET '${env.R2_SECRET_ACCESS_KEY}',
    REGION 'auto',
    ENDPOINT 'https://${env.ACCOUNT_ID}.r2.cloudflarestorage.com'
  );
`);

// 이후 s3:// 프로토콜을 사용해 안전하게 비공개 파일을 가져옵니다.
const sql = `SELECT * FROM 's3://my-private-bucket/data.parquet' LIMIT 10;`;
const result = await conn.query(sql);

name = "my-duckdb-worker"
main = "src/index.ts"
compatibility_date = "2024-01-01"

# ⚠️ 유료 플랜(Standard) 설정 (월 $5)
# 무료 플랜의 3MB 제한을 넘어 10MB까지 업로드 가능하게 합니다.
compatibility_flags = [ "nodejs_compat" ]

[observability]
enabled = true

# R2 버킷 연결 (선택 사항)
[[r2_buckets]]
binding = 'MY_BUCKET'
bucket_name = 'my-analytics-data'

# 환경 변수 (비공개 S3 액세스 시 필요)
[vars]
R2_ACCESS_KEY_ID = "your_access_key"
# R2_SECRET_ACCESS_KEY는 'wrangler secret put'으로 별도 관리 권장

// vite.config.ts (Workers 환경용)
export default {
  build: {
    assetsInlineLimit: 0, // WASM 파일이 소스코드에 인라인화되지 않도록 방지
  },
  server: {
    fs: {
      allow: ['..'] // 프로젝트 상위 폴더의 WASM 참조 허용
    }
  }
};