Como programadores muchas veces hemos tenido que utilizar o incluso diseñar estructuras de bases de datos. El problema es que, según crecen los proyectos, entender rápidamente su estructura deja de ser tan sencillo.

Aquí es donde entra en juego ChartDB, una herramienta pensada para visualizar estos esquemas de una manera mucho más clara. Nos permite representar tablas, columnas y relaciones de forma gráfica, algo muy útil tanto para documentación como para comprender mejor aplicaciones.

Es totalmente gratuita y nos da una opción de selfhost, que es lo que vamos a cubrir en este post.

Requisitos

Para poder seguir esta guía necesitaremos lo siguiente:

  • Un servidor con Docker y Docker Compose instalados.
  • Acceso al terminal de dicho servidor.
  • Una base de datos existente que queramos documentar o explorar, si queremos sacarle partido desde el primer momento.
  • Recomendable:
    • Un proxy inverso o VPN si queremos acceder de forma segura desde fuera de casa.

Instalación

La forma más cómoda de desplegar ChartDB en nuestro homelab es mediante docker compose, ya que nos permitirá dejar definida la aplicación en un único fichero y levantarla fácilmente cuando queramos.

Crear el directorio del proyecto

Lo primero será crear una carpeta específica para este servicio:

mkdir ./chartdb
cd ./chartdb

A partir de ahora trabajaremos dentro de este directorio.

Crear el fichero docker-compose.yml

Dentro de la carpeta anterior crearemos un fichero llamado docker-compose.yml con un contenido similar al siguiente. Como siempre, recuerda adaptarlo a tus necesidades.

services:
  chartdb:
    image: ghcr.io/chartdb/chartdb:latest
    container_name: chartdb
    ports:
      - "8080:80"
    restart: unless-stopped
	volumes:
      - ./data:/app/data

Con esta configuración estamos indicando que:

  • Usaremos la imagen oficial de ChartDB.
  • El contenedor se llamará chartdb.
  • Expondremos el servicio en el puerto 8080 de nuestro servidor anfitrión.
  • Se reiniciará automáticamente salvo que lo detengamos manualmente.
  • Almacenaremos los datos de la aplicación en la ruta ./data.

Puerto

Si ya tienes otros servicios usando ese puerto, tan solo tendrás que cambiar el valor de la izquierda. Por ejemplo, 8081:80.

Lanzar el contenedor

Una vez guardado el fichero, ya podremos iniciar el servicio:

sudo docker compose up -d

Si todo va bien, Docker descargará la imagen y levantará el contenedor en segundo plano. Para comprobar que está funcionando correctamente, podemos ejecutar:

sudo docker compose ps

Y también revisar los logs si fuese necesario:

sudo docker compose logs -f

Interfaz web

Con la aplicación ya lanzada, podremos acceder a su interfaz web desde el navegador usando la IP de nuestro servidor y el puerto configurado en el docker-compose.yml.

En el ejemplo anterior sería:

http://IP_DE_TU_SERVIDOR:8080

Una vez dentro, veremos la interfaz principal de ChartDB, desde la cual podremos empezar a trabajar con nuestros esquemas de base de datos.

Uso básico

La utilidad principal de ChartDB es ayudarnos a representar visualmente la estructura de una base de datos. Esto puede venirnos especialmente bien si:

  • Tenemos una base de datos ya existente que no terminamos de visualizar.
  • Queremos generar una nueva estructura para una aplicación que estemos desarrollando.
  • Vamos a hacer cambios en una base de datos que no controlamos del todo.

Dependiendo de estos puntos anteriores, podemos empezar a trabajar en ChartDB desde cero, o desde un archivo importado de una base de datos que ya tengamos a disposición, para así poder visualizar el diagrama.

Esto nos permite ver de forma mucho más clara:

  • Las tablas existentes.
  • Sus columnas y tipos.
  • Las claves primarias y otras restricciones.
  • Las relaciones entre unas tablas y otras.

En muchos casos, una vista así ahorra bastante tiempo frente a revisar el esquema directamente desde sentencias SQL o paneles menos visuales. Y ya no hablemos a nivel de documentación técnica, que aquí sí que se da un paso importante.

