Turso

Turso는 플랫폼 API 토큰으로 연결합니다:

1. Turso를 열고 계정 설정의 API Tokens 페이지로 이동하거나, CLI에서 turso auth api-tokens mint polylane을 실행합니다.
2. 플랫폼 API 토큰을 복사합니다.
3. 토큰을 Polylane에 붙여 넣습니다. 토큰이 둘 이상의 조직에 접근할 수 있으면, 요청 시 연결할 조직을 선택하세요.
4. Polylane이 토큰을 검증하고 동기화를 시작합니다.

각 연결은 하나의 Turso 조직을 다룹니다. Polylane은 조직의 데이터베이스 그룹과 데이터베이스를 위치, 배치, 브랜치 상위 관계, 읽기/쓰기 상태를 포함해 발견합니다. 토큰은 저장 전에 암호화되며 에이전트는 이를 절대 보지 못합니다. Polylane은 Platform API만 읽습니다. 데이터베이스에 절대 연결하지 않으며 데이터베이스 자격 증명을 보관하지 않습니다.

Turso의 Platform API는 사용량을 시계열이 아니라 결제 기간 누적 카운터로 보고하므로, 데이터베이스에는 메트릭 차트가 없습니다. 모니터링은 그 카운터를 폴링하고 대신 변화량을 감시합니다: 읽기 및 쓰기 볼륨, 동기화 트래픽, 스토리지 증가, 데이터베이스 수, 플랜 대비 할당량 소진, 데이터베이스별 가장 무거운 질의를 각각 계정 자체의 이력에 대해 검사합니다.

문제 해결

"Invalid Turso API token" 오류

• 플랫폼 API 토큰은 데이터베이스 인증 토큰과 다릅니다. turso auth api-tokens mint로 또는 계정 설정에서 하나를 발급하세요.
• Turso 설정에서 토큰이 취소되지 않았는지 확인하세요.

"Multiple Turso organizations are reachable" 오류

• 토큰이 둘 이상의 조직에 접근할 수 있으므로 연결할 조직을 지정하세요.
• 콘솔에서 연결하는 경우, 검증 후 요청 시 조직을 선택하세요.
• API로 연결하는 경우, organization 필드를 조직 슬러그로 설정하세요.

리소스 누락

• Turso가 모든 것을 동기화하는 데 몇 분이 걸릴 수 있습니다.
• 계정 헤더에서 수동 Sync를 실행해 새로 고치세요.

연결 해제

Polylane에서 계정의 연결을 해제한 뒤, Turso 계정 설정에서 또는 turso auth api-tokens revoke로 API 토큰을 취소하세요.

Turso 연결에는 브라우저가 필요하지 않습니다: 콘솔이 호출하는 것과 같은 엔드포인트를 CI 작업에 담을 수 있습니다. 인증된 POST 하나가 연결을 만들고 첫 동기화를 시작합니다.

사전 요구 사항

• cloud_accounts:write와 cloud_accounts:read 스코프를 가진 Polylane API 키. API 키와 OAuth를 참고하세요.
• ws_로 시작하는 워크스페이스 ID. 같은 키로 GET /v1/workspaces에서 읽을 수 있습니다.
• 계정 설정에서 또는 turso auth api-tokens mint polylane으로 발급한 Turso 플랫폼 API 토큰.

연결 만들기

curl -X POST https://api.polylane.com/v1/cloud_accounts \
  -H "x-api-key: $POLYLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "turso",
    "workspaceId": "ws_0abc123",
    "token": "<platform-api-token>",
    "organization": "my-org-slug"
  }'

한 번의 호출로 Turso 조직 하나가 연결됩니다.

• organization은 토큰이 정확히 하나의 조직에만 접근할 수 있을 때만 생략할 수 있습니다. 그렇지 않으면 접근 가능한 조직 슬러그를 나열하는 400으로 호출이 실패합니다.

응답은 연결된 것을 나열하며, 첫 동기화는 이미 실행 중입니다. 나머지 흐름이 읽는 두 필드만 남기면:

{
  "success": true,
  "result": {
    "provider": "turso",
    "accounts": [{ "id": "acc_34gky74ibc92h8t2efn8csrh", "status": "syncing" }],
    "failures": []
  }
}

이미 연결된 계정은 accounts 대신 failures에 들어가므로, 호출을 반복해도 연결이 중복되지 않습니다.

첫 동기화 기다리기

반환된 각 계정을 id로 status가 ready에 도달할 때까지 폴링하세요(등록 시 new, 리소스가 들어오는 동안 syncing):

until [ "$(curl -s "https://api.polylane.com/v1/cloud_accounts/$WORKSPACE_ID/$ACCOUNT_ID" \
  -H "x-api-key: $POLYLANE_API_KEY" | jq -r '.result.status')" = "ready" ]; do
  sleep 15
done

실패한 연결이 작업을 멈추게 하는 대신 실패시키도록 루프에 기한을 두세요. 계정이 ready가 되면 리소스는 토폴로지에 있고 Polylane은 첫 검사를 시작한 상태입니다.

API에서 연결 해제

연결을 삭제하면 모든 동기화와 검사가 중단되고 Polylane이 보관하던 자격 증명이 삭제됩니다. 호출에는 cloud_accounts:delete 스코프가 필요합니다:

curl -X DELETE "https://api.polylane.com/v1/cloud_accounts/$WORKSPACE_ID/$ACCOUNT_ID" \
  -H "x-api-key: $POLYLANE_API_KEY"

그 다음 아래 연결 해제에 설명된 대로 제공자 쪽에서 Turso 자격 증명을 취소하세요.