Manuel du gestionnaire de base de données en Python
Documentation technique complète et code source du script modulaire gestor_db.py conçu pour l'administration automatisée des fichiers SQLite chez Portelcore.
Ce canevas final détaille la conception, l'architecture et le code source de notre outil interactif pour terminal : gestor_db.py. Ce logiciel modulaire automatise les interactions SQL les plus fréquentes via des menus interactifs.
5.1. Architecture et capacités du script
Sección titulada «5.1. Arquitectura y Capacidades del Script»Le script gestor_db.py encapsule la logique de communication avec le moteur de base de données relationnelle légère, évitant au développeur l'écriture manuelle des instructions DDL, DML et DQL pour les tâches récurrentes.
Fonctionnalités intégrées :
Sección titulada «Funcionalidades Integradas:»- Gestion des Fichiers de Base de Données :
- Inspection dynamique et listage des fichiers avec l'extension
.db,.sqliteou.sqlite3dans le sous-répertoire/data/. - Approvisionnement guidé de nouveaux conteneurs relationnels vides.
- Suppression physique sécurisée des bases de données existantes sous confirmation explicite de l'opérateur d'infrastructure (
portel_user).
- Inspection dynamique et listage des fichiers avec l'extension
- Maintenance des Structures (Tables) :
- Consultation du catalogue interne du système SQLite (
sqlite_master) pour lister les tables actives. - Création guidée de tables et définition interactive des types de données.
- Destruction contrôlée des tables existantes.
- Consultation du catalogue interne du système SQLite (
- Administration et Consultation des Enregistrements :
- Formulaires de console dynamiques qui lisent le schéma de la table affectée (
PRAGMA table_info) pour demander les valeurs correspondantes à chaque colonne de manière interactive. - Visionneuse analytique d'enregistrements formatée dans un tableau tabulaire en console avec ajustement automatique de la largeur des colonnes selon le contenu.
- Formulaires de console dynamiques qui lisent le schéma de la table affectée (
5.2. Prérequis et structure organisationnelle
Sección titulada «5.2. Requisitos y Estructura Organizativa»Prérequis système :
Sección titulada «Requisitos del Sistema:»- Interpréteur d'exécution : Python version 3.8 ou supérieure.
- Dépendances réseau/paquets : Aucune. Le module interactif
sqlite3fait partie de la bibliothèque standard native de Python.
Structure de répertoires obligatoire :
Sección titulada «Estructura de Directorios Mandatoria:»Pour assurer le bon fonctionnement de l'adressage relatif dynamique du script, maintenez la hiérarchie organisationnelle de l'entreprise :
portelcore_proyecto/├── scripts/│ └── gestor_db.py <-- Directorio de ejecución interactiva└── data/ ├── portel_ventas.db <-- Espacio seguro de persistencia de archivos SQL └── portel_lab.dbLe script résout dynamiquement le chemin physique absolu du dossier de stockage en utilisant la variable système de Python : os.path.join(os.path.dirname(__file__), '..', 'data').
5.3. Le code source consolidé (gestor_db.py)
Sección titulada «5.3. El Código Fuente Consolidado (gestor_db.py)»Ci-dessous est présenté le code de console complet. Un bug syntaxique latent dans la gestion du menu de sortie a été corrigé et le formatage visuel des sorties a été optimisé :
import sqlite3import osimport platform
# --- Configuración y Resoluciones de Rutas ---
# Ruta al subdirectorio de datos subiendo un nivel desde el directorio del scriptDATA_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()🏁 Liste de contrôle de la qualité du code Python
Sección titulada «🏁 Checklist de Calidad del Código Python»Assurez la robustesse des outils d'automatisation en Python de Portelcore en suivant cette liste de contrôle de validation technique :
- ✓ Gestion structurée des exceptions : Valider que toutes les requêtes SQL critiques sont enveloppées dans des blocs de contrôle
try-except sqlite3.Errorpour éviter l'arrêt inattendu des processus. - ✓ Libération des ressources (Close) : Confirmer que la connexion à la base de données est toujours fermée explicitement lors du retour au menu principal afin de libérer les descripteurs de fichiers de l'hôte.
- ✓ Injection de paramètres : Utiliser des marqueurs de position (
?) dans toutes les requêtes paramétrées (cursor.execute(sql, valores)) pour atténuer les failles de sécurité par injection SQL. - ✓ Résolution des Chemins Absolus : Utiliser des constructions basées sur
__file__pour garantir la portabilité absolue du script sans dépendre du répertoire de travail actif de la console.

