Primeros pasos

Visión general de la aplicación y su flujo de trabajo.

Calíope es un cliente nativo para MySQL, MariaDB, PostgreSQL, Microsoft SQL Server, Oracle Database, ClickHouse, MongoDB y Redis disponible en macOS, iPad, iPhone y Apple Vision Pro. El flujo de trabajo principal tiene dos pantallas: el Gestor de Conexiones, donde se administran los perfiles de servidor, y el Espacio de Trabajo, que se abre una vez establecida la conexión.

El Espacio de Trabajo contiene la barra lateral Herramientas —el árbol de esquemas vive dentro del Editor SQL—, una barra de pestañas para abrir múltiples herramientas simultáneamente, y una barra de acceso rápido a todas las herramientas.

Palabras clave: inicio, overview, presentación, qué es, introducción

Un archivo levanta hasta cuarenta servidores de prueba, con datos ya cargados: tú eliges cuáles.

Si no tienes ningún servidor a mano, o quieres ver de qué es capaz Calíope antes de apuntarlo a uno tuyo, puedes levantar el mismo entorno de pruebas con el que desarrollo la app. Es un solo archivo y no necesita nada más que Docker.

→ Descargar caliope-testbed.command

Qué necesitas. Un Mac con Docker Desktop —gratis para uso personal, en docker.com— y disco: unos 39 GB con todo, 14 de ellos la imagen de Oracle, que crecen con el tiempo porque los generadores de carga escriben sin parar. La memoria depende de lo que levantes: con todo arriba son unos 15 GB para Docker, y ni SQL Server ni Oracle arrancan con menos de 2 GB libres. Antes de arrancar, el propio lanzador te dice cuánta memoria necesita lo que elegiste y cuánta tiene Docker.

Cómo se pone en marcha. Lo más limpio es pegar estas cuatro líneas en Terminal:

cd ~/Downloads
curl -fLO https://caliope.org/caliope-testbed.command
chmod +x caliope-testbed.command
./caliope-testbed.command

Si prefieres descargarlo con el navegador, hacen falta dos cosas más y en este orden: darle permiso de ejecución (chmod +x sobre el archivo descargado) y abrirlo la primera vez con clic derecho › Abrir en vez de doble clic, porque macOS pone en cuarentena lo que baja un navegador. Con curl no pasa ninguna de las dos.

Primero pregunta qué levantar. Abierto en Terminal, el lanzador recorre los motores contigo: escribes los números de los que quieres y, de cada uno, eliges el mínimo, todo o a medida, con lo que pesa cada pieza al lado. Las dependencias se resuelven solas: un nodo de túnel trae el bastión SSH, y el segundo shard de ClickHouse trae la pareja replicada. Después ofrece los datos de ejemplo de los motores elegidos —Sakila para MySQL y MariaDB, Pagila para PostgreSQL y la muestra de Atlas para MongoDB—, que se descargan en segundo plano mientras arrancan los contenedores y se cargan en cuanto sus nodos están en pie; si ya estaban cargados, no se vuelven a bajar. Cada cosa que termina se avisa con una línea en la terminal y con una notificación de macOS. La vez siguiente, cada respuesta trae por omisión la anterior, y Enter repite el arranque entero. Lo que corría de antes y no elegiste se para, sin perder sus datos.

Mientras trabaja va diciendo en qué anda, y al terminar imprime un informe con las direcciones, los puertos, las credenciales y el estado de cada grupo de replicación.

Qué puede levantar. Hasta cuarenta servidores, elegidos para que ninguna herramienta de Calíope se quede sin nada que enseñar:

Con un bastión SSH y generadores de carga continua, así que el Tablero, el registro de consultas lentas, la lista de procesos, el monitor de replicación y la topología tienen tráfico de verdad que mostrar.

Los perfiles no se escriben a mano. Cada corrida deja un archivo caliope-testbed-connections.json junto al lanzador con los nodos que levantó, como un grupo. En Calíope: Ajustes › Conexiones › Importar. La importación fusiona, así que no se borra nada de lo que ya tengas. Cada perfil lleva ya su usuario y su contraseña: caliope y caliopepass en casi todos, caliope_admin en ClickHouse, sa con Caliope!pass1 en SQL Server y system con Caliope_pass1 en Oracle. Los perfiles que van por túnel —hasta cinco— piden su contraseña de SSH (tunnel123) la primera vez, porque los secretos de SSH sólo viven en el Llavero.

