scavengr 0.0.2

Scavengr — Recolector y documentador de metadatos en bases de datos

🗃️ Scavengr

"Descubre lo que tus bases esconden."

Scavengr es una herramienta de línea de comandos para extraer, validar y documentar metadatos de bases de datos con inteligencia automática 🧠✨

Extrae esquemas de bases de datos, genera archivos DBML compatibles con dbdiagram.io, crea diccionarios de datos profesionales y produce informes analíticos detallados.

---

🚀 Características Principales

🔍 Extracción de Metadatos

• Múltiples motores: PostgreSQL, MySQL/MariaDB y SQL Server
• Extracción completa: Tablas, columnas, tipos de datos, relaciones, índices
• Formato DBML: Archivos compatibles con dbdiagram.io para visualización
• Configuración simple: Usa archivo .env para credenciales

📊 Diccionarios de Datos Profesionales

• Formato Excel avanzado: 19 campos especializados por columna
• Análisis de sensibilidad: Clasificación automática (CRÍTICO, ALTO, MEDIO, BAJO)
• Descripciones inteligentes: Generación automática basada en 80+ patrones
• Observaciones contextuales: Warnings y recomendaciones automáticas

✅ Validación de Esquemas DBML

• Validación exhaustiva: Sintaxis, estructura y consistencia
• Detección de errores: Tablas, relaciones, claves y tipos de datos
• Análisis de integridad: Verifica referencias y relaciones

📈 Reportes Analíticos

• Score de calidad: Evaluación en 7 dimensiones
• Análisis estadístico: Distribución de tipos, tamaños, relaciones
• Recomendaciones: Mejoras priorizadas por impacto
• Formato Excel: 5 hojas con información completa

---

⚡ Instalación

Requisitos Previos

• Python: 3.8 o superior (recomendado: 3.10+)
• pip: Gestor de paquetes de Python

Instalación desde PyPI

La forma más sencilla de instalar Scavengr es directamente desde PyPI:

pip install scavengr

Instalación desde Fuente - En modo Desarrollo

# Clonar repositorio
git clone https://github.com/JasRockr/Scavengr.git
cd Scavengr

# Crear entorno virtual (recomendado)
python -m venv .venv

# Activar entorno virtual
# En Windows (PowerShell):
.venv\Scripts\Activate.ps1
# En Linux/Mac:
source .venv/bin/activate

# Instalar Scavengr en modo desarrollo
pip install -e .

# Verificar instalación
scavengr --version

Dependencias por Motor de Base de Datos

# Para PostgreSQL
pip install psycopg2-binary

# Para MySQL/MariaDB
pip install mysql-connector-python

# Para SQL Server
pip install pyodbc
# En Windows: Instalar ODBC Driver 17 for SQL Server
# Descargar desde: https://learn.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server

---

🎯 Uso Básico

1️⃣ Configuración Inicial

Crea un archivo .env en la raíz del proyecto:

# Copiar plantilla de ejemplo
cp .env.example .env

# Editar con tus credenciales
# Ejemplo para PostgreSQL:
DB_TYPE=postgresql
DB_HOST=localhost
DB_PORT=5432
DB_NAME=mi_base_datos
DB_USER=usuario_lectura
DB_PASSWORD=contraseña_segura
DB_SCHEMA=public

Tipos de base de datos soportados: postgresql, mysql, mssql

2️⃣ Extraer Esquema de Base de Datos

# Extrae esquema completo a archivo DBML
scavengr extract -o /ruta/mi-esquema.dbml

Resultado: Archivo DBML con:

• ✅ Definición de tablas y columnas
• ✅ Tipos de datos nativos
• ✅ Primary keys y foreign keys
• ✅ Índices con columnas
• ✅ Valores por defecto
• ✅ Relaciones entre tablas

3️⃣ Validar Archivo DBML

# Valida sintaxis y estructura
scavengr validate -i /ruta/mi-esquema.dbml

# Salida típica:
# ✓ Estructura de tablas: OK
# ✓ Relaciones: 875 validadas
# ⚠ Advertencias: 16 (tablas de auditoría, temporales)
# ✓ Errores: 0

4️⃣ Generar Diccionario de Datos

