Memasang dan Menggunakan Database Turso di Debian 13

Pengertian

Turso adalah layanan database terdistribusi yang dibangun di atas libSQL — sebuah fork open source dari SQLite yang menambahkan replikasi, akses jaringan, dan fitur modern lainnya. Jika SQLite adalah satu file lokal, Turso adalah "SQLite di cloud" yang bisa diakses dari mana saja lewat HTTP/WebSocket, dengan replika yang ditempatkan dekat pengguna.

Turso tetap memakai dialek dan semantik SQLite: tabel, index, view, trigger, transaksi, dan tipe data dinamis. Aplikasi yang sudah memakai SQLite biasanya cukup mengganti driver-nya (bukan menulis ulang query) untuk mulai memakai Turso.

Perbedaan mendasar:

• SQLite lokal: file .db, dibaca langsung oleh proses aplikasi, tanpa jaringan.
• Turso: database dikelola layanan, diakses lewat URL libsql://, dapat direplikasi ke beberapa region, dan dilindungi token akses.

Kelebihan

• Kompatibel SQLite: query, skema, dan sintaks hampir sama — migrasi relatif mudah.
• Terdistribusi di edge: replika bisa diletakkan dekat pengguna sehingga latensi baca rendah.
• Tanpa kelola server: tidak ada VPS, daemon, patching, atau backup manual yang harus dijaga.
• Akses jaringan aman: koneksi memakai URL libsql:// dan token per database.
• Embedded replica: aplikasi bisa memakai salinan lokal yang disinkronkan ke cloud — baca cepat, tulis ke pusat.
• Gratis untuk skala kecil: tersedia free tier yang cukup untuk bot dan proyek pribadi.
• Dukungan driver modern: SDK resmi untuk JavaScript/TypeScript, Python, Go, Rust, dan lainnya.
• Fork dan branching: database bisa diduplikasi untuk pengujian tanpa mengganggu data produksi.

Kekurangan

• Bergantung pada layanan pihak ketiga: butuh akun dan koneksi internet untuk operasi ke cloud.
• Bukan SQLite murni: sebagian ekstensi SQLite dan perilaku file langsung tidak tersedia.
• Write tetap tersentralisasi: Turso mengandalkan satu primary writer; beban tulis tinggi tetap terbatas seperti SQLite.
• Latensi tulis: setiap write menempuh jaringan menuju primary — tidak secepat SQLite lokal.
• Kuota free tier: jumlah database, storage, dan reads/writes dibatasi; melewati kuota berarti upgrade.
• Kebijakan data: data berada di infrastruktur penyedia, sehingga perlu pertimbangan kepatuhan dan privasi.
• Ketergantungan tooling: CLI dan SDK harus diperbarui mengikuti perkembangan libSQL.

Catatan penting: Turso cocok untuk aplikasi read-heavy, bot Telegram, dan layanan edge yang butuh replika dekat pengguna. Untuk beban tulis sangat tinggi atau syarat data harus berada di server sendiri, pertimbangkan self-hosted libSQL (sqld) atau database server seperti PostgreSQL.

Persiapan

Pastikan Anda memiliki:

• Debian 13 dengan akses sudo.
• Akun Turso (bisa dibuat langsung dari CLI).
• curl dan nodejs untuk instalasi CLI serta pengujian SDK.

Perbarui sistem terlebih dahulu:

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl ca-certificates

Langkah 1: Instalasi Turso CLI

Pasang CLI resmi Turso:

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

Skrip akan menempatkan binary di ~/.turso. Tambahkan ke PATH agar bisa dipanggil dari mana saja:

echo 'export PATH="$HOME/.turso:$PATH"' >> ~/.bashrc
source ~/.bashrc

Verifikasi:

turso --version

Turso CLI resmi tersedia untuk Linux dan macOS. Jika memakai Windows, jalankan melalui WSL — artikel ini fokus pada Debian 13.

Langkah 2: Login ke Turso

Buat akun baru atau login:

turso auth signup

Atau jika sudah punya akun:

turso auth login

Perintah akan membuka alur autentikasi di browser dan menampilkan kode verifikasi. Selesaikan prosesnya, lalu cek akun aktif:

turso auth whoami

Langkah 3: Membuat Database

Buat database baru:

turso db create aplikasi

Pilih region terdekat agar latensi rendah:

turso db create aplikasi --location fra

Daftar region yang tersedia:

turso db locations

Lihat daftar database dan detailnya:

turso db list
turso db show aplikasi

Ambil URL koneksi database:

turso db show aplikasi --url

Hasilnya berupa URL dengan format libsql://aplikasi-<username>.turso.io.

Langkah 4: Membuat Token Akses

Setiap koneksi aplikasi membutuhkan token. Buat token untuk database:

turso db tokens create aplikasi

Simpan token di tempat aman — jangan di-commit ke Git. Contoh .env:

TURSO_DATABASE_URL=libsql://aplikasi-username.turso.io
TURSO_AUTH_TOKEN=eyJhbGciOi...

Melihat dan mencabut token bila bocor:

turso db tokens list aplikasi
turso db tokens invalidate aplikasi

Langkah 5: Menggunakan Shell Turso

Masuk ke shell interaktif:

turso db shell aplikasi

Buat tabel dan isi data:

CREATE TABLE users (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  nama TEXT NOT NULL,
  email TEXT UNIQUE,
  dibuat_pada DATETIME DEFAULT CURRENT_TIMESTAMP
);

INSERT INTO users (nama, email) VALUES ('Sugeng', '[email protected]');

SELECT * FROM users;

Jalankan query langsung dari terminal tanpa masuk shell:

turso db shell aplikasi "SELECT COUNT(*) FROM users;"

Langkah 6: Menggunakan Turso dari Node.js

1. Siapkan proyek dan pasang SDK resmi:
   bash

   mkdir -p ~/turso-node && cd ~/turso-node
   npm init -y
   npm install @libsql/client dotenv

2. Buat file .env seperti pada Langkah 4.
3. Buat file db.js:
   javascript

   require('dotenv').config();
   const { createClient } = require('@libsql/client');
   
   const db = createClient({
     url: process.env.TURSO_DATABASE_URL,
     authToken: process.env.TURSO_AUTH_TOKEN,
   });
   
   async function main() {
     await db.execute(`
       CREATE TABLE IF NOT EXISTS users (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
         nama TEXT NOT NULL,
         email TEXT UNIQUE
       )
     `);
   
     await db.execute({
       sql: 'INSERT INTO users (nama, email) VALUES (?, ?)',
       args: ['Sugeng', '[email protected]'],
     });
   
     const hasil = await db.execute('SELECT * FROM users');
     console.log(hasil.rows);
   }
   
   main().catch((err) => {
     console.error(err);
     process.exit(1);
   });

4. Jalankan:
   bash

   node db.js

Selalu gunakan parameter ? dengan args agar terhindar dari SQL injection.

Langkah 7: Menggunakan Turso dari Python

Pasang SDK Python, sebaiknya di virtual environment:

sudo apt install -y python3 python3-venv
python3 -m venv venv
source venv/bin/activate
pip install libsql-client python-dotenv

Buat file db.py:

import os
from dotenv import load_dotenv
from libsql_client import create_client_sync

load_dotenv()

client = create_client_sync(
    url=os.environ["TURSO_DATABASE_URL"],
    auth_token=os.environ["TURSO_AUTH_TOKEN"],
)

client.execute("""
  CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    nama TEXT NOT NULL,
    email TEXT UNIQUE
  )
""")

client.execute(
    "INSERT INTO users (nama, email) VALUES (?, ?)",
    ["Sugeng", "[email protected]"],
)

result = client.execute("SELECT * FROM users")
for row in result.rows:
    print(row)

client.close()

Jalankan:

python db.py

Langkah 8: Embedded Replica

Embedded replica membuat salinan database di server aplikasi. Baca dilakukan dari file lokal (cepat), lalu disinkronkan ke Turso:

const { createClient } = require('@libsql/client');

const db = createClient({
  url: 'file:replica.db',
  syncUrl: process.env.TURSO_DATABASE_URL,
  authToken: process.env.TURSO_AUTH_TOKEN,
  syncInterval: 60,
});

await db.sync();
const hasil = await db.execute('SELECT * FROM users');

Pola ini cocok untuk bot atau API yang banyak membaca namun jarang menulis, sekaligus tetap aman bila server utama bermasalah.

Langkah 9: Backup, Export, dan Migrasi

Ekspor seluruh database ke dump SQL:

turso db shell aplikasi .dump > dump-aplikasi.sql

Impor dump SQLite lokal ke Turso:

turso db shell aplikasi < dump-aplikasi.sql

Membuat database baru dari database yang sudah ada (untuk pengujian):

turso db create aplikasi-test --from-db aplikasi

Menghapus database:

turso db destroy aplikasi

Tabel Perintah Penting

Troubleshooting

• 401 Unauthorized: token salah, kedaluwarsa, atau milik database lain. Buat ulang token dengan turso db tokens create nama dan perbarui .env.
• database not found: URL tidak lengkap. Ambil URL terbaru dengan turso db show nama --url.
• turso: command not found: PATH belum dimuat. Jalankan source ~/.bashrc atau buka sesi shell baru.
• Login gagal di VPS tanpa browser: gunakan perangkat lain untuk membuka URL autentikasi yang ditampilkan CLI, lalu selesaikan verifikasi kode.
• Query lambat: pilih region primary terdekat (--location) dan gunakan embedded replica untuk beban baca tinggi.
• SQLITE_BUSY saat banyak write: Turso menyerialkan write di primary. Tambahkan retry dengan backoff eksponensial di aplikasi.
• Data lokal tidak muncul: pastikan sudah memanggil db.sync() pada embedded replica dan cek syncInterval.
• Kuota free tier habis: lihat pemakaian di dashboard Turso, atau upgrade paket sebelum produksi.

Kelebihan dan Kekurangan untuk Dipilih

Kesimpulan

Turso membawa SQLite ke era terdistribusi: sintaks SQLite yang familiar, akses jaringan yang aman, replika dekat pengguna, dan tanpa perlu mengelola server database. Instalasinya cukup lewat CLI, lalu aplikasi terhubung memakai URL libsql:// dan token. Untuk bot Telegram dan layanan read-heavy, Turso adalah pilihan ringkas dan hemat. Untuk beban tulis ekstrem atau kebutuhan data on-premise, gunakan database server atau sqld self-hosted.