También desde el iPad y el iPhone. Cada perfil lleva la dirección de red del Mac como alternativa, así que el mismo archivo sirve en todos tus aparatos sin editar nada — con el Mac encendido, el testbed corriendo y los dos en la misma red.

En otra máquina. Con --remote, el mismo lanzador levanta el testbed en el Docker de otra máquina de tu red —un Linux con SSH—, y la prepara la primera vez: pide su dirección y su usuario, instala una llave SSH y, si falta, Docker. Así la memoria y la CPU que se gasta no son las de tu Mac.

Los comandos.

Cuidado con --fresh: es destructivo y va más allá de Calíope. Para todos los contenedores de Docker de esa máquina y borra imágenes, volúmenes y cachés que nadie esté usando, incluidos los de otros proyectos tuyos. Lo dice y pide confirmación antes de hacer nada.

Esto no es un servidor para trabajar. Las contraseñas son públicas y están escritas dentro del propio archivo, nada va cifrado y todo escucha en tu máquina. Es una cama de pruebas: para aprender, para probar una herramienta antes de usarla sobre datos tuyos, y para que un informe de fallo se pueda reproducir.

Palabras clave: docker, prueba, testbed, ejemplo, sin servidor, demo, practicar, sakila, replicación, asistente

Un archivo SQLite de unos ochenta megabytes, con productos e imágenes reales, para el Editor SQLite y el Previsualizador.

Si quieres ver cómo se comporta Calíope con un archivo grande y realista, o simplemente probar el Editor SQLite y el Previsualizador sin tener ningún servidor a mano, puedes descargar una base de datos de muestra ya cargada.

→ Descargar caliope-demo.db

Qué tiene. Unos ochenta megabytes repartidos en dos tablas relacionadas: productos, con unos mil quinientos artículos —nombre, descripción, precio, existencias, fecha de alta, categoría y un puñado de atributos en JSON—, e imagenes, con varias fotografías reales por producto: cada una es un PNG de verdad, no un relleno. Lleva también sus índices, la clave foránea entre las dos tablas y una vista (vista_catalogo) que las combina.

Algunos productos no tienen categoría, descripción ni atributos: es a propósito, para poder mirar cómo se ven los valores nulos.

Todo el texto está en español, con acentos, eñes y algún emoji, para comprobar de un vistazo que el manejo de UTF-8 es correcto.

Cómo se abre. Descárgala y ábrela desde el Editor SQLite con Abrir…; se trata como cualquier otro archivo .sqlite/.db, sin necesitar ninguna conexión.

No se actualiza sola. Es un archivo estático, y cada vez que se vuelve a generar puede pesar un poco distinto.

Palabras clave: sqlite, demo, ejemplo, muestra, imagenes, blob, prueba, sin servidor, offline, utf-8

Crea un perfil y establece tu primera conexión a un servidor.

Dónde está: Gestor de Conexiones › Botón +

En el Gestor de Conexiones pulsa el botón + en la barra lateral para crear un nuevo perfil. Completa el host, puerto (el formulario propone el de cada motor), usuario y contraseña. Pulsa Probar conexión para verificar los datos antes de guardar.

Una vez validados, pulsa Conectar para abrir el Espacio de Trabajo. El perfil queda guardado y estará disponible en la lista para conexiones futuras.

Palabras clave: primera vez, nueva conexión, perfil, host, puerto

Cómo usar la barra lateral Herramientas, las pestañas, el selector de servidor y la barra de estado.

El Espacio de Trabajo se divide en tres zonas: la barra lateral Herramientas a la izquierda, la barra de pestañas con las herramientas abiertas, y la barra de estado al pie.