# Genera diccionario en Excel (recomendado)
scavengr dictionary -i /ruta/mi-esquema.dbml -o /ruta/diccionario.xlsx

Resultado: Archivo Excel con 19 campos por columna:

• Nombre de tabla y columna
• Tipo de dato y tamaño
• Clasificación de sensibilidad (CRÍTICO, ALTO, MEDIO, BAJO)
• Descripción generada automáticamente
• Observaciones y recomendaciones
• Máscaras de datos sugeridas
• Ejemplos de valores
• Criterios de calidad

5️⃣ Generar Reporte Analítico

# Genera reporte con métricas en Excel
scavengr report -i /ruta/mi-esquema.dbml -o /ruta/reporte-analisis.xlsx

Resultado: Archivo Excel con 5 hojas:

1. Resumen Ejecutivo: Score de calidad y métricas principales
2. Análisis de Calidad: 7 dimensiones evaluadas
3. Estadísticas: Distribución de tipos, tamaños, relaciones
4. Sensibilidad: Campos críticos y protegidos
5. Recomendaciones: Mejoras priorizadas por impacto

---

⚡ Comandos Disponibles

# Ayuda general
scavengr --help

# Ayuda por comando
scavengr extract --help
scavengr validate --help
scavengr dictionary --help
scavengr report --help

# Versión
scavengr --version

Comando extract

scavengr extract [OPTIONS]

Opciones:
  -o, --output PATH        Archivo DBML de salida (requerido)
  --config PATH            Archivo de configuración (default: .env)
  --help                   Mostrar ayuda

Comando validate

scavengr validate [OPTIONS]

Opciones:
  -i, --input PATH         Archivo DBML a validar (requerido)
  --help                   Mostrar ayuda

Comando dictionary

scavengr dictionary [OPTIONS]

Opciones:
  -i, --input PATH         Archivo DBML de entrada (requerido)
  -o, --output PATH        Archivo de salida .xlsx (requerido)
  --help                   Mostrar ayuda

Comando report

scavengr report [OPTIONS]

Opciones:
  -i, --input PATH         Archivo DBML de entrada (requerido)
  -o, --output PATH        Archivo de salida .xlsx (requerido)
  --help                   Mostrar ayuda

---

🛡️ Seguridad y Permisos

Permisos de Base de Datos Requeridos

Scavengr necesita solo lectura en vistas del sistema:

PostgreSQL

GRANT CONNECT ON DATABASE mi_base TO usuario_scavengr;
GRANT USAGE ON SCHEMA information_schema TO usuario_scavengr;
GRANT SELECT ON ALL TABLES IN SCHEMA information_schema TO usuario_scavengr;

MySQL/MariaDB

GRANT SELECT ON information_schema.* TO 'usuario_scavengr'@'%';

SQL Server

GRANT VIEW DEFINITION TO usuario_scavengr;
-- O simplemente:
ALTER ROLE db_datareader ADD MEMBER usuario_scavengr;

🔒 Scavengr NUNCA modifica datos: Solo lee metadatos del esquema

Protección de Credenciales

# El archivo .env NO se debe versionar (está en .gitignore)
# Usa .env.example como plantilla

# Permisos recomendados (Linux/Mac):
chmod 600 .env

---

🏗️ Arquitectura

Scavengr implementa Clean Architecture con separación clara de responsabilidades:

scavengr/
├── application/          # Casos de uso (extract, validate, dictionary, report)
├── core/                 # Entidades de dominio y servicios
│   ├── entities.py       # DatabaseSchema, Table, Column, Relationship, Index
│   ├── interfaces.py     # Contratos (Scanner, Parser, Exporter)
│   └── services.py       # 10 servicios de dominio
├── infrastructure/       # Adaptadores externos
│   ├── database/         # Scanners (PostgreSQL, MySQL, MSSQL)
│   ├── parsers/          # Parser DBML
│   ├── formatters/       # Formatter DBML
│   └── exporters/        # Exportadores (Excel, JSON)
├── config/               # Gestión de configuración
├── utils/                # Utilidades transversales
└── cli.py                # Interfaz de línea de comandos

Beneficios:

• ✅ Lógica de negocio desacoplada de infraestructura
• ✅ Fácilmente testeable y extensible
• ✅ Agregar nuevos motores de BD sin modificar el core
• ✅ Cambiar formatos de salida sin afectar la lógica

