Scavengr

🗃️ Scavengr

Version Python License Status PyPI version

“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

📊 Diccionarios de Datos Profesionales

✅ Validación de Esquemas DBML

📈 Reportes Analíticos

✅ Flujo de trabajo típico

1. Configuración inicial (una sola vez)

scavengr init

2. Flujo principal

scavengr extract -o schema.dbml                    # Extraer
scavengr validate -i schema.dbml                   # Validar
scavengr dictionary -i schema.dbml -o dict.xlsx    # Documentar
scavengr report -i schema.dbml -o report.xlsx      # Analizar

⚡ Instalación

Requisitos Previos

Instalación desde PyPI

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

# Instalación básica
pip install scavengr

# Verificar instalación
scavengr --version

# Configuración inicial (crea archivo .env)
scavengr init

# ¡Listo para usar!
scavengr extract -o mi-esquema.dbml

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

🚀 Configuración Rápida (Recomendado)

# Generar archivo de configuración automáticamente
scavengr init

# O crear configuración global (disponible en cualquier directorio)
scavengr init --global

🔧 Configuración Manual

# Opción 1: Crear archivo .env local (desde desarrollo)
cp .env.example .env

# Opción 2: Crear archivo .env desde cero
echo 'DB_TYPE=postgresql' > .env
echo 'DB_HOST=localhost' >> .env
echo 'DB_NAME=mi_base_datos' >> .env
echo 'DB_USER=usuario_lectura' >> .env
echo 'DB_PASSWORD=contraseña_segura' >> .env

📍 Ubicaciones de Configuración

Scavengr busca configuración en este orden de prioridad:

  1. Archivo específico: --env-file mi-config.env
  2. Directorio actual: .env.local → .env
  3. Configuración global: ~/.scavengr.env
  4. Variables del sistema: export DB_TYPE=postgresql

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:

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:

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 init --help
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)
  --env-file PATH          Archivo .env específico a usar (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 init

scavengr init [OPTIONS]

Opciones:
  --global                 Crear configuración global en directorio home
  --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:

🎯 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
scavengr extract --env-file /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

🤝 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)

📞 Soporte

📄 Licencia

Licencia: MIT License - Ver LICENSE para detalles completos

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

🙏 Agradecimientos

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

This site is open source. Improve this page.