Turso 무료로 시작하기 — Free 플랜 발급부터 .env 연동까지

Turso 무료 플랜으로 SQLite/libSQL 데이터베이스를 발급받아, .env 의 TURSO_DATABASE_URL · TURSO_AUTH_TOKEN 두 값을 채우는 과정을 처음부터 끝까지 정리했습니다. 앱 개발은 이미 끝났고, 이제 "무료 DB 연결"만 하면 되는 상황을 전제로 합니다.

들어가며

Next.js 앱을 배포할 때 가장 먼저 마주치는 벽이 데이터베이스입니다. 로컬에서는 file:./local.db 같은 SQLite 파일로도 잘 돌아가지만, 실제 서비스에서는 여러 서버 인스턴스가 같은 데이터를 공유해야 하죠.

이때 부담 없이 시작할 수 있는 선택지가 Turso 입니다. SQLite 를 그대로 쓰던 프로젝트라면 코드를 거의 바꾸지 않고 클라우드 DB 로 넘어갈 수 있고, 무료 플랜이 꽤 넉넉합니다.

이 글에서는 Turso 사이트에서 계정을 만들고, 데이터베이스를 생성해, 앱이 필요로 하는 딱 두 개의 값을 얻어 .env 에 넣는 것까지만 다룹니다. (스키마·쿼리 코드는 이미 있다는 전제)

Turso 가 뭔가요?

Turso 는 libSQL — SQLite 를 포크해서 서버/복제 기능을 붙인 데이터베이스 — 를 클라우드로 제공하는 서비스입니다.

• SQLite 문법·드라이버를 거의 그대로 사용 (@libsql/client)
• 전 세계 엣지 지역에 읽기 복제본(replica) 배치 가능 → 낮은 지연
• 앱에 파일로 복제본을 두는 embedded replica 지원 (읽기는 로컬 파일, 쓰기는 원격 동기화)

우리 앱도 TURSO_DATABASE_URL 이 있으면 Turso, 없으면 로컬 file:./local.db 로 폴백하도록 되어 있어서 — 환경변수만 넣으면 그대로 클라우드 DB 로 전환됩니다.

1단계 — 계정 만들기

1. turso.tech 접속 → 우측 상단 Sign up.
2. GitHub 계정으로 가입하는 게 가장 빠릅니다 (이메일도 가능).
3. 가입하면 대시보드 app.turso.tech 로 이동합니다.

💡 이후 작업은 ① 웹 대시보드 또는 ② Turso CLI 둘 중 하나로 할 수 있습니다. CLI 가 값 복사가 편해서 추천하지만, 터미널이 부담되면 웹으로만 해도 됩니다.

2단계 (방법 A) — Turso CLI 로 발급 ⭐ 추천

CLI 설치

# macOS / Linux
curl -sSfL https://get.tur.so/install.sh | bash

# 또는 Homebrew (macOS)
brew install tursodatabase/tap/turso

설치 후 새 터미널을 열고 로그인합니다.

turso auth login    # 브라우저가 열리며 GitHub 인증

데이터베이스 생성

turso db create codium-lab

codium-lab 자리에 원하는 이름을 넣으세요. 생성되면 지역(region)과 함께 완료 메시지가 뜹니다.

값 두 개 얻기

# ① TURSO_DATABASE_URL  (libsql:// 로 시작)
turso db show codium-lab --url

# ② TURSO_AUTH_TOKEN  (긴 JWT 문자열)
turso db tokens create codium-lab