---

🎯 Casos de Uso

Algunos casos de uso continuan en desarrollo y requieren extenderse para cobertura completa.

Caso 1: Documentar Base de Datos Existente

# 1. Extraer esquema
scavengr extract -o /ruta/produccion.dbml

# 2. Validar integridad
scavengr validate -i /ruta/produccion.dbml

# 3. Generar diccionario para el equipo
scavengr dictionary -i /ruta/produccion.dbml -o /ruta/diccionario-produccion.xlsx

Caso 2: Auditoría de Calidad

# 1. Extraer esquema
scavengr extract -o /ruta/auditoria.dbml

# 2. Generar reporte analítico
scavengr report -i /ruta/auditoria.dbml -o /ruta/reporte-calidad.xlsx

# 3. Revisar score de calidad y recomendaciones
# (Abrir reporte-calidad.xlsx)

Caso 3: Cumplimiento Protección de Datos

# 1. Generar diccionario con análisis de sensibilidad
scavengr dictionary -i /ruta/esquema.dbml -o /ruta/datos-sensibles.xlsx

# 2. Filtrar campos CRÍTICOS y ALTOS en Excel
# 3. Aplicar máscaras de datos sugeridas

Caso 4: Migración de Base de Datos

# 1. Extraer esquema origen
scavengr extract -o /ruta/origen.dbml

# 2. Extraer esquema destino
# El parametro --config puede presentar algunos errores
scavengr extract --config /ruta/destino.env -o /ruta/destino.dbml

# 3. Comparar manualmente (diff tool)
# 4. Validar ambos esquemas
scavengr validate -i origen.dbml
scavengr validate -i destino.dbml

---

🧪 Ejemplo de Salida

Archivo DBML Generado

Table dbo.usuarios {
  id_usuario int [pk, increment]
  nombre varchar(100) [not null]
  email varchar(255) [unique, not null]
  fecha_registro datetime [default: `getdate()`]
  id_departamento int [ref: > dbo.departamentos.id_departamento]
  
  indexes {
    email [unique, name: 'idx_usuarios_email']
    (nombre, email) [name: 'idx_usuarios_nombre_email']
  }
}

Table dbo.departamentos {
  id_departamento int [pk, increment]
  nombre varchar(100) [not null]
  descripcion text
}

Ref: dbo.usuarios.id_departamento > dbo.departamentos.id_departamento

Diccionario de Datos (Excel)

Tabla	Columna	Tipo	Sensibilidad	Descripción
usuarios	email	varchar(255)	CRÍTICO	Correo electrónico del usuario
usuarios	nombre	varchar(100)	ALTO	Nombre completo del usuario
departamentos	nombre	varchar(100)	BAJO	Nombre del departamento

---

🛠️ Requisitos del Sistema

• Python: 3.8+ (recomendado: 3.10 o superior)
• Sistema Operativo: Windows, Linux, macOS
• Memoria: Mínimo 512MB, recomendado 2GB para esquemas grandes
• Dependencias: Ver pyproject.toml para lista completa

---

🤝 Contribuciones

Las contribuciones son bienvenidas. Para cambios importantes:

1. Haz fork del repositorio
2. Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
3. Commit tus cambios (git commit -m 'Add: AmazingFeature')
4. Push a la rama (git push origin feature/AmazingFeature)
5. Abre un Pull Request

---

📝 Roadmap

v0.1.0 (Q1 2026)

• [ - ] Exportación JSON y CSV para diccionarios
• [ - ] CLI interactivo
• [ - ] API REST

---

📞 Soporte

• 🐛 Reportar Issues: GitHub Issues
• 💬 Preguntas: GitHub Discussions
• 📧 Contacto: [e-mail]

---

📄 Licencia

Licencia: MIT License - Ver LICENSE para detalles completos

Autor: Jason Rivera (@JasRockr)
Repositorio: https://github.com/JasRockr/Scavengr

---

🙏 Agradecimientos

• dbdiagram.io: Por el estándar DBML
• Python Community: Por las excelentes librerías
• Comunidad Open Source: Por inspiración y apoyo

---

✨ Hecho con Python y mucho ☕ para revelar los secretos de tus bases de datos.