Primeros pasos

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

Calíope es un cliente nativo para MySQL, MariaDB, Amazon Aurora y PostgreSQL disponible en macOS, iPad e iPhone. 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 una barra lateral con el árbol de esquemas, 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 doce servidores de prueba en tu Mac, con datos ya cargados.

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 en tu propio Mac el mismo entorno de pruebas con el que se desarrolla la app. Es un solo archivo y no necesita nada más que Docker.

→ Descargar caliope-testbed.command

Qué necesitas. macOS 12 o posterior, Docker Desktop —gratis para uso personal, en docker.com— y unos 2 GB de disco y de memoria libres.

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.

La primera vez tarda unos minutos bajando imágenes, y mientras trabaja va diciendo en qué anda. Al terminar imprime un informe con las direcciones, los puertos y las credenciales.

Qué levanta. Doce 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 y el monitor de replicación 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 doce nodos como un grupo. En Calíope: Ajustes › Conexiones › Importar. La importación fusiona, así que no se borra nada de lo que ya tengas. El usuario es caliope y la contraseña caliopepass. Los dos perfiles que van por túnel 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 los tres aparatos sin editar nada — con el Mac encendido, el testbed corriendo y los dos en la misma red.

Los cuatro comandos.

Cuidado con --fresh: es destructivo y va más allá de Calíope. Para todos los contenedores de Docker de tu Mac 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. A cambio es la única corrida que ofrece descargar los tres juegos de datos de ejemplo, uno por motor: Sakila para MySQL y MariaDB, Pagila para PostgreSQL y la muestra de Atlas para MongoDB. Cada uno se pregunta aparte.

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

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 (3306 por defecto), 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 ⌘[. 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) 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, 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.

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.

Sin conexión el navegador enseña sólo lo que funciona sin servidor: el Editor SQL, los Fragmentos, el Editor SQLite, 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 las veintitantas 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.
- 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, pulsa el botón Conectar al servidor en la barra de herramientas o en el banner superior. Se abre el Gestor de Conexiones como panel flotante sin perder el contenido del editor.

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 y oculta 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 botón a la posición que prefieras.
- Ocultar — desmarca los que no uses; sus acciones siguen disponibles por menú y por atajo de teclado.
- 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 (lanzador de aplicaciones) organiza los accesos directos a todas las herramientas del workspace en grupos lógicos para un flujo de trabajo optimizado:

1. Desarrollo y Consulta — Editor SQL, Query Builder, Fragmentos, Registro SQL y Editor SQLite.
2. Diseño y Estructura — Catálogos, Diagrama ER, Comparación de esquemas y Migración de objetos.
3. Diagnóstico y Rendimiento — Tablero, Salud del servidor, Alertas SQL, Monitoreo de réplicas y Visor de binlogs.
4. Administración del Servidor — Info del servidor, Procesos, Usuarios, Respaldo y Mantenimiento.
5. Asistente Inteligente — Asistente IA.

Cómo abrir el personalizador
- En la parte superior de la barra lateral de navegación 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 MySQL, MariaDB, Aurora o PostgreSQL al mismo tiempo sin perder el contexto de cada uno.

Dónde está: Servidor › Añadir sesión…

Calíope mantiene sesiones independientes para cada perfil de conexión que abres. Cada sesión tiene sus propias pestañas, su propia base de datos activa, su propio historial de queries y sus propias preferencias de layout.

Abrir una nueva sesión
- macOS: menú Servidor › Añadir sesión… o atajo ⌘⌥N. También puedes pulsar Nueva sesión desde el selector de servidor en la esquina superior izquierda.
- iPad: abre el selector de servidor (icono a la izquierda de la barra de pestañas) y pulsa Añadir sesión.

Cambiar entre sesiones
- Usa el selector de servidor desde la esquina superior izquierda (macOS) o desde la barra de pestañas (iPad). Cada sesión muestra el nombre del perfil, el host y un punto de color que indica su estado.
- macOS: atajo ⌘⌥1…9 para saltar directamente a las primeras nueve sesiones.

Estado por sesión
- Cada sesión recuerda la base de datos activa, las pestañas abiertas y el historial de queries dentro de QueryLogger.
- Las conexiones SSH y SSL se establecen una sola vez por sesión; al cambiar de sesión no se reconecta.
- El widget anclado sigue al perfil marcado como anclado en Preferencias › Widget, independientemente de cuál sesión esté en primer plano.

Cerrar una sesión
- Cierra todas las pestañas con la × o usa Servidor › Desconectar. Calíope cierra el túnel SSH si existe.
- Las contraseñas siguen en el Keychain; no se piden de nuevo al reconectar a menos que el perfil requiera 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>.

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