• 첫 번째 명령의 출력 → TURSO_DATABASE_URL (예: libsql://codium-lab-yourname.turso.io)
• 두 번째 명령의 출력 → TURSO_AUTH_TOKEN (아주 긴 토큰 문자열)

⚠️ 토큰은 이때만 전체가 보입니다. 창을 닫으면 다시 볼 수 없으니 바로 복사해 두세요. 잃어버리면 새로 발급(turso db tokens create)하면 됩니다.

2단계 (방법 B) — 웹 대시보드로 발급

CLI 없이 브라우저만으로도 가능합니다.

1. app.turso.tech → Create Database (또는 + New).
2. New Database 탭에서 Name(예: codium-lab) 입력.
3. Location(지역) 을 반드시 선택 ⭐ — Primary location 이 비어 있으면(선택 안 하면) Create Database 클릭 시 에러가 납니다. 드롭다운을 열어 지역을 골라 주세요. 한국 서비스라면 가까운 Tokyo (nrt) 를 추천합니다.
4. Create Database 클릭 → 생성 완료.
5. 생성된 DB 를 클릭 → Connect (또는 상세 화면).
6. Database URL 항목의 libsql://... 를 복사 → TURSO_DATABASE_URL.
7. 같은 화면 또는 Tokens 탭에서 Create Token → 나온 문자열 복사 → TURSO_AUTH_TOKEN.

⚠️ Location(지역)은 필수입니다. Primary location 을 고르지 않고 바로 생성하면 에러가 나니, 드롭다운에서 지역을 먼저 선택하세요. (CLI 로 만들 때는 계정 기본 지역이 자동 적용됩니다.)

3단계 — .env 에 넣기 ⭐

프로젝트 루트의 .env 파일에 아래 두 줄을 추가(또는 수정)합니다.

TURSO_DATABASE_URL=libsql://codium-lab-yourname.turso.io
TURSO_AUTH_TOKEN=eyJhbGciOi...(복사한 긴 토큰)...

• 값에 따옴표는 필요 없습니다 (그대로 붙여넣기).
• .env 는 절대 git 에 커밋하지 마세요 (.gitignore 확인). 커밋용은 .env.example 만.

이제 앱을 재시작하면 로컬 파일이 아니라 Turso 클라우드 DB 에 연결됩니다.

npm run dev

💡 값이 잘 들어갔는지 확인하려면: URL 은 libsql:// 로 시작해야 하고, 토큰은 보통 eyJ 로 시작하는 아주 긴 문자열입니다.

무료 플랜, 뭐가 되고 안 되나

Turso 무료(Free) 플랜은 개인 프로젝트·소규모 서비스에는 충분합니다.

장점

• 넉넉한 무료 한도 — 개인/사이드 프로젝트 수준에서는 요금 걱정 없이 운영 가능.
• SQLite 그대로 — 기존 SQLite 코드·드라이버를 거의 수정 없이 사용.
• 비활성화되어도 안 멈춤 — 트래픽이 없다고 프로젝트가 일시정지(pause)되지 않음.
• 엣지 복제·embedded replica — 읽기 지연을 크게 낮출 수 있음.
• 연결이 가벼움 — HTTP 기반이라 서버리스/엣지 환경과 궁합이 좋음(커넥션 풀 이슈 적음).

단점

• SQLite 의 한계 — 복잡한 동시 쓰기, 일부 고급 SQL 기능은 PostgreSQL 만 못함.
• 부가 기능이 없음 — 인증·스토리지·실시간·Edge Function 같은 BaaS 기능은 제공하지 않음(순수 DB).
• 한도 초과 시 — 무료 한도(저장 용량·월간 읽기/쓰기 행 수 등)를 넘기면 유료 전환 필요.
• 상대적으로 신생 — 생태계·자료가 PostgreSQL 계열보다 적고, 요금/한도 정책이 종종 바뀜.

⚠️ 무료 한도의 구체적 수치(저장 용량, 월 읽기/쓰기 행 수, DB 개수 등)는 시기에 따라 자주 바뀝니다. 정확한 최신 값은 반드시 Turso 요금 페이지에서 확인하세요.

Supabase 와 비교하면?

가장 자주 비교되는 무료 DB 가 Supabase 입니다. 성격이 꽤 다릅니다.

정리하면:

• 이미 SQLite 로 개발했고 "DB 한 개만 클라우드로 붙이면 되는" 상황 → Turso 가 간단하고 잘 맞습니다. (지금 우리 케이스)
• 인증·파일 저장·실시간 구독까지 백엔드를 통째로 위임하고 싶다 → Supabase 가 유리합니다.
• 다만 Supabase 무료 프로젝트는 오래 안 쓰면 잠들었다가 다시 깨우는 특성이 있어, 저트래픽 상시 운영에는 Turso 가 마음 편할 수 있습니다.

마치며

정리하면 Turso 무료 연결은 결국 세 동작입니다.

• Turso 가입 (GitHub 로그인)
• turso db create 로 DB 생성
• URL·토큰을 뽑아 .env 의 TURSO_DATABASE_URL · TURSO_AUTH_TOKEN 에 붙여넣기

개발이 이미 되어 있는 상태라면, 이 두 줄만 채우고 앱을 재시작하는 순간 로컬 파일 DB 가 클라우드 DB 로 조용히 바뀝니다. SQLite 로 시작한 프로젝트를 가장 적은 변경으로 실제 서비스에 올리는 방법으로 Turso 는 꽤 매력적인 선택지입니다.