Astro DB con Bunny Database: Desarrollo Local-First, libSQL en Producción

Astro DB es una de esas funciones que te hace preguntarte por qué no todos los frameworks incluyen algo así. Defines tablas en TypeScript, obtienes un archivo SQLite local para desarrollo sin configuración alguna, y consultas todo a través de un cliente Drizzle integrado con seguridad de tipos completa. El problema es que la documentación oficial te lleva directamente a Turso para la base de datos de producción, y Turso es la opción obvia por defecto ya que mantienen libSQL.

Pero Astro DB se conecta a cualquier servidor libSQL, no solo a Turso. Y Bunny.net ahora ofrece una base de datos libSQL gestionada que te da la misma URL libsql:// y un token de acceso, está ubicada en la UE, se detiene cuando nadie la consulta y factura por uso. Así que puedes mantener todo el flujo de trabajo local-first de Astro DB y simplemente apuntar la producción a Bunny. Eso es lo que hace esta guía.

Cómo encajan Astro DB y Bunny

Aquí está el modelo mental, porque a mí me confundió al principio. Astro DB tiene dos mitades:

La documentación rellena esas dos variables con valores de Turso. Nosotros las vamos a rellenar con valores de Bunny. Todo lo demás de Astro DB, el esquema, el archivo seed, las consultas Drizzle, permanece exactamente igual.

Requisitos previos

• Un proyecto Astro existente, o uno nuevo (npm create astro@latest)
• Node.js instalado
• Una cuenta de Bunny.net con acceso a Bunny Database (actualmente en vista previa pública)

Si aún no tienes un sitio Astro, tengo una guía sobre cómo crear un blog gratis con Astro que te da un proyecto funcional al que añadir una base de datos.

Paso 1: Instala la integración de Astro DB

Desde la raíz de tu proyecto, deja que Astro lo configure todo:

npx astro add db

Esto instala @astrojs/db, lo añade a tu astro.config.mjs y crea un db/config.ts inicial:

// db/config.ts
import { defineDb } from 'astro:db';

export default defineDb({
  tables: {},
})

Paso 2: Define tus tablas

Las tablas viven en db/config.ts. Astro lee este archivo para generar una interfaz TypeScript para cada tabla, que es lo que te da autocompletado y errores en tiempo de compilación al consultar.

Aquí hay una tabla Comment con un Author al que referencia, la misma estructura que usan los docs de Astro, para que sea fácil de comparar:

// db/config.ts
import { defineDb, defineTable, column } from 'astro:db';

const Author = defineTable({
  columns: {
    id: column.number({ primaryKey: true }),
    name: column.text(),
  },
});

const Comment = defineTable({
  columns: {
    id: column.number({ primaryKey: true }),
    authorId: column.number({ references: () => Author.columns.id }),
    body: column.text(),
    published: column.date({ default: new Date() }),
  },
});

export default defineDb({
  tables: { Author, Comment },
})

Los tipos de columna se traducen limpiamente a SQLite: column.text(), column.number(), column.boolean(), column.date() (consultada como un Date de JavaScript) y column.json() para un blob sin tipo. La propiedad references en authorId establece la relación de clave foránea con Author.id.

Paso 3: Carga datos de desarrollo local

En desarrollo no tocas los datos de producción. Astro vuelve a sembrar una base de datos local nueva desde db/seed.ts cada vez que el archivo cambia, lo que mantiene tu entorno de desarrollo predecible.

// db/seed.ts
import { db, Author, Comment } from 'astro:db';

export default async function () {
  await db.insert(Author).values([
    { id: 1, name: 'Kasim' },
    { id: 2, name: 'Mina' },
  ]);

  await db.insert(Comment).values([
    { authorId: 1, body: 'Hope you like Astro DB!' },
    { authorId: 2, body: 'Enjoy!' },
  ]);
}

Arranca el servidor de desarrollo y la tabla ya está activa en local:

npm run dev

Paso 4: Consulta la base de datos en una página

Puedes consultar desde cualquier página, endpoint o acción de Astro usando el cliente db exportado desde astro:db. Es Drizzle por dentro, ya configurado, sin necesidad de configurar el cliente.

---
// src/pages/index.astro
import { db, Comment, Author, eq } from 'astro:db';

const comments = await db
  .select()
  .from(Comment)
  .innerJoin(Author, eq(Comment.authorId, Author.id));
---

<h2>Comments</h2>
{
  comments.map(({ Author, Comment }) => (
    <article>
      <p>Author: {Author.name}</p>
      <p>{Comment.body}</p>
    </article>
  ))
}

Todos los helpers de consulta de Drizzle, eq(), gt(), like(), count() y la etiqueta sql cruda, vienen directamente de astro:db:

import { eq, gt, count, sql } from 'astro:db';

En este punto todo se ejecuta contra el archivo local. Ahora vamos a darle un hogar real en Bunny.

Paso 5: Crea tu Bunny Database

1. Inicia sesión en el panel de Bunny.net
2. En la barra lateral, haz clic en + Add, luego en Database
3. Dale un nombre (por ejemplo astro-comments). El nombre aparece en tu URL de conexión
4. Elige un modo de despliegue. Single region es lo más barato y suficiente para la mayoría de sitios, Automatic deja que Bunny elija las regiones por ti, y Manual te da control sobre el primario y las réplicas
5. Haz clic en Add Database

Abre la base de datos y ve a la pestaña Access. Necesitas dos cosas aquí:

• Database URL: tiene el formato libsql://<your-database-id>.lite.bunnydb.net
• Access Token: haz clic en Generate Tokens y copia el token Full Access (Astro necesita acceso de escritura para enviar el esquema y persistir datos)

