데이터베이스 쿼리하기 (Query a database)

원문 보기 위키 갱신 2026.10.07

D1은 SQLite의 쿼리 엔진을 사용하므로 대부분의 SQLite SQL 규칙과 호환돼요. SQL 명령을 사용해 D1을 쿼리할 수 있어요.

D1 데이터베이스와 상호작용하는 방법은 여러 가지가 있어요.

코드에서 D1 Workers Binding API를 사용하는 방법.
D1 REST API를 사용하는 방법.
D1 Wrangler 명령을 사용하는 방법.

출처: 문서

본문

SQL로 D1 쿼리하기

D1은 SQLite 의미론을 이해하므로 Workers Binding API나 REST API(및 Wrangler 명령 포함)를 통해 SQL 구문으로 데이터베이스를 쿼리할 수 있어요. 지원되는 SQL 구문에 대해 더 배우려면 D1 SQL API를 참고하세요.

외래 키 관계 사용하기

D1에서 SQL을 사용할 때 데이터베이스의 테이블 간에 외래 키 제약 조건을 정의하고 적용하고 싶을 수 있어요. 외래 키 제약 조건을 사용하면 테이블 간의 관계를 적용하거나, 다른 테이블의 행을 참조하는 행을 삭제하지 못하게 할 수 있어요. 외래 키 관계의 예시는 아래와 같아요.

CREATE TABLE users (
    user_id INTEGER PRIMARY KEY,
    email_address TEXT,
    name TEXT,
    metadata TEXT
)

CREATE TABLE orders (
    order_id INTEGER PRIMARY KEY,
    status INTEGER,
    item_desc TEXT,
    shipped_date INTEGER,
    user_who_ordered INTEGER,
    FOREIGN KEY(user_who_ordered) REFERENCES users(user_id)
)

자세한 내용은 외래 키 정의하기를 참고하세요.

JSON 쿼리하기

D1을 사용하면 데이터베이스에 저장된 JSON 데이터를 쿼리하고 파싱할 수 있어요. 예를 들어 JSON 객체 안의 값을 추출할 수 있어요.

sensor_reading이라는 컬럼에 다음 JSON 객체(type:blob)가 주어졌을 때, 그 값들을 직접 추출할 수 있어요.

{
    "measurement": {
        "temp_f": "77.4",
        "aqi": [21, 42, 58],
        "o3": [18, 500],
        "wind_mph": "13",
        "location": "US-NY"
    }
}

-- Extract the temperature value
SELECT json_extract(sensor_reading, '$.measurement.temp_f')-- returns "77.4" as TEXT

JSON 객체 쿼리에 대해 더 배우려면 JSON 쿼리하기를 참고하세요.

Workers Binding API로 D1 쿼리하기

Workers Binding API는 주로 데이터 플레인(data plane)과 상호작용하며, Worker에서 D1 데이터베이스를 쿼리할 수 있게 해 줘요.

이를 위해서는:

D1 데이터베이스를 Worker에 바인딩하세요.
구문을 준비하세요.
구문을 실행하세요.

export default {
    async fetch(request, env) {
        const {pathname} = new URL(request.url);
        const companyName1 = `Bs Beverages`;
        const companyName2 = `Around the Horn`;
        const stmt = env.DB.prepare(`SELECT * FROM Customers WHERE CompanyName = ?`);

        if (pathname === `/RUN`) {
            const returnValue = await stmt.bind(companyName1).run();
            return Response.json(returnValue);
        }

        return new Response(
            `Welcome to the D1 API Playground!
						\nChange the URL to test the various methods inside your index.js file.`,
        );
    },
};

자세한 내용은 Workers Binding API를 참고하세요.

REST API로 D1 쿼리하기

REST API는 주로 컨트롤 플레인(control plane)과 상호작용하며, D1 데이터베이스를 만들고/관리할 수 있게 해 줘요.

D1 REST API 문서는 D1 REST API를 참고하세요.

Wrangler 명령으로 D1 쿼리하기

Wrangler 명령을 사용해 D1 데이터베이스를 쿼리할 수 있어요. Wrangler 명령은 작업을 수행하기 위해 REST API를 사용한다는 점에 주의하세요.

npx wrangler d1 execute prod-d1-tutorial --command="SELECT * FROM Customers"

🌀 Mapping SQL input into an array of statements
🌀 Executing on local database production-db-backend (<DATABASE_ID>) from .wrangler/state/v3/d1:
┌────────────┬─────────────────────┬───────────────────┐
│ CustomerId │ CompanyName         │ ContactName       │
├────────────┼─────────────────────┼───────────────────┤
│ 1          │ Alfreds Futterkiste │ Maria Anders      │
├────────────┼─────────────────────┼───────────────────┤
│ 4          │ Around the Horn     │ Thomas Hardy      │
├────────────┼─────────────────────┼───────────────────┤
│ 11         │ Bs Beverages        │ Victoria Ashworth │
├────────────┼─────────────────────┼───────────────────┤
│ 13         │ Bs Beverages        │ Random Name       │
└────────────┴─────────────────────┴───────────────────┘