Para abrir una herramienta pulsa su fila en la barra lateral. Cada una se abre en su propia pestaña; puedes tener varias abiertas y moverte entre ellas con ⌘} y ⌘{ en el Mac (⌘] y ⌘[ en el iPad). Las filas están agrupadas por tema, y el orden y los grupos se ajustan desde el botón ⋮≡ de la propia barra lateral (ver Personalizar la barra principal). Cada grupo se colapsa pulsando su cabecera, y el campo de arriba de la barra lateral filtra las herramientas por su nombre (ver Filtrar y colapsar la barra lateral).

Selector de servidor: en la esquina superior izquierda (macOS) o a la izquierda de la barra de pestañas (iPad); en iPhone también está arriba de la lista Herramientas está el menú con el nombre del servidor activo. Desde ahí puedes cambiar de sesión, añadir otro servidor o desconectar. Calíope permite varias conexiones activas a la vez.

Ocultar la barra lateral: el botón de la barra de título la repliega y deja todo el ancho a la herramienta activa.

El árbol de esquema no está aquí: vive dentro del Editor SQL, que es el único sitio donde se usa.

Sin conexión: el Espacio de Trabajo sin servidor muestra una tira de acceso rápido con lo que no necesita conexión —Editor SQL, Fragmentos, Editor SQLite, Editor DuckDB, Previsualizador de archivos, Errores y Reportes—. El chevron de su extremo derecho la colapsa.

En el iPhone y en ventana estrecha: las herramientas van en una barra inferior con las cuatro primeras de tu orden y un botón Más para el resto. Cuáles son esas cuatro lo decides tú reordenando la barra lateral.

Apple Vision Pro: el navegador de herramientas cuelga fuera de la ventana, a su izquierda, y la barra de pestañas encima, con el selector de servidor delante y, al final, actividad, mantener despierto, Ayuda y Ajustes. La cabecera de cada herramienta cuelga debajo de la ventana. No hay botón en la barra de título para ocultar la barra lateral: lo hace el menú Ver. Consulta Calíope en Apple Vision Pro.

Palabras clave: espacio de trabajo, workspace, barra lateral, herramientas, pestañas, navegación, selector de servidor, barra de estado, sin conexión

La lista del navegador la decide la conexión, no un ajuste que hayas tocado.

El navegador de herramientas no enseña siempre lo mismo: enseña lo que esta sesión puede hacer. Al conectar, Calíope resuelve qué sabe hacer esa conexión y esconde el resto. Lo que no ves no está roto ni desactivado: no se ofrece.

Esconderlo es deliberado. Una herramienta que se abre sólo para decir «aquí no» ya te ha hecho perder el viaje, y una fila apagada invita a buscar el interruptor que la encienda — y no existe.

Por la clase de base de datos. Un servidor relacional y uno de documentos no se parecen: en una sesión de documentos no hay editor SQL ni diagrama entidad-relación, y en una relacional no hay explorador de colecciones. Eso no cambia nunca, y no es una carencia de ninguno de los dos.

Por lo que esa conexión sabe hacer. Dos servidores relacionales tampoco ofrecen exactamente lo mismo. A veces el motor no tiene ese concepto, y entonces la herramienta no va a aparecer nunca contra ese servidor porque no habría nada que enseñar; a veces Calíope todavía no la ha escrito para ese motor, y aparecerá en una versión posterior. Las dos ausencias se ven igual a propósito: lo que necesitas saber ahora es si la herramienta sirve, no por qué no.

Por la etiqueta de la conexión. Si la conexión lleva una etiqueta de entorno de solo lectura, se esconden además las herramientas que sólo escriben —el Constructor de tablas, la Administración de usuarios, el Mantenimiento de tablas y la Migración de datos—, y si alguna se pide, la barra de estado dice que la sesión es de solo lectura. Basta cambiar la etiqueta para que vuelvan, sin reconectar.

Sin conexión el navegador enseña sólo lo que funciona sin servidor: el Editor SQL, los Fragmentos, el Editor SQLite, el Editor DuckDB, el Previsualizador de archivos, los Errores y los Reportes — éstos a medias, porque sin servidor se pueden ver, editar y exportar, pero no ejecutar.

Dónde más se nota. El botón Ir de esta Ayuda puede apuntar a una herramienta que tu sesión no ofrece: entonces no se abre nada y la barra de estado lo dice con su nombre. Es una respuesta, no un fallo.

Y esta Ayuda las lleva todas. El índice no cambia con el servidor al que estés conectado, así que aquí vas a encontrar temas de herramientas que tu sesión de ahora no enseña. Si echas una en falta, prueba a abrir una sesión contra otro servidor: la lista se vuelve a calcular en cada conexión.

Palabras clave: herramientas, faltan, no aparecen, navegador, disponibilidad, motor, sesión, escondidas, Ir

Colapsa los grupos que no usas y escribe en el campo de arriba para encontrar una herramienta por su nombre.

La barra lateral Herramientas reparte por temas todas las herramientas de Calíope. Dos cosas la acortan.

Colapsar un grupo: pulsa su cabecera. El chevron gira y las filas del grupo desaparecen; junto al nombre queda el número de herramientas que está escondiendo, para que ninguna se pierda sin dejar rastro. Púlsala otra vez para volver a abrirlo. Lo que colapsas se recuerda al cerrar la app, y viaja a tu otro Mac, iPad o iPhone si tienes activada la sincronización con iCloud.

Filtrar: el campo de arriba deja sólo las herramientas que coinciden con lo que escribes. Busca en el nombre de la herramienta, en su nombre completo del catálogo y en la frase que dice qué hace, y además en el nombre de su grupo — así, escribir el nombre de un grupo lo enseña entero. Las tildes no importan: replicacion encuentra Replicación.

Mientras filtras, todo grupo con coincidencias se dibuja abierto, incluso los que tenías colapsados. Nada de lo que encuentres puede quedarse escondido dentro de un grupo cerrado. Tus grupos colapsados no se tocan: vacía el campo y todo vuelve exactamente a como estaba.

Pulsa Esc o la × para limpiar el campo. El filtro no se recuerda al cerrar la app: una barra lateral que arranca medio vacía por un motivo que no recuerdas es peor que volver a escribir tres letras.

Palabras clave: barra lateral, herramientas, filtrar, buscar, grupos, colapsar, expandir

Lo que funciona sin conectar a ningún servidor, y lo que no.

Calíope incluye un Espacio de Trabajo offline accesible incluso cuando no hay ningún servidor conectado. Es útil para redactar consultas y organizar tus fragmentos sin necesitar conexión.

Cómo acceder:

Desde el Gestor de Conexiones, sin conectar a ningún servidor. Dónde está el botón depende del sitio que haya: en pantalla ancha —el Mac y el iPad— está en la pantalla de bienvenida, junto a «Crear perfil»; en pantalla estrecha —el iPhone, y el iPad con la ventana partida— esa pantalla no se dibuja, así que va en la barra de abajo, con el icono de terminal.

Herramientas disponibles en modo offline:
- Editor SQL — escribe y guarda SQL, usa el historial y los fragmentos. Las consultas no pueden ejecutarse contra un servidor.
- Fragmentos — crea, edita y copia tus fragmentos de código.
- Editor SQLite — abre un archivo .sqlite del disco y trabájalo entero: no necesita servidor porque la base es el archivo.
- Editor DuckDB — abre un archivo .duckdb —o un CSV, JSON o Parquet en una base en memoria— y consúltalo en el propio aparato, sin servidor.
- Previsualizador de archivos — mira CSV, JSON, Markdown y demás sin salir de la app.
- Errores — el registro es local, y hay que poder leerlo justo cuando no se puede conectar.
- Reportes — se pueden ver, editar y exportar los resultados que ya tenías; ejecutar uno sí necesita servidor, y la vista lo dice.

Banner de modo offline: una franja dorada en la parte superior del workspace indica que estás en modo sin conexión.

Para conectar a un servidor desde el workspace offline: en el Mac, pulsa Conectar servidor en la barra de la ventana, que abre el Gestor de Conexiones en su propia ventana; en el iPad, el iPhone y Apple Vision Pro, Conectar en la barra de arriba, que lo abre como hoja. En los dos casos el contenido del editor se conserva. La franja de modo offline sólo avisa: no tiene botón.

Palabras clave: offline, sin conexión, modo offline, sin servidor, editor offline, workspace offline, editor sin conexión, fragmentos

Muestra el resultado, el tiempo y el progreso de las operaciones en curso.

La barra de estado aparece en la parte inferior del Espacio de Trabajo y del editor SQL. Refleja el estado de la última operación ejecutada.

Información que muestra:
- Mensaje de resultado — texto descriptivo de la última operación (filas afectadas, tiempo de ejecución, error).
- Progreso — barra de progreso o animación de carga mientras una consulta o tarea está en ejecución.
- Porcentaje — en operaciones largas (como backups o restauraciones) muestra el avance numérico.

Copiar el mensaje:

macOS: haz doble clic sobre el área de texto de la barra de estado para copiar el mensaje completo al portapapeles. Útil para copiar mensajes de error sin tener que seleccionarlos manualmente.

iPad: el mismo gesto de doble tap copia el mensaje.

La barra de estado está siempre visible y no puede ocultarse.

Palabras clave: barra de estado, status bar, progreso, mensaje, copiar mensaje, error, tiempo de ejecución, doble clic

Reordena los botones de la barra del editor y de la barra de resultados.

Dónde está: Editor SQL › Personalizar la barra

El Editor SQL tiene dos barras de botones propias, y cada una se personaliza por separado:

- Barra del editor — la de encima del área de texto: ejecutar, formatear, comentar, historial, panel de esquema…
- Barra de resultados — la de encima de la rejilla: exportar, gráfico, perfilador de columnas, filtros…

Cómo abrir el personalizador
Pulsa el botón ⋮≡ (icono slider.horizontal.3) al principio de la barra que quieras ajustar.

Qué puedes hacer
- Reordenar — arrastra cada grupo de botones a la posición que prefieras, o usa Subir y Bajar de su menú contextual.
- Restablecer — vuelve a la disposición original de esa barra.

Las dos barras se desplazan en horizontal, así que ningún botón queda inalcanzable por estrecha que sea la ventana.

Para el lanzador de herramientas del Espacio de Trabajo, mira Personalizar la barra principal.

Palabras clave: barra del editor, barra de resultados, personalizar, reordenar, ocultar botones, arrastrar, editor sql

Reordena los botones de la barra principal del Espacio de Trabajo para poner tus herramientas favoritas primero.

Dónde está: Workspace › Personalizar la barra principal

La barra lateral de navegación reúne todas las herramientas del workspace en grupos por tema —desarrollo y consulta, diseño y estructura, diagnóstico y rendimiento, administración del servidor…—. El reparto de fábrica es sólo un punto de partida: los grupos, su orden y lo que va en cada uno se cambian aquí.

Cómo abrir el personalizador
- Al pie de la barra lateral de navegación, junto al indicador de rendimiento, encontrarás el botón de personalización ⋮≡ (icono slider.horizontal.3).
- Púlsalo para abrir la pantalla de personalización.

Qué puedes hacer
El personalizador ofrece un control jerárquico y dinámico dividido en dos pestañas:
- Pestaña "Reordenar Grupos" — Permite arrastrar y soltar secciones completas para cambiar el orden de las categorías, renombrarlas o incluso añadir tus propios grupos personalizados.
- Pestaña "Reordenar Elementos" — Permite arrastrar y soltar herramientas individuales dentro de cada grupo, o pulsar Mover a... para desplazar cualquier herramienta a otra sección de forma dinámica.
- Restablecer — El botón Restablecer vuelve al orden y agrupación nativos por defecto en un solo toque.

Persistencia y Autocuración
La configuración se guarda de forma segura en UserDefaults (bajo la clave caliope_sidebar_config_macos o caliope_sidebar_config_ipad). Si Calíope añade una nueva herramienta en una futura actualización, se insertará automáticamente en su grupo predeterminado sin interferir en tu personalización previa.

Palabras clave: barra principal, quick access, nav strip, personalizar, reordenar, botones, arrastrar, overflow

Trabaja con varios servidores al mismo tiempo sin perder el contexto de cada uno.

Dónde está: Menú de servidor › Añadir servidor

Calíope mantiene sesiones independientes para cada servidor al que te conectas. Cada sesión tiene sus propias pestañas, su propia base de datos activa y su propio historial de consultas.

Abrir otra sesión
- Abre el menú de servidor —en la barra de la ventana en macOS, a la izquierda de la barra de pestañas en iPad— y pulsa Añadir servidor. Se abre el Gestor de conexiones: elige un perfil y pulsa Conectar. Las sesiones que ya tenías siguen abiertas.

Cambiar entre sesiones
- En el mismo menú, pulsa el servidor al que quieras ir. Cada sesión enseña el nombre del perfil y un punto de color con su estado.
- El menú de servidor no está en la barra de menús: vive en la ventana, porque cada ventana puede estar mirando una sesión distinta.

Estado por sesión
- Cada sesión recuerda su base de datos activa, sus pestañas abiertas y su historial de consultas.
- El túnel SSH y el cifrado se establecen una vez por sesión; cambiar de sesión no reconecta.
- El widget sigue al perfil fijado en Ajustes › Widget, esté delante la sesión que esté.

Cerrar una sesión
- Desconectar, en el menú de servidor o en el menú Archivo (⌘⇧D), cierra la sesión activa, y su túnel SSH si lo tiene.
- Las contraseñas siguen en el Llavero: no se piden de nuevo al reconectar, salvo que tengas activada la biometría.

Palabras clave: sesiones, multi-sesión, varios servidores, simultáneas, cambiar sesión, selector servidor, añadir sesión, session manager, ⌘⌥N, desconectar

Cómo acceder al índice completo de ayuda desde cada plataforma.

Dónde está: Ayuda › Ayuda de Calíope

La ayuda de Calíope está disponible como ventana o panel dedicado con índice, buscador y navegación por secciones. Se abre distinto según la plataforma pero muestra el mismo contenido.

macOS: menú Ayuda › Ayuda de Calíope o atajo ⌘?. La ventana queda flotando y puede permanecer abierta mientras usas el resto de la app.

iPad: menú Ayuda › Ayuda de Calíope o atajo ⌘? si tienes un teclado externo conectado. La ayuda aparece como panel deslizable; ciérralo con el botón Cerrar en la esquina superior derecha o desliza hacia abajo.

Ayuda contextual (?): cada vista de la app tiene un botón ? en su barra superior que abre directamente el tema relacionado. Es la vía más rápida cuando ya sabes qué herramienta te interesa.

En la web: la misma Ayuda está publicada en https://caliope.org/help/, en los cinco idiomas. Desde allí, con «Tengo Calíope instalada» activado, cada tema tiene un botón «Abrir en Calíope» que lo abre en la app; el enlace de un tema tiene la forma caliope://help/<identificador>.

Apple Vision Pro: la Ayuda es la misma hoja que en el iPad, pero una hoja de visionOS no se cierra deslizándola hacia abajo: ciérrala con Cerrar (o Listo, si la abriste desde un «?» o desde un error).

Palabras clave: ayuda, help, índice, buscar tema, menú ayuda, ⌘?, documentación, cmd?

Filtrar los temas por motor, saltar de un tema a su herramienta y llevar un ejemplo de SQL al editor.

El menú Todos los motores de la cabecera del índice deja sólo los temas de un motor y los que valen para todos. Un motor trae también lo de su familia: filtrar por Aurora trae lo de MySQL. El filtro se recuerda entre aperturas y se quita con Quitar filtro.

En la cabecera de un tema con ubicación, Ir cierra la Ayuda y abre esa herramienta o los Ajustes.

En cada bloque de SQL del Manual del DBA, Abrir en el editor carga el ejemplo en el Editor SQL de la sesión abierta; fuera del Mac cierra además la Ayuda.

Palabras clave: ayuda, filtro, motor, ir, ejemplo, SQL, editor

Con la ventana estrecha, las herramientas van en una barra abajo: las cuatro primeras de tu orden y el resto en Más.

Cuando la ventana es estrecha, la barra lateral no se dibuja y las herramientas pasan a una barra abajo. Van las cuatro primeras del orden que eliges en el personalizador, y el resto en Más. Cambiar el orden en el personalizador cambia cuáles se ven.

En el Mac esta barra no existe, y en Apple Vision Pro el navegador va en su ornamento.

Palabras clave: barra de abajo, herramientas, más, pantalla estrecha, personalizar

Si la conexión de la sesión se cae, sale Conexión perdida: puedes volver al gestor de conexiones o dejar las pestañas como estaban.

Si la conexión de la sesión se cae, sale el aviso Conexión perdida.

Volver al inicio desconecta la sesión y vuelve al gestor de conexiones. Cancelar cierra el aviso y deja las pestañas como estaban.

Palabras clave: conexión perdida, desconectar, sesión, volver