Aquí un ejemplo:

Configuración de tablas

Cuando creamos una tabla, podemos hacerlo con click derecho en el grid, o podemos gestionarlo desde su apartado en el menú izquierdo:

Relaciones o referencias

También podemos gestionar las relaciones entre las tablas, ya sea desde la propia interfaz visual, o desde su apartado en el menú izquierdo de Refs:

Aquí nos aparecerán todas las que tenemos, pudiendo modificarlas; o crear nuevas dándole al botón de Agregar Relación en la parte superior derecha de este menú.

Lenguaje DBML

Son las siglas de DataBase Markup Languaje, y se trata de un lenguaje estándar para definir estructuras de bases de datos. ChartDB trabaja sobre esto, y nos permite editarlo directamente como si de código se tratase, si nos resulta más práctico.

La ventaja es que nos permite compartir nuestros esquemas de forma más cómoda, gestionarlos incluso como repositorios de código, etc.

Aquí un ejemplo:

Table "public"."users" {
  "user_id" bigint [pk, not null, increment]
  "user_name" varchar(500) [not null]
  "user_mail" varchar(500) [not null]
  "user_register_date" timestamp [not null]
  "user_bio" text
}

Table "public"."posts" {
  "post_id" bigint [pk, not null, increment]
  "post_content" text [not null]
  "post_date" timestamp [not null]
  "post_update_date" timestamp
  "post_delete_date" timestamp
}

Table "public"."user_posts" {
  "user_posts_user_id" bigint [not null, ref: > "public"."users"."user_id"]
  "user_posts_post_id" bigint [not null, ref: > "public"."posts"."post_id"]

  Indexes {
    (user_posts_user_id, user_posts_post_id) [pk]
  }
}

Table "public"."comments" {
  "comment_id" bigint [pk, not null, increment]
  "comment_content" bigint [not null]
  "comment_date" timestamp [not null]
  "comment_parent_id" bigint
  "comment_update_date" timestamp
  "comment_delete_date" timestamp
}

Table "public"."users_comments" {
  "users_comments_user_id" bigint [not null, ref: > "public"."users"."user_id"]
  "users_comments_comment_id" bigint [not null, ref: > "public"."comments"."comment_id"]

  Indexes {
    (users_comments_user_id, users_comments_comment_id) [pk]
  }
}

Table "public"."posts_comments" {
  "post_comments_post_id" bigint [not null, ref: - "public"."posts"."post_id"]
  "post_comments_comment_id" bigint [not null, ref: - "public"."comments"."comment_id"]

  Indexes {
    (post_comments_post_id, post_comments_comment_id) [pk]
  }
}

Importado y Exportado

Teniendo en cuenta el uso de DBML, tanto importar como exportar nuestro esquema resulta muy sencillo y cómodo.

Pero si estamos en la situación de que queremos visualizar una base de datos ya existente, ChartDB nos permite importar desde un dump de casi cualquiera de los proveedores de bases de datos relacionales.

Y por supuesto podemos hacer este mismo camino pero a la inversa: Generar los DDL para ejecutarlos en el motor que deseemos, como pueden ser PosrgreSQL o MariaDB.

También contamos con la posibilidad de generar imágenes de nuestra estructura, ideal para generar documentación técnica de los proyectos. He de decir que esto me ha salvado la vida en muchas ocasiones en conjunto con Obsidian.

Aquí un ejemplo del exportado a PostgreSQL del esquema, que lo podemos obtener haciendo clic en Acciones > Exportar SQL > PostgreSQL:

Conclusión

Con ChartDB podemos añadir a nuestro homelab una herramienta muy práctica para visualizar y entender mejor la estructura de nuestras bases de datos.

Su despliegue con Docker Compose es muy sencillo, por lo que en pocos minutos podemos tenerla funcionando en nuestro servidor y lista para ayudarnos a documentar proyectos, revisar relaciones entre tablas o simplemente comprender mejor cómo está organizada la información de nuestras aplicaciones.

Y todo esto en la privacidad de nuestra red, por lo que no debemos preocuparnos por datos sensibles u otros aspectos en el mundo laboral.

Referencias

Vídeo

0:00
/2:14