Tu primera base en Turso en 5 minutos: guía de la CLI paso a paso

Para crear tu primera base en Turso Cloud alcanza con cinco comandos: instalar la CLI, iniciar sesión, crear la base, abrir la consola SQL y generar un token para tu aplicación. En esta guía los repasamos uno por uno, con los comandos tal como figuran en la documentación oficial, y te contamos qué opciones conviene conocer desde el primer día.

Es el quinto post de "Turso en español", la serie de Mark-Co Digital. Si todavía no sabés qué es Turso ni en qué se diferencia de SQLite, empezá por qué es Turso y por qué Supabase anunció su compra.

Antes de empezar: hay dos CLIs con nombres parecidos#

Turso tiene dos herramientas de línea de comandos y conviene no confundirlas:

Esta guía es sobre la primera, turso, la que usás para trabajar con Turso Cloud.

Paso 1: instalar la CLI#

En macOS podés usar Homebrew:

brew install tursodatabase/tap/turso

En macOS (como alternativa) y en Linux, el script oficial:

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

En Windows la CLI necesita WSL (Windows Subsystem for Linux, el entorno Linux integrado en Windows). Primero abrís PowerShell y ejecutás wsl; después, ya dentro de WSL, corrés el mismo script:

wsl

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

La documentación aclara un detalle que suele hacer perder tiempo: para verificar la instalación tenés que abrir una terminal nueva y escribir turso.

Para actualizarla más adelante, en macOS usás brew update y brew upgrade; en Linux y Windows, turso update.

Paso 2: crear la cuenta o iniciar sesión#

turso auth signup

Si ya tenés cuenta:

turso auth login

Estos comandos abren el navegador para autenticarte. Si estás en un entorno donde eso no es posible, como WSL o un servidor de integración continua, la documentación recomienda el modo sin navegador:

turso auth login --headless

Para automatizaciones, la página del modo headless menciona la variable de entorno TURSO_API_TOKEN, y turso auth token muestra el token que usa la CLI para hablar con la Platform API (la API para administrar Turso Cloud por código). Tratalo como una contraseña.

Paso 3: crear tu primera base#

La guía rápida oficial muestra dos variantes. Con el motor nuevo, Turso Database:

turso db create my-db --tursodb

O sin la opción, que crea una base sobre libSQL, el fork de SQLite que Turso mantiene desde antes:

turso db create my-db

Para una base nueva, la documentación de Turso recomienda el motor Turso Database; libSQL queda como opción probada para cargas críticas.

turso db create tiene opciones útiles que vamos a usar en otros posts de la serie:

• --from-file, --from-dump y --from-csv para crear la base a partir de datos existentes (con --from-file el límite es de 2 GB).
• --from-db para copiar otra base, y --timestamp junto con --from-db para restaurar un momento del pasado.
• --group para elegir el grupo y --size-limit para ponerle un tope de tamaño (por ejemplo 256mb).

Paso 4: mirar la base y conectarte con la consola SQL#

Para ver el nombre, el ID, el grupo, el tamaño y la ubicación:

turso db show my-db

Con --url obtenés la URL de conexión que va a usar tu aplicación, y con --http-url la URL HTTP. Para listar todas tus bases, turso db list (opcionalmente filtrando con --group).

Ahora, la consola SQL interactiva:

turso db shell my-db

Adentro, el ejemplo de la guía rápida crea una tabla, inserta un registro y lo consulta:

CREATE TABLE users (
  ID INTEGER PRIMARY KEY AUTOINCREMENT,
  name TEXT
);

INSERT INTO users (name) VALUES ('Iku');

SELECT * FROM users;

Para salir, .quit. Iku, por cierto, es la mascota de Turso: su nombre viene de Iku-Turso, una criatura marina de la mitología finlandesa, según la página institucional de la empresa.

También podés ejecutar una consulta suelta sin entrar a la consola, algo práctico para scripts:

turso db shell <database-name> "SELECT * FROM users"

Paso 5: generar un token para tu aplicación#

Tu aplicación se conecta con la URL de la base y un token. Se crea así:

turso db tokens create <database-name> [flags]

Dos opciones que recomendamos usar desde el principio:

• --read-only: el token solo puede leer. Ideal para un panel de reportes o un sitio que solo muestra datos.
• --expiration: el token vence. Acepta never o una duración como 7d.

turso db tokens create <database-name> --read-only

Si necesitás un token para todas las bases de un grupo, existe turso group tokens create <group-name>, con las mismas opciones. Es cómodo, pero da acceso a más cosas: usalo solo si hace falta. Y no subas tokens al repositorio; en nuestra nota sobre claves de API expuestas en GitHub explicamos por qué.

Extras: regiones, grupos y limpieza#

Para ver en qué regiones podés crear bases, y la latencia desde tu máquina a cada una:

turso db locations --show-latencies

Esto es especialmente interesante desde Latinoamérica, porque Turso Cloud sumó una región en San Pablo: lo contamos en Turso llegó a San Pablo.

Los grupos agrupan bases en una ubicación. Se crean con turso group create <group-name>, y si no indicás --location, la ubicación primaria es la región más cercana. Tener varios grupos requiere los planes Scaler, Pro o Enterprise.

Para borrar una base de prueba:

turso db destroy <database-name>

La opción -y evita la confirmación; usala con cuidado en scripts.

Qué significa para tu proyecto#

• Para un equipo de desarrollo, la CLI permite probar Turso en minutos y con el plan gratuito, que según la página de precios incluye 100 bases y 5 GB de almacenamiento. Alcanza para un piloto.
• Para una pyme con un desarrollador o una agencia, conviene que los tokens de producción tengan permisos mínimos y vencimiento, y que la cuenta de Turso esté a nombre de la empresa, no de una persona.
• Para automatizar, el modo headless y los comandos con SQL en línea permiten integrar Turso en pipelines de despliegue. Más adelante en la serie vemos la Platform API, que lleva esto un paso más allá.

Preguntas frecuentes#

¿Necesito tarjeta de crédito para probar Turso?#

La página de precios muestra un plan Free de USD 0 con 100 bases. Las condiciones de alta pueden cambiar, así que revisalas al crear la cuenta.

¿Puedo usar la CLI de Turso en Windows sin WSL?#

La documentación de instalación de la CLI turso indica WSL para Windows. El motor local tursodb tiene su propio instalador para PowerShell, pero es otra herramienta.

¿Cuál es la diferencia entre un token de base y uno de grupo?#

El de base da acceso a una sola base; el de grupo, a todas las del grupo. Ambos se pueden limitar a lectura y ponerles vencimiento.

¿Qué pasa si borro una base por error?#

Con turso db destroy la base se elimina. En los planes pagos, Turso permite recuperar bases borradas durante 5 días; lo vemos en detalle en un post posterior de la serie.

Si querés sumar Turso o Supabase a un proyecto y necesitás ayuda para diseñar el backend, configurar accesos seguros o automatizar el despliegue, en Mark-Co Digital trabajamos en desarrollo backend y en cloud e infraestructura. Mañana: los precios de Turso explicados plan por plan.

Fuentes#

• Instalación de la CLI de Turso
• Actualizar la CLI de Turso
• Guía rápida de Turso
• Modo headless de la CLI
• turso auth token
• turso db create
• turso db show
• turso db list
• turso db shell
• turso db tokens create
• turso group tokens create
• turso db locations
• turso db destroy
• turso group create
• Repositorio de Turso Database en GitHub
• Precios de Turso
• Sobre Turso (About us)
• Claves de API expuestas en GitHub (Mark-Co Digital)