Paso 6: Apunta Astro DB a Bunny

Este es el único paso realmente específico de Bunny, y son solo dos variables de entorno. Mapea los valores de Bunny a las variables que Astro espera:

Colócalas en un archivo .env en la raíz del proyecto:

# .env
ASTRO_DB_REMOTE_URL="libsql://your-database-id.lite.bunnydb.net"
ASTRO_DB_APP_TOKEN="your-full-access-token"

Asegúrate de que .env está en el gitignore. Ese es todo el cambio. Donde los docs de Astro dicen “establece esto a tu URL de Turso”, tú lo estableces a tu URL de Bunny.

Paso 7: Envía tu esquema a Bunny

Por ahora tu esquema local solo existe en db/config.ts. Envíalo a la base de datos Bunny con el flag --remote:

npx astro db push --remote

Esto crea las tablas Author y Comment en Bunny y verifica que el cambio no perderá datos existentes. Si más adelante haces un cambio de esquema incompatible y no te importa borrar la producción, añade --force-reset:

npx astro db push --remote --force-reset

Para cargar datos reales en la base de datos remota (no solo los datos seed locales), ejecuta un archivo seed o de migración contra ella con execute:

npx astro db execute db/seed.ts --remote

Paso 8: Compila y despliega contra Bunny

En local, dev y build usan el archivo local por defecto. Para que producción lea y escriba en Bunny, añade --remote a tu comando de build en package.json:

{
  "scripts": {
    "build": "astro build --remote"
  }
}

También puedes pasarlo directamente cuando quieras una sesión de desarrollo conectada al remoto:

# Build against the Bunny database
astro build --remote

# Develop against the Bunny database
astro dev --remote

Define ASTRO_DB_REMOTE_URL y ASTRO_DB_APP_TOKEN también en el entorno de tu plataforma de despliegue, no solo en local. El flag --remote usa la conexión durante el build y en el servidor, así que ambos entornos necesitan las credenciales.

Aceptar datos de usuarios: un formulario de comentarios

Aquí está la ruta de escritura, usando una acción de Astro para obtener validación con Zod gratis. Esto asume que has añadido un adaptador y habilitado el renderizado bajo demanda.

// src/actions/index.ts
import { db, Comment } from 'astro:db';
import { defineAction } from 'astro:actions';
import { z } from 'astro/zod';

export const server = {
  addComment: defineAction({
    input: z.object({
      authorId: z.number(),
      body: z.string(),
    }),
    handler: async (input) => {
      const created = await db.insert(Comment).values(input).returning();
      return created;
    },
  }),
};

Como la acción se ejecuta en el servidor, tu token de Bunny nunca llega al navegador. El insert va directamente a la base de datos libSQL remota y returning() devuelve la fila nueva.

Réplicas embebidas para lecturas más rápidas

Una función de libSQL que vale la pena conocer: las réplicas embebidas. Puedes mantener una copia local sincronizada de la base de datos Bunny para lecturas muy rápidas, con las escrituras reenviadas a Bunny. Astro lo configura mediante parámetros de consulta en la URL remota:

# In-memory replica synced from Bunny, refreshing every 60s
ASTRO_DB_REMOTE_URL="memory:?syncUrl=libsql%3A%2F%2Fyour-database-id.lite.bunnydb.net&syncInterval=60"
ASTRO_DB_APP_TOKEN="your-full-access-token"

El valor de syncUrl debe estar codificado para URL. Esto es exagerado para un blog pequeño, pero si ejecutas un sitio con muchas lecturas en un solo servidor, convierte la mayoría de lecturas en consultas locales mientras Bunny sigue siendo la fuente de verdad.

Por qué combinar Astro DB con Bunny en lugar de Turso

Ambos son sólidos. Así es como yo planteo la elección:

Si ya ejecutas tu CDN, almacenamiento o vídeo en Bunny, mantener la base de datos en el mismo panel y en la misma factura es la ventaja obvia. Si quieres el host libSQL más maduro, en GA y con las herramientas más profundas, Turso sigue siendo la opción segura. Como ambos son libSQL, puedes cambiar entre ellos más adelante modificando dos variables de entorno y reenviando el esquema, así que no es una puerta de un solo sentido.

Solución de problemas

Preguntas frecuentes

Conclusión

Astro DB te da un flujo de trabajo local-first realmente agradable: tablas tipadas, SQLite local instantáneo y un cliente Drizzle que no necesita cableado. Los docs te dirigen a Turso para producción, pero la conexión remota es simplemente libSQL, así que apuntarla a Bunny es un cambio de dos variables. Obtienes una base de datos que vive en el mismo panel que tu CDN y almacenamiento, se detiene cuando el tráfico está quieto y sigue siendo portable porque es libSQL puro por debajo.

Si tu sitio ya funciona estático en Bunny, esto cierra el círculo: páginas estáticas desde el CDN, datos dinámicos desde Bunny Database, todo en una factura.

Artículos relacionados

• Reseña de Bunny.net - la plataforma completa tras un año en producción
• TanStack Start + Bunny Database + Drizzle - la misma base de datos con Drizzle en crudo en una app React
• Despliega un sitio Astro en Bunny.net - hosting estático en Bunny Storage y CDN
• Crea un blog gratis con Astro - consigue un proyecto inicial al que añadir una base de datos
• Bunny Storage vs S3 vs Backblaze - comparativa de precios de almacenamiento en la nube
• Montar un bucket S3 como sistema de archivos - ZeroFS y JuiceFS en Bunny Storage