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

Turso 퀵스타트

원문 보기 위키 갱신

Turso 퀵스타트 (Go)

Go에서 Turso를 시작하는 일은 생각보다 간단해요. 이 퀵스타트에서는 패키지 설치부터 로컬·원격 데이터베이스 연결, SQL 쿼리 실행, 클라우드 동기화까지 차근차근 배워요.

출처: 문서

본문

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

  • Turso 패키지 설치하기
  • 로컬 또는 원격 데이터베이스에 연결하기
  • SQL로 쿼리 실행하기
  • 클라우드로 변경 사항 동기화하기

추천: tursogo (로컬 + 클라우드 동기화)

tursogo는 로컬 데이터베이스를 실행하고 Turso Cloud와 양방향으로 동기화하는 데 추천되는 패키지예요. SQLite를 완전히 새로 작성한 Turso Database 엔진을 기반으로 하며, 동시 쓰기(MVCC)와 비동기 I/O를 지원해요. 표준 database/sql 드라이버 인터페이스를 구현하기 때문에 어떤 Go SQLite 드라이버든 드롭인 대체재로 동작해요. 사전 빌드된 네이티브 라이브러리를 함께 제공하고 purego로 FFI를 처리해서 CGO가 필요 없어요.

1. 설치

go get turso.tech/database/tursogo

2. 연결

package main

import (
	"database/sql"
	"fmt"

	_ "turso.tech/database/tursogo"
)

func main() {
	db, _ := sql.Open("turso", "app.db")
	defer db.Close()

	db.Exec(`CREATE TABLE IF NOT EXISTS users (
		id INTEGER PRIMARY KEY AUTOINCREMENT,
		name TEXT NOT NULL
	)`)

	db.Exec("INSERT INTO users (name) VALUES (?)", "Alice")

	rows, _ := db.Query("SELECT * FROM users")
	defer rows.Close()
	for rows.Next() {
		var id int
		var name string
		rows.Scan(&id, &name)
		fmt.Printf("User: %d %s\n", id, name)
	}
}

3. 동기화 (Push와 Pull)

로컬 데이터베이스를 Turso Cloud와 동기화해야 한다면 sync 드라이버를 사용해요.

package main

import (
	"context"
	"os"

	turso "turso.tech/database/tursogo"
)

func main() {
	ctx := context.Background()

	syncDb, _ := turso.NewTursoSyncDb(ctx, turso.TursoSyncDbConfig{
		Path:      "app.db",
		RemoteUrl: os.Getenv("TURSO_DATABASE_URL"),
		AuthToken: os.Getenv("TURSO_AUTH_TOKEN"),
	})

	db, _ := syncDb.Connect(ctx)
	defer db.Close()

	db.ExecContext(ctx, "INSERT INTO users (name) VALUES (?)", "Bob")

	// Push local writes to Turso Cloud
	syncDb.Push(ctx)

	// Pull remote changes to local database
	syncDb.Pull(ctx)
}

모든 읽기와 쓰기는 로컬 데이터베이스 파일을 대상으로 이뤄져서 빠르고 오프라인에서도 동작해요. Push()는 변경 사항을 클라우드로 보내고, Pull()은 원격 변경 사항을 내려받아요. 체크포인트, 통계, 암호화에 대해서는 레퍼런스를 참고하고, 충돌 해결 등 세부 내용은 Turso Sync를 확인해 주세요.

참고: Turso Cloud 계정 없이도 로컬 sync 서버를 띄워 동기화를 테스트할 수 있어요.

tursodb :memory: --sync-server 127.0.0.1:8080

그다음 RemoteUrl을 http://127.0.0.1:8080으로 설정하면 돼요(AuthToken은 필요 없어요). tursodb 설치 방법은 Turso Database 퀵스타트를 확인해 주세요.

원격 접근 (Over-the-Wire)

애플리케이션이 네트워크를 통해 Turso Cloud 데이터베이스를 직접 조회해야 한다면(웹 서버나 서버리스 함수 등), 사용하는 데이터베이스 엔진에 맞는 드라이버를 선택해요. Turso 데이터베이스라면 tursogo-serverless, libSQL 데이터베이스라면 libsql-client-go를 쓰면 돼요.

