Skill de Operaciones Generales sobre Base de Datos DMS
Conéctate a Alibaba Cloud DMS (MySQL) para consultar y ejecutar operaciones sobre bases de datos, con cortafuegos de seguridad integrado. Soporta sobrescritura de la base de datos por defecto, comandos rápidos y exportación en múltiples formatos.
Principios de Seguridad Fundamentales (Obligatorios)
- Solo lectura por defecto: Sin la bandera
--writesolo se ejecutan sentenciasSELECT / SHOW / DESCRIBE / EXPLAIN / WITH / USE. El script intercepta automáticamente cualquier operación de escritura y termina. - Las operaciones de escritura requieren doble confirmación: Incluso si el usuario solicita explícitamente modificar/eliminar datos, se debe seguir el proceso de cuatro pasos: "vista previa -> mostrar impacto -> confirmación del usuario -> ejecución". No se puede saltar.
- No realizar modificaciones más allá de la intención del usuario: Si el usuario solo pide "consultar", nunca se debe "modificar". Si el usuario pide "modificar A", no se debe modificar también "B".
- Una sola cosa a la vez: Cada operación de escritura se previsualiza y confirma de forma independiente. No se ejecutan múltiples sentencias de escritura sin confirmación individual.
Scripts
{SKILL_DIR} = ~/.codex/skills/dms-query/scripts. Script principal: dms_exec.py.
Comandos Rápidos
# Listar todas las bases de datos
python3 {SKILL_DIR}/dms_exec.py --databases
# Listar las tablas de una base de datos específica (si no se pasa nombre de BD, usa DMS_DB)
python3 {SKILL_DIR}/dms_exec.py --tables # Usa la BD por defecto DMS_DB
python3 {SKILL_DIR}/dms_exec.py --tables shop # Base de datos específica
# Ver estructura de una tabla
python3 {SKILL_DIR}/dms_exec.py --describe mydb.users
python3 {SKILL_DIR}/dms_exec.py --db shop --describe products
Tres formas de leer SQL
# 1. Pasar directamente en la línea de comandos
python3 {SKILL_DIR}/dms_exec.py --sql "SELECT * FROM mydb.users LIMIT 5"
# 2. Leer desde un archivo
python3 {SKILL_DIR}/dms_exec.py --file /path/to/query.sql
# 3. Leer desde stdin
echo "SHOW DATABASES" | python3 {SKILL_DIR}/dms_exec.py
Sobrescribir la base de datos por defecto
Por defecto se conecta a la base de datos especificada en la variable de entorno DMS_DB. Usa --db para sobrescribirla temporalmente sin afectar otras terminales:
python3 {SKILL_DIR}/dms_exec.py --db shop --sql "SELECT id, name FROM products LIMIT 10"
python3 {SKILL_DIR}/dms_exec.py --db mydb --tables
Exportar resultados
# Exportar a xlsx
python3 {SKILL_DIR}/dms_exec.py --sql "SELECT ..." -o result.xlsx
# Exportar a csv
python3 {SKILL_DIR}/dms_exec.py --sql "SELECT ..." -o result.csv
# Exportar a json (formato array de objetos)
python3 {SKILL_DIR}/dms_exec.py --sql "SELECT ..." -o result.json
# Salida TSV raw (apto para tuberías, no exporta archivo)
python3 {SKILL_DIR}/dms_exec.py --sql "SELECT ..." --raw
--display-rows N (por defecto 200) controla el número de filas mostradas en la terminal. Al exportar a archivo no hay límite.
Consultar datos (solo lectura)
# Ver todas las bases de datos
python3 {SKILL_DIR}/dms_exec.py --databases
# Ver las tablas de una base de datos
python3 {SKILL_DIR}/dms_exec.py --tables mydb
# Ver estructura de una tabla
python3 {SKILL_DIR}/dms_exec.py --describe mydb.users
# Consultar datos
python3 {SKILL_DIR}/dms_exec.py --sql "SELECT id, name, email FROM mydb.users LIMIT 10"
# Ver la sentencia CREATE TABLE
python3 {SKILL_DIR}/dms_exec.py --sql "SHOW CREATE TABLE mydb.users"
# Consulta entre bases de datos (usa el nombre completo db.tabla en SQL, no necesita --db)
python3 {SKILL_DIR}/dms_exec.py --sql "SELECT c.name, COUNT(*) FROM mydb.users u LEFT JOIN shop.companies c ON u.company_id = c.id GROUP BY c.name"
Al consultar grandes volúmenes de datos, añade
LIMITen la SQL. Si necesitas exportar todo, usa-o file.xlsx.
Manejo de errores en tiempo de ejecución
El script incluye mensajes de error amigables. Ante una ejecución fallida, interpreta la salida y guía al usuario:
| Síntoma del error | Causa | Acción |
|---|---|---|
Can't connect to MySQL server ... (timed out) | VPN no conectada | Recordar al usuario: "DMS es una dirección de intranet; conecta la VPN de la empresa y vuelve a intentar." |
Falta el módulo pymysql | Dependencia no instalada | Indicar ejecutar pip3 install pymysql -i https://pypi.tuna.tsinghua.edu.cn/simple |
Falta la variable de entorno DMS_* | Parámetros de conexión no configurados | Recordar al usuario configurar las variables de entorno DMS en ~/.zshenv y luego abrir una nueva terminal. |
Operación de escritura rechazada | Falta la bandera --write | Intercepción normal. Seguir el flujo de confirmación de escritura. |
La salida del script ya incluye sugerencias para la resolución. Puedes transmitirlas directamente al usuario. No es necesario adivinar la causa.
Flujo de confirmación de operaciones de escritura (Obligatorio, no se puede saltar)
Cuando el usuario solicite explícitamente modificar/eliminar/crear datos, debes seguir estos cuatro pasos:
Paso 1 - Generar vista previa (dry-run)
python3 {SKILL_DIR}/dms_exec.py --sql "<SQL de escritura>" --write
Por defecto el script ejecuta dry-run: para DML ejecuta la transacción y luego hace ROLLBACK para obtener el número exacto de filas afectadas, y ejecuta un SELECT para previsualizar las filas afectadas; para INSERT muestra la tabla destino, columnas y valores; para DDL da una explicación del impacto. No modifica datos realmente.
Paso 2 - Mostrar al usuario el alcance del impacto
Basándote en la salida de la vista previa, explica claramente al usuario en español:
- Tipo de operación: INSERT / UPDATE / DELETE / DDL (cuál exactamente)
- Tabla destino: Nombre(s) de la(s) tabla(s) afectada(s)
- Número de filas afectadas: Cuántas filas se modificarán/eliminarán/insertarán
- Cambios específicos:
- UPDATE: qué campos cambian de qué valor a qué valor (mostrar filas de vista previa)
- DELETE: qué filas se eliminarán (mostrar filas de vista previa)
- INSERT: qué datos se insertarán (mostrar columnas y valores)
- DDL: contenido específico del cambio estructural
- Si es reversible: DROP/TRUNCATE no son reversibles, hay que enfatizarlo especialmente
- Advertencia sin WHERE: Si UPDATE/DELETE no tiene cláusula WHERE, se debe enfatizar que "afectará a toda la tabla"
Paso 3 - Esperar confirmación explícita del usuario
El usuario debe responder con un sentido afirmativo ("confirmo" / "ejecuta" / "está bien" etc.). No se debe asumir que "el usuario estaría de acuerdo" y saltarse este paso. Si el usuario duda o pide cambios, vuelve al Paso 1 para una nueva vista previa.
Paso 4 - Ejecutar
python3 {SKILL_DIR}/dms_exec.py --sql "<SQL de escritura>" --write --confirm
Tras la ejecución, informa del número de filas afectadas.
Ejemplo del flujo
El usuario dice: "Actualiza el campo feedback de los registros en la tabla users donde feedback_type sea 2 a 'procesado'"
# Paso 1: Vista previa
python3 {SKILL_DIR}/dms_exec.py \
--sql "UPDATE mydb.users SET feedback = 'procesado' WHERE feedback_type = 2" \
--write
# Paso 2: Mostrar resultado de la vista previa al usuario (número de filas afectadas, filas de vista previa, irreversibilidad)
# Paso 3: Esperar confirmación del usuario
# Paso 4: Tras confirmación, ejecutar
python3 {SKILL_DIR}/dms_exec.py \
--sql "UPDATE mydb.users SET feedback = 'procesado' WHERE feedback_type = 2" \
--write --confirm
Resumen de parámetros
| Parámetro | Descripción |
|---|---|
--sql "..." | Pasar SQL directamente |
--file / -f RUTA | Leer SQL desde un archivo |
--db NOMBRE | Sobrescribir el nombre de la base de datos por defecto (DMS_DB) |
--databases | Listar todas las bases de datos |
--tables [BD] | Listar tablas (nombre de BD opcional) |
--describe TABLA | Ver estructura de una tabla |
-o ARCHIVO | Exportar a xlsx/csv/json |
--raw | Salida TSV raw |
--display-rows N | Filas mostradas en terminal (por defecto 200) |
--timeout N | Tiempo de espera de conexión en segundos (por defecto 15) |
--write | Permitir operaciones de escritura |
--confirm | Confirmar ejecución de operación de escritura (requiere --write) |
Al finalizar
- Operaciones de consulta: Informa del número de filas y un resumen de los datos clave (o la ruta del archivo exportado).
- Operaciones de escritura: Informa del número de filas afectadas y el resultado de la operación.