본문 바로가기
WIKI 기술 지식 베이스

SQL over HTTP 레퍼런스

원문 보기 위키 갱신

Turso 데이터베이스는 HTTP로 접근할 수 있어요. 이 API를 이용하면 SQL over HTTP 방식으로 SQL 작업을 수행하고, 서버 버전 정보를 확인하고, 상태(health)를 모니터링할 수 있어요.

출처: 문서

본문

참고: 가능하면 네이티브 SDK 사용을 추천해요.

Base URL

데이터베이스 URL의 프로토콜만 바꾸면 돼요. Turso 데이터베이스는 turso://, libSQL 데이터베이스는 libsql://를 https://로 바꿔 주세요.

https://[databaseName]-[organizationSlug].turso.io

데이터베이스 Base URL은 Turso CLI로 확인할 수 있어요.

Turso CLI로 HTTP URL 얻기

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

인증 (Authentication)

Turso는 Bearer 인증 방식을 사용해요. 보호된 요청에는 모두 Authorization 헤더에 API 토큰을 담아야 해요.

Authorization: Bearer ***

Turso CLI로 토큰 만들기

turso db tokens create <database-name>

엔드포인트 (Endpoints)

데이터베이스에서는 아래 엔드포인트를 사용할 수 있어요.

POST /v2/pipeline

/v2/pipeline 엔드포인트로 데이터베이스를 조회할 수 있어요. 이 엔드포인트는 데이터베이스 커넥션에 대해 수행할 작업 목록을 받아요. 지원되는 작업 타입은 다음과 같아요.

  • execute: 커넥션에서 문(statement)을 실행해요.
  • close: 커넥션을 닫아요.

단순 쿼리 (Simple query)

{
  "requests": [
    { "type": "execute", "stmt": { "sql": "CREATE TABLE users (name)" } },
    { "type": "close" }
  ]
}

{
  "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"
      }
    }
  ]
}

참고: 요청에서 명시적으로 닫지 않으면(위 예시처럼) 커넥션은 타임아웃이 될 때까지 열려 있어요. 커넥션에서 보내는 모든 요청은 타임아웃을 연장해요. 더 이상 필요 없는 커넥션은 직접 닫아 주는 게 좋아요.

파라미터 바인딩 (Parameter binding)

파라미터가 바인딩된 쿼리는 두 가지 방식이 있어요.

  1. 위치 기반(positional) 쿼리 파라미터. 파라미터 목록에서의 위치로 바인딩되고 ? 접두사를 써요. 쿼리가 위치 기반 파라미터를 사용한다면 값은 args 필드에 배열로 넣어요.
{
  "requests": [
    {
      "type": "execute",
      "stmt": {
        "sql": "SELECT * FROM users WHERE name = ?",
        "args": [
          {
            "type": "text",
            "value": "Turso"
          }
        ]
      }
    },
    {
      "type": "close"
    }
  ]
}

{
  "baton": null,
  "base_url": null,
  "results": [
    {
      "type": "ok",
      "response": {
        "type": "execute",
        "result": {
          "cols": [
            {
              "name": "name",
              "decltype": "TEXT"
            }
          ],
          "rows": [
            [
              {
                "type": "text",
                "value": "Turso"
              }
            ]
          ],
          "affected_row_count": 0,
          "last_insert_rowid": null
        }
      }
    },
    {
      "type": "ok",
      "response": {
        "type": "close"
      }
    }
  ]
}
  1. 이름 기반(named) 바인드 파라미터. 파라미터를 이름으로 참조하고 :, @, $ 접두사를 써요. 쿼리가 이름 기반 파라미터를 사용한다면 named_args 필드에 파라미터와 값을 매핑한 객체 배열을 넣어요.
{
  "requests": [
    {
      "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": "close"
    }
  ]
}

{
  "baton": null,
  "base_url": null,
  "results": [
    {
      "type": "ok",
      "response": {
        "type": "execute",
        "result": {
          "cols": [
            {
              "name": "name",
              "decltype": "TEXT"
            }
          ],
          "rows": [
            [
              {
                "type": "text",
                "value": "Turso"
              }
            ]
          ],
          "affected_row_count": 0,
          "last_insert_rowid": null
        }
      }
    },
    {
      "type": "ok",
      "response": {
        "type": "close"
      }
    }
  ]
}

참고: 각 named_args의 name 속성은 접두사를 붙여도 되고 생략해도 돼요. 위 예시에서는 생략했지만 두 방식 모두 유효해요.

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

참고: blob 타입을 사용한다면 value 속성을 base64로 바꾸고, 요청을 보내기 전에 인자를 base64로 인코딩해 주세요.

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

인터랙티브 쿼리 (Interactive query)

같은 커넥션에서 여러 작업을 여러 번의 왕복(roundtrip)에 걸쳐 수행하고 싶을 때가 있어요. 이럴 때는 커넥션을 바로 닫지 않으면 돼요.

{
  "requests": [{ "type": "execute", "stmt": { "sql": "BEGIN" } }]
}

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

baton을 돌려받은 걸 볼 수 있어요. 커넥션을 닫지 않았기 때문이에요. 이 baton을 사용하면 같은 커넥션에서 추가 쿼리를 이어서 할 수 있어요.

{
  "baton": "m7lVVgEvknpf1P1irxHsHqrAqH7BLiwO4DQIAwr93PdZWGvdBNugLSokSsCZNkry",
  "requests": [
    { "type": "execute", "stmt": { "sql": "CREATE TABLE users (name)" } },
    {
      "type": "execute",
      "stmt": { "sql": "INSERT INTO users VALUES (\"iku\")" }
    },
    { "type": "execute", "stmt": { "sql": "COMMIT" } },
    { "type": "close" }
  ]
}

참고: 트랜잭션과 커넥션 모두 타임아웃이 있어요. 트랜잭션은 완료까지 5초의 시간이 주어지고, 커넥션은 10초간 유휴 상태면 닫혀요.

응답 타입 (Response types)

응답에는 다음 필드들이 담겨요.

Field Type Description
baton string 커넥션을 서버에서 식별해 재사용할 수 있게 해주는 값이에요.
base_url string 요청을 처리한 서버의 Base URL이에요. 이후 요청에서 이 URL을 재사용하면 해당 서버로 라우팅을 강제할 수 있어요.
results array 파이프라인에서 수행한 각 요청의 결과예요.

results 배열에는 파이프라인의 각 요청 결과가 담겨요. 각 결과는 다음 필드를 가져요.

Field Type Description
cols array 반환된 행들의 컬럼 목록이에요.
rows array 쿼리가 반환한 행들이에요.
affected_row_count integer 쿼리가 영향을 준 행 수예요.
last_insert_rowid integer 마지막으로 삽입된 행의 ID예요.
replication_index string 이 쿼리가 실행된 복제(replication) 시점이에요.
rows_read integer 쿼리가 읽은 행 수예요.
rows_written integer 쿼리가 쓴 행 수예요.
query_duration_ms float 쿼리 소요 시간(밀리초)이에요.

GET /version

데이터베이스를 실행 중인 서버의 현재 버전을 확인하려면 /version 엔드포인트를 사용해요.

curl -L -X GET 'https://[databaseName]-[organizationSlug].turso.io/version' \
  -H 'Authorization: Bearer ***'

sqld 0.21.9 (67f3ea5d 2023-10-26)

GET /health

데이터베이스 상태를 확인하려면 /health 엔드포인트를 사용해요. 본문 없이 HTTP 상태 코드만 돌려줘요.

curl -L -X GET 'https://[databaseName]-[organizationSlug].turso.io/health' \
  -H 'Authorization: Bearer ***'

This response has no body data.

GET /dump

/dump 엔드포인트로 데이터베이스를 덤프할 수 있어요.

curl -L -X GET 'https://[databaseName]-[organizationSlug].turso.io/dump' \
  -H 'Authorization: Bearer ***'

PRAGMA foreign_keys=OFF;
BEGIN TRANSACTION;
CREATE TABLE IF NOT EXISTS mytable (
content TEXT,
embedding FLOAT32(1536)
);
CREATE TABLE IF NOT EXISTS libsql_vector_index (type TEXT, name TEXT, vector_type TEXT, block_size INTEGER, dims INTEGER, distance_ops TEXT);
INSERT INTO libsql_vector_index VALUES('diskann','mytable_idx','float32',128,1536,'cosine');
CREATE INDEX mytable_idx USING diskann_cosine_ops ON mytable (embedding);
COMMIT;