참고: 대부분의 애플리케이션에서는 원격 접근보다 동기화 기능이 있는 로컬 데이터베이스(NewTursoSyncDb)를 추천해요. 더 빠른 읽기, 오프라인 지원, 낮은 지연 시간을 얻을 수 있거든요. 원격 접근은 로컬 데이터베이스 파일을 둘 수 없을 때(스테이트리스 서버리스 환경 등) 유용해요.

원격 Turso 데이터베이스: tursogo-serverless

tursogo-serverless는 HTTP를 통해 원격 Turso 데이터베이스에 연결해요. 순수 Go라서 CGO도 네이티브 라이브러리도 필요 없어요. 표준 database/sql 인터페이스를 구현해서 임베디드 tursogo 드라이버와 호환돼요.

1. 데이터베이스 자격 증명 가져오기

계속하려면 기존 Turso 데이터베이스가 필요해요. 없다면 turso db create --tursodb로 만들면 돼요(퀵스타트 참고). 데이터베이스 URL과 인증 토큰은 환경 변수로 저장해 두는 편이 좋아요.

2. 설치
go get turso.tech/database/tursogo-serverless
3. 연결과 쿼리
package main

import (
	"database/sql"
	"fmt"
	"os"

	turso "turso.tech/database/tursogo-serverless"
)

func main() {
	db := sql.OpenDB(turso.NewConnector(
		os.Getenv("TURSO_DATABASE_URL"),
		os.Getenv("TURSO_AUTH_TOKEN"),
	))
	defer db.Close()

	rows, _ := db.Query("SELECT * FROM users")
	defer rows.Close()
	for rows.Next() {
		var id int
		var name string
		rows.Scan(&id, &name)
		fmt.Printf("User: %d %s\n", id, name)
	}
}

원격 libSQL 데이터베이스: libsql-client-go

libsql-client-go는 libSQL 와이어 프로토콜을 통해 원격 libSQL 데이터베이스에 연결해요. 로컬 파일도 필요 없고 순수 Go로 동작해요.

1. 데이터베이스 자격 증명 가져오기

계속하려면 기존 libSQL 데이터베이스가 필요해요. 없다면 만들어 주세요. 자격 증명은 환경 변수로 저장해 두면 편해요.

2. 설치
go get github.com/tursodatabase/libsql-client-go/libsql
3. 연결과 쿼리
package main

import (
	"database/sql"
	"fmt"
	"os"

	_ "github.com/tursodatabase/libsql-client-go/libsql"
)

func main() {
	url := os.Getenv("TURSO_DATABASE_URL") + "?authToken=" + os.Getenv("TURSO_AUTH_TOKEN")

	db, _ := sql.Open("libsql", url)
	defer db.Close()

	rows, _ := db.Query("SELECT * FROM users")
	defer rows.Close()
	for rows.Next() {
		var id int
		var name string
		rows.Scan(&id, &name)
		fmt.Printf("User: %d %s\n", id, name)
	}
}

임베디드 레플리카 (go-libsql)

참고: 임베디드 레플리카는 Turso Cloud 데이터베이스의 로컬 읽기 복사본을 Go 앱에 제공해요. 읽기는 로컬에서 처리되고, 쓰기는 클라우드 기본(primary) 인스턴스로 전달된 뒤 레플리카에 반영돼요. 프로덕션에서도 완전히 지원돼요.

동기화가 필요한 새 프로젝트라면 NewTursoSyncDb를 갖춘 tursogo를 추천해요. 읽기와 쓰기가 모두 로컬에서 일어나고, Push() / Pull()로 명시적으로 동기화하며, 와이어 포맷도 페이지 프레임이 아니라 논리적 변경 데이터 캡처 방식이에요(벤치마크).

go-libsql을 사용한 임베디드 레플리카의 전체 문서는 레퍼런스에서 확인할 수 있어요.

더 알아보기 (Learn more)