Ir al contenido

Manual do Gestor de Base de Dados em Python

Documentação técnica abrangente e código-fonte do script modular gestor_db.py projetado para a administração automatizada de arquivos SQLite na Portelcore.

0lecturas

Este projeto final detalha o design, a arquitetura e o código-fonte da nossa ferramenta interativa de terminal: gestor_db.py. Este software modular automatiza as interações SQL mais frequentes por meio de menus interativos.


O script gestor_db.py encapsula a lógica de comunicação com o motor de base de dados relacional leve, abstraindo o desenvolvedor da escrita manual de sentenças DDL, DML e DQL para tarefas recorrentes.

  1. Gerenciamento de Arquivos de Banco de Dados:
    • Inspeção dinâmica e listagem de arquivos com extensão .db, .sqlite ou .sqlite3 no subdiretório /data/.
    • Provisionamento guiado de novos contêineres relacionais vazios.
    • Exclusão segura a nível físico de bases de dados existentes sob confirmação explícita do operador de infraestrutura (portel_user).
  2. Manutenção de Estruturas (Tabelas):
    • Consulta do catálogo interno do sistema SQLite (sqlite_master) para listar tabelas ativas.
    • Criação guiada de tabelas e definição interativa de tipos de dados.
    • Destruição controlada de tabelas existentes.
  3. Administração e Consulta de Registros:
    • Formulários de console dinâmicos que leem o esquema da tabela afetada (PRAGMA table_info) para solicitar os valores correspondentes a cada coluna de forma interativa.
    • Visualizador analítico de registros formatado em uma tabela tabular no console com ajuste automático da largura das colunas de acordo com o conteúdo.

5.2. Requisitos e Estrutura Organizacional

Sección titulada «5.2. Requisitos y Estructura Organizativa»
  • Interpretador de Execução: Python versão 3.8 ou superior.
  • Dependências de Rede/Pacotes: Nenhuma. O módulo interativo sqlite3 pertence à biblioteca padrão nativa do Python.

Para garantir o funcionamento correto do endereçamento relativo dinâmico do script, mantenha a hierarquia organizacional corporativa:

portelcore_proyecto/
├── scripts/
│ └── gestor_db.py <-- Directorio de ejecución interactiva
└── data/
├── portel_ventas.db <-- Espacio seguro de persistencia de archivos SQL
└── portel_lab.db

O script resolve dinamicamente o caminho físico absoluto da pasta de armazenamento utilizando a variável de sistema do Python: os.path.join(os.path.dirname(__file__), '..', 'data').


5.3. O Código Fuente Consolidado (gestor_db.py)

Sección titulada «5.3. El Código Fuente Consolidado (gestor_db.py)»

Abaixo é apresentado o código de console completo. Foi corrigido um bug sintático latente no gerenciamento do menu de saída e a formatação visual das saídas foi otimizada:

import sqlite3
import os
import platform
# --- Configuración y Resoluciones de Rutas ---
# Ruta al subdirectorio de datos subiendo un nivel desde el directorio del script
DATA_DIR = os.path.join(os.path.dirname(__file__), '..', 'data')
def limpiar_pantalla():
"""Limpia la terminal según el sistema operativo del host."""
command = 'cls' if platform.system() == 'Windows' else 'clear'
os.system(command)
def pausar_pantalla():
"""Pausa la ejecución de la consola para lectura del operador."""
input("\nPresione Enter para continuar...")
def obtener_conexion(db_name):
"""Inicializa la conexión con el archivo físico sqlite."""
db_path = os.path.join(DATA_DIR, db_name)
try:
conn = sqlite3.connect(db_path)
# Habilitación explícita de validación de claves foráneas
conn.execute("PRAGMA foreign_keys = ON;")
return conn
except sqlite3.Error as e:
print(f"❌ Error crítico de conexión al archivo de datos: {e}")
return None
# --- Funciones Operacionales de Estructura (Tablas) ---
def listar_tablas(conn):
"""Inspecciona el catálogo de metadatos de SQLite."""
cursor = conn.cursor()
cursor.execute("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%';")
tablas = cursor.fetchall()
print("--- Tablas Activas en el Esquema ---")
if not tablas:
print("No se han detectado tablas en este archivo de datos.")
else:
for i, tabla in enumerate(tablas):
print(f" {i + 1}. {tabla[0]}")
print("-" * 36)
return [tabla[0] for tabla in tablas]
def crear_tabla(conn):
"""Crea una tabla solicitando columnas en consola."""
limpiar_pantalla()
print("--- Aprovisionamiento de Estructuras (Tablas) ---")
nombre_tabla = input("Nombre de la tabla a crear: ").strip()
if not nombre_tabla:
print("❌ El nombre de la tabla no cumple los requisitos mínimos.")
return
print("\nDefina las columnas (ej: 'id INTEGER PRIMARY KEY AUTOINCREMENT, nombre TEXT NOT NULL')")
columnas = input("Esquema de columnas: ").strip()
if not columnas:
print("❌ Debe definir al menos un campo para estructurar la tabla.")
return
try:
cursor = conn.cursor()
cursor.execute(f"CREATE TABLE IF NOT EXISTS {nombre_tabla} ({columnas});")
conn.commit()
print(f"\n✅ Estructura '{nombre_tabla}' aprovisionada con éxito en disco.")
except sqlite3.Error as e:
print(f"\n❌ Error al compilar la sentencia DDL: {e}")
def eliminar_tabla(conn):
"""Elimina permanentemente una estructura lógica del archivo."""
limpiar_pantalla()
print("--- Destrucción de Tablas ---")
tablas = listar_tablas(conn)
if not tablas:
return
try:
opcion = int(input("Seleccione el índice de la tabla a destruir: "))
if 1 <= opcion <= len(tablas):
tabla_a_borrar = tablas[opcion - 1]
confirmacion = input(f"¿Desea eliminar la tabla '{tabla_a_borrar}'? (s/n): ").lower()
if confirmacion == 's':
cursor = conn.cursor()
cursor.execute(f"DROP TABLE {tabla_a_borrar};")
conn.commit()
print(f"\n✅ Tabla '{tabla_a_borrar}' eliminada físicamente.")
else:
print("Operación cancelada de forma segura.")
else:
print("❌ Índice fuera de rango.")
except ValueError:
print("❌ Por favor, introduzca un valor numérico entero.")
except sqlite3.Error as e:
print(f"❌ Error al ejecutar DROP TABLE: {e}")
# --- Funciones Operacionales de Datos (DML y DQL) ---
def insertar_datos(conn):
"""Lee dinámicamente el esquema e inserta un nuevo registro."""
limpiar_pantalla()
print("--- Inserción de Datos ---")
tablas = listar_tablas(conn)
if not tablas:
return
try:
opcion = int(input("Seleccione la tabla destino: "))
if not (1 <= opcion <= len(tablas)):
print("❌ Índice no válido.")
return
tabla_seleccionada = tablas[opcion - 1]
cursor = conn.cursor()
cursor.execute(f"PRAGMA table_info({tabla_seleccionada});")
columnas_info = cursor.fetchall()
nombres_columnas = [col[1] for col in columnas_info]
print(f"\nInsertando datos en '{tabla_seleccionada}'. Columnas detectadas: {', '.join(nombres_columnas)}")
valores = []
for nombre_col in nombres_columnas:
valor = input(f" - Valor para campo '{nombre_col}': ")
valores.append(valor if valor != '' else None)
placeholders = ', '.join(['?' for _ in nombres_columnas])
sql = f"INSERT INTO {tabla_seleccionada} ({', '.join(nombres_columnas)}) VALUES ({placeholders})"
cursor.execute(sql, valores)
conn.commit()
print("\n✅ Registro persistido con éxito en la base de datos.")
except ValueError:
print("❌ Selección no numérica.")
except sqlite3.Error as e:
print(f"❌ Error de violación de restricciones ACID: {e}")
def ver_datos_tabla(conn):
"""Consulta de registros formateada en consola."""
limpiar_pantalla()
print("--- Visor Tabular de Registros (DQL) ---")
tablas = listar_tablas(conn)
if not tablas:
return
try:
opcion_tabla = int(input("Seleccione la tabla a consultar: "))
if not (1 <= opcion_tabla <= len(tablas)):
print("❌ Selección fuera de rango.")
return
tabla_seleccionada = tablas[opcion_tabla - 1]
cursor = conn.cursor()
cursor.execute(f"PRAGMA table_info({tabla_seleccionada});")
columnas_info = cursor.fetchall()
nombres_columnas = [col[1] for col in columnas_info]
limpiar_pantalla()
print(f"--- Columnas Disponibles en '{tabla_seleccionada}' ---")
print(" 0. * (Todas las columnas)")
for i, nombre_col in enumerate(nombres_columnas):
print(f" {i + 1}. {nombre_col}")
opciones_col_str = input("\nDefina las columnas a mostrar (separadas por comas, ej: 1,2 o 0 para todas): ")
columnas_a_mostrar = []
if opciones_col_str == '0':
columnas_a_mostrar = nombres_columnas
else:
indices = [int(i.strip()) - 1 for i in opciones_col_str.split(',')]
for idx in indices:
if 0 <= idx < len(nombres_columnas):
columnas_a_mostrar.append(nombres_columnas[idx])
if not columnas_a_mostrar:
print("❌ No se seleccionaron columnas válidas para la consulta.")
return
columnas_sql = ', '.join(f'"{c}"' for c in columnas_a_mostrar)
sql = f"SELECT {columnas_sql} FROM {tabla_seleccionada}"
cursor.execute(sql)
resultados = cursor.fetchall()
print(f"\n--- Registros Persistidos en '{tabla_seleccionada}' ---")
if not resultados:
print("La tabla seleccionada no contiene registros.")
return
# Cálculo dinámico del ancho de columnas para visualización premium
anchos = [len(col) for col in columnas_a_mostrar]
for fila in resultados:
for i, valor in enumerate(fila):
anchos[i] = max(anchos[i], len(str(valor if valor is not None else 'NULL')))
# Imprimir cabecera alineada
cabecera = " | ".join(columnas_a_mostrar[i].ljust(anchos[i]) for i in range(len(columnas_a_mostrar)))
print(cabecera)
print("-" * len(cabecera))
# Imprimir registros tabulados
for fila in resultados:
fila_formateada = " | ".join(str(fila[i] if fila[i] is not None else 'NULL').ljust(anchos[i]) for i in range(len(fila)))
print(fila_formateada)
except (ValueError, IndexError):
print("❌ Selección sintáctica no válida.")
except sqlite3.Error as e:
print(f"❌ Error al consultar la estructura en disco: {e}")
# --- Interfaces de Menús de Consola ---
def menu_gestion_db(db_name):
"""Muestra el submenú para operar sobre el contenido del archivo."""
conn = obtener_conexion(db_name)
if not conn:
pausar_pantalla()
return
while True:
limpiar_pantalla()
print(f"🗄️ Gestionando Base de Datos: [ {db_name} ]")
print("-" * 46)
listar_tablas(conn)
print("\n--- Opciones de Operación ---")
print("1. Crear una nueva tabla (DDL)")
print("2. Eliminar una tabla (DDL)")
print("3. Insertar datos interactivos (DML)")
print("4. Ver datos en visor tabular (DQL)")
print("5. Retornar al menú principal")
opcion = input(">> Opción elegida: ").strip()
if opcion == '1':
crear_tabla(conn)
pausar_pantalla()
elif opcion == '2':
eliminar_tabla(conn)
pausar_pantalla()
elif opcion == '3':
insertar_datos(conn)
pausar_pantalla()
elif opcion == '4':
ver_datos_tabla(conn)
pausar_pantalla()
elif opcion == '5':
break
else:
print("❌ Comando desconocido.")
pausar_pantalla()
conn.close()
def menu_principal():
"""Muestra el menú principal de selección de archivos en disco."""
os.makedirs(DATA_DIR, exist_ok=True)
while True:
limpiar_pantalla()
print("============== GESTOR DE BASES DE DATOS SQLITE ==============")
print("\n--- Bases de Datos Disponibles en '/data/' ---")
try:
databases = [f for f in os.listdir(DATA_DIR) if f.endswith(('.db', '.sqlite', '.sqlite3'))]
if not databases:
print("No se han detectado archivos de base de datos compatibles.")
else:
for i, db in enumerate(databases):
print(f" {i + 1}. {db}")
except FileNotFoundError:
print("El directorio de datos no existe. Creando ruta `/data`...")
os.makedirs(DATA_DIR)
databases = []
print("\n--- Opciones del Gestor ---")
print("1. Seleccionar y gestionar una Base de Datos")
print("2. Crear un archivo de Base de Datos nuevo")
print("3. Eliminar físicamente un archivo de Base de Datos")
print("4. Salir de la aplicación")
opcion_principal = input(">> Opción elegida: ").strip()
if opcion_principal == '1':
if not databases:
print("\nNo existen bases de datos activas en el subdirectorio. Cree una primero.")
pausar_pantalla()
continue
try:
opcion_db = int(input("Número de la base de datos a abrir: "))
if 1 <= opcion_db <= len(databases):
db_seleccionada = databases[opcion_db - 1]
menu_gestion_db(db_seleccionada)
else:
print("❌ Opción inválida.")
pausar_pantalla()
except ValueError:
print("❌ Introduzca un número de índice entero.")
pausar_pantalla()
elif opcion_principal == '2':
nombre_db = input("Nombre para el archivo (sin extensión): ").strip()
if nombre_db:
conn = obtener_conexion(f"{nombre_db}.db")
if conn:
conn.close()
print(f"\n✅ Archivo '{nombre_db}.db' inicializado con éxito.")
else:
print("❌ Nombre inválido.")
pausar_pantalla()
elif opcion_principal == '3':
if not databases:
print("\nNo existen archivos de datos para eliminar.")
pausar_pantalla()
continue
try:
opcion_db = int(input("Número del archivo a eliminar: "))
if 1 <= opcion_db <= len(databases):
db_a_borrar = databases[opcion_db - 1]
confirmacion = input(f"¿Confirma la destrucción total de '{db_a_borrar}'? (s/n): ").lower()
if confirmacion == 's':
os.remove(os.path.join(DATA_DIR, db_a_borrar))
print(f"\n✅ Archivo de datos '{db_a_borrar}' eliminado del disco.")
else:
print("Operación cancelada de forma segura.")
else:
print("❌ Índice inválido.")
except ValueError:
print("❌ Por favor, introduzca un número entero.")
pausar_pantalla()
elif opcion_principal == '4':
print("Cerrando sesión en el gestor. ¡Hasta luego! 👋")
break
else:
print("❌ Selección no reconocida.")
pausar_pantalla()
if __name__ == "__main__":
menu_principal()

🏁 Checklist de Qualidade do Código Python

Sección titulada «🏁 Checklist de Calidad del Código Python»

Garanta a robustez das ferramentas de automação em Python do Portelcore seguindo este checklist de validação técnica:

  • ✓ Manejo Estructurado de Excepciones: Validar que todas las consultas SQL críticas estão envueltas em bloques de controle try-except sqlite3.Error para evitar a caída inesperada de processos.
  • ✓ Liberação de Recursos (Close): Confirmar que a conexão a a base de dados se cierra sempre de forma explícita ao retornar ao menu principal para liberar descriptores de arquivos do host.
  • ✓ Injeção de Parámetros: Utilizar marcadores de posição (?) em todas as consultas parametrizadas (cursor.execute(sql, valores)) para mitigar brechas de segurança por injeção SQL.
  • ✓ Resolução de Rotas Absolutas: Usar construções baseadas em __file__ para garantir a portabilidade absoluta do script sem depender do diretório de trabalho ativo da console.