멀티 DB 스키마나 벡터 데이터베이스를 사용 중이라면 내부 관리 테이블을 표현하는 문들도 함께 보여요.

스키마 마이그레이션 상태 (Schema Migration Status)

Turso는 관리형 멀티 테넌트 스키마 시스템인 Multi-DB Schemas를 제공해요. 이 기능을 쓰면 하나의 데이터베이스가 스키마를 관련 자식 데이터베이스들과 자동으로 공유하고, 부모 데이터베이스의 변경 사항이 관련 데이터베이스들에 자동으로 전파돼요.

/v1/jobs 엔드포인트로 스키마 마이그레이션 상태를 모니터링할 수 있어요.

경고: 현재 AWS에서는 Free, Developer, Scaler 플랜에서 사용할 수 없어요.

GET /v1/jobs

스키마의 모든 마이그레이션 작업 요약을 반환해요.

curl -X GET 'https://[databaseName]-[organizationSlug].turso.io/v1/jobs' \
     -H 'Authorization: Bearer ***'

{
  "schema_version": 4,
  "migrations": [
    {
      "job_id": 43,
      "status": "RunSuccess"
    },
    {
      "job_id": 42,
      "status": "RunSuccess"
    },
    {
      "job_id": 39,
      "status": "RunSuccess"
    }
  ]
}

응답 필드 (Response Fields)

  • schema_version (number): 현재 스키마 버전.
  • migrations (array): 마이그레이션 작업 목록
    • Migration Object:
      • job_id (number): 마이그레이션 작업의 고유 ID.
      • status (string): 작업의 현재 상태. 가능한 값: WaitingDryRun, DryRunSuccess, DryRunFailure, WaitingRun, RunSuccess, RunFailure

GET /v1/jobs/:id

특정 마이그레이션 작업의 상세 정보를 반환해요.

curl -X GET 'https://[databaseName]-[organizationSlug].turso.io/v1/jobs/:id' \
     -H 'Authorization: Bearer ***'

{
  "job_id": 1,
  "status": "RunSuccess",
  "error": null,
  "progress": [
    {
      "namespace": "db1",
      "status": "Success",
      "error": null
    },
    {
      "namespace": "db2",
      "status": "Failure",
      "error": "Connection lost"
    }
  ]
}

경로 파라미터 (Path Parameters)

  • id (number, required): 마이그레이션 작업의 ID.

응답 필드 (Response Fields)

  • job_id (number): 마이그레이션 작업의 고유 ID.
  • status (string): 작업의 전체 상태. 가능한 값은 /v1/jobs 엔드포인트와 같아요.
  • error (string): 작업이 실패한 경우 오류 메시지, 아니면 null.
  • progress (array): 개별 데이터베이스의 마이그레이션 상태 목록
    • Progress Object:
      • namespace (string): 데이터베이스 이름.
      • status (string): 이 데이터베이스의 마이그레이션 상태. 가능한 값: Enqueued, DryRunSuccess, DryRunFailure, Run, Success, Failure
      • error (string): 이 데이터베이스의 마이그레이션이 실패한 경우 오류 메시지, 아니면 null.

변경 사항 듣기 (Listen to changes)

/beta/listen 엔드포인트로 데이터베이스에 커밋된 변경 사항을 구독할 수 있어요.

이 기능은 기술 프리뷰(technical preview) 상태예요.

경고: 현재 AWS에서는 Free, Developer, Scaler 플랜에서 사용할 수 없어요.

참고: 데이터베이스 그룹이 v0.24.18 이상 버전을 사용해야 해요 — turso group update <group-name> --version latest

GET /beta/listen

curl -L 'https://[primary-instance-id]-[databaseName]-[organizationSlug].turso.io/beta/listen?table=TABLE_NAME' \
-H 'Authorization: Bearer ***'

쿼리 파라미터 (Query Parameters)

  • table (string, required): 구독할 테이블 이름.
  • action (string, required): 구독할 액션 이름 — insert, update, 또는 delete.

더 알아보기 (Learn more)