Turso 퀵스타트

원문 보기 위키 갱신 2026.10.11

Turso 퀵스타트 (SQL over HTTP)

HTTP 위에서 SQL을 바로 날리면 SDK 설치 없이도 Turso 데이터베이스를 다룰 수 있어요. 이 퀵스타트에서는 원격 Turso 데이터베이스에 연결하고 SQL over HTTP로 SQL 쿼리를 실행하는 방법을 배워요.

출처: 문서

본문

이 퀵스타트에서 배울 내용은 다음과 같아요:

원격 Turso 데이터베이스에 연결하기
SQL over HTTP로 SQL 쿼리 실행하기

	`@tursodatabase/serverless`	`@libsql/client`	Raw HTTP
Use with	Turso 데이터베이스	libSQL 데이터베이스	모든 데이터베이스
Dependencies	`fetch`만 사용 — 네이티브 의존성 없음	Node.js 또는 `/web` 서브패스 필요	없음 (아무 HTTP 클라이언트)
ORM support	아직 미지원	Drizzle, Prisma 등	N/A

데이터베이스 엔진에 맞춰 드라이버를 고르면 돼요. Turso 데이터베이스에는 @tursodatabase/serverless, libSQL 데이터베이스에는 @libsql/client.

@tursodatabase/serverless

@tursodatabase/serverless 패키지는 fetch API만으로 Turso에 연결해요. 네이티브 의존성이 없어서 edge와 serverless 런타임에서 가장 가벼운 선택지예요.

1. 설치

npm install @tursodatabase/serverless

2. 연결과 쿼리

import { connect } from "@tursodatabase/serverless";

const conn = connect({
  url: process.env.TURSO_DATABASE_URL,
  authToken: process.env.TURSO_AUTH_TOKEN,
});

const stmt = await conn.prepare("SELECT * FROM users WHERE id = ?");
const row = await stmt.get([123]);

libSQL 클라이언트 API와의 호환이 필요하다면 compat 모듈을 사용해요.

import { createClient } from "@tursodatabase/serverless/compat";

const client = createClient({
  url: process.env.TURSO_DATABASE_URL,
  authToken: process.env.TURSO_AUTH_TOKEN,
});

const result = await client.execute("SELECT * FROM users WHERE id = ?", [123]);

@libsql/client

@libsql/client 패키지는 Turso 생태계 전반에서 쓰이는 프로덕션 준비가 끝난 libSQL 드라이버예요. serverless와 edge 런타임에서는 /web 임포트를 사용해요.

1. 설치

npm install @libsql/client

2. 연결과 쿼리

import { createClient } from "@libsql/client/web";

const client = createClient({
  url: process.env.TURSO_DATABASE_URL!,
  authToken: process.env.TURSO_AUTH_TOKEN!,
});

const result = await client.execute({
  sql: "SELECT * FROM users WHERE id = ?",
  args: [123],
});

참고: edge와 serverless 런타임에서는 @libsql/client 대신 @libsql/client/web을 사용해 주세요. /web 임포트는 HTTP 프로토콜을 사용해요.

Raw HTTP

HTTP 클라이언트만 있으면 쿼리를 직접 보낼 수도 있어요.

1. HTTP 데이터베이스 URL 만들기

Turso CLI나 Platform API로 데이터베이스 URL을 확인해요.

turso db show <database-name> --http-url

참고: URL 끝에 /v2/pipeline을 붙이고 진행해요.

2. 데이터베이스 인증 토큰 만들기

Turso CLI나 Platform API로 데이터베이스의 새 인증 토큰을 생성해요.

turso db tokens create <database-name>

3. JSON 요청 페이로드 만들기

쿼리를 JSON으로 보낼 거예요. SQL 문을 실행하고 연결을 바로 닫는 페이로드를 만들어 봐요.

{
  "requests": [
    { "type": "execute", "stmt": { "sql": "SELECT * FROM users" } },
    { "type": "close" }
  ]
}

참고: stmt.sql을 실제로 가지고 있는 테이블에서 조회하도록 수정해 주세요. 바인드 파라미터 예시는 레퍼런스 페이지에 있어요.

4. HTTP 요청 실행하기

사용하는 언어에 맞는 HTTP 클라이언트 라이브러리로, 만들어 둔 URL에 요청을 보내고 Authorization 헤더에 생성한 토큰을, 본문에 SQL 문이 담긴 JSON을 넣어요.

Base URL 뒤에 요청을 받아 주는 실제 파이프라인 URL인 /v2/pipeline을 붙여야 해요.

const url = "https://[databaseName]-[organizationSlug].turso.io/v2/pipeline";
const authToken = "...";

fetch(url, {
  method: "POST",
  headers: {
    Authorization: *** ${authToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    requests: [
      { type: "execute", stmt: { sql: "SELECT * FROM users" } },
      { type: "close" },
    ],
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data))
  .catch((err) => console.log(err));

require 'net/http'
require 'json'
require 'uri'

url = "https://[databaseName]-[organizationSlug].turso.io/v2/pipeline"
auth_token = "..."

uri = URI(url)
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{auth_token}"
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "requests": [
    { "type": "execute", "stmt": { "sql": "SELECT * FROM users" } },
    { "type": "close" }
  ]
})

begin
  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
    http.request(request)
  end

  puts JSON.parse(response.body)
rescue => e
  puts e.message
end

응답 (Response)

응답은 results 배열에 쿼리 결과를 담은 JSON 객체로 돌아오고, 대략 이런 모습이에요.

{
  "baton": null,
  "base_url": null,
  "results": [
    {
      "type": "ok",
      "response": {
        "type": "execute",
        "result": {
          "cols": [],
          "rows": [],
          "affected_row_count": 0,
          "last_insert_rowid": null,
          "replication_index": "1"
        }
      }
    },
    {
      "type": "ok",
      "response": {
        "type": "close"
      }
    }
  ]
}

값에 플레이스홀더를 쓰고 싶다면 아래처럼 하면 돼요.

{
  "type": "execute",
  "stmt": {
    "sql": "SELECT * FROM users WHERE id = ?",
    "args": [
      {
        "type": "integer",
        "value": "1"
      }
    ]
  }
}

{
  "type": "execute",
  "stmt": {
    "sql": "SELECT * FROM users WHERE name = :name OR name = $second_name OR name = @third_name",
    "named_args": [
      {
        "name": "name",
        "value": {
          "type": "text",
          "value": "Turso"
        }
      },
      {
        "name": "second_name",
        "value": {
          "type": "text",
          "value": "Not Turso"
        }
      },
      {
        "name": "third_name",
        "value": {
          "type": "text",
          "value": "Maybe Turso"
        }
      }
    ]
  }
}

참고: 각 인자의 type 필드는 컬럼 데이터 타입에 해당하고, null, integer, float, text, blob 중 하나예요.

노트: JSON에서 value는 정밀도 손실을 피하려고 String으로 표현해요. 일부 JSON 구현은 모든 숫자를 64비트 부동소수점으로 다루거든요.

더 알아보기 (Learn more)

HTTP 레퍼런스 — 파이프라인 요청·응답 형식 전체 정리
Turso Database 퀵스타트 — Turso 데이터베이스 생성과 관리
libSQL — libSQL 데이터베이스와 클라이언트 소개
Platform API — 데이터베이스와 토큰을 API로 관리하기