protheus-db-query

name: protheus-db-query description: > Habilidad para explorar y consultar la base de datos ERP TOTVS Protheus (MSSQL) usando protheus-db-cli. Activa esta skill para: sondear el diccionario de tablas (SX2), inspeccionar campos disponibles (SX3), ejecutar SELECT de solo lectura con salida CSV pipeable, y construir consultas informadas siguiendo el protocolo DSR-SQL de tres pasos. NO usar para operaciones de escritura: DML/DDL es bloqueado con exit 40.

Skill: protheus-db-query

Cuándo Activar

Usa esta skill cuando necesites:

• Explorar qué tablas existen en una instancia de Protheus (diccionario SX2)
• Entender qué campos tiene una tabla antes de consultarla (diccionario SX3)
• Ejecutar consultas SELECT sobre datos transaccionales de Protheus
• Encadenar resultados CSV con herramientas Unix para filtrar antes de leer al contexto

No activar para: INSERT, UPDATE, DELETE, DROP — serán rechazados con exit 40.

Variables de Entorno Requeridas

MSSQL_HOST=servidor.empresa.local   # Host o IP del SQL Server
MSSQL_PORT=1433                     # Puerto TCP (default: 1433)
MSSQL_USER=usuario_readonly         # Usuario de solo lectura
MSSQL_PASSWORD=contraseña_segura    # Contraseña
MSSQL_DATABASE=PROTHEUS_PRD         # Base de datos Protheus

Alternativamente, provee cada valor con el flag correspondiente (--host, --user, etc.).

Protocolo Obligatorio: DSR-SQL (3 Pasos)

REGLA ABSOLUTA: Nunca ejecutes data query sin completar primero los pasos 1 y 2. Los campos de Protheus son crípticos. Asumir su nombre genera queries que fallan.

Paso 1 — Validar que la tabla existe (schema probe)

# Sondear el diccionario SX2: confirma existencia y nombre descriptivo
protheus-db-cli schema probe --table SA1 2>/dev/null

Salida esperada (CSV):

X2_CHAVE,X2_NOME,X2_NOMESPA,X2_ARQUIVO
SA1,Clientes,Clientes,SA1010

Interpreta: X2_CHAVE = alias, X2_NOME = nombre en portugués, X2_ARQUIVO = tabla física.

Paso 2 — Inspeccionar campos disponibles (schema fields)

# Inspeccionar el diccionario SX3: campos, tipos y descripciones
protheus-db-cli schema fields --table SA1 2>/dev/null

Salida esperada (CSV, primeras filas):

X3_CAMPO,X3_TITULO,X3_TIPO,X3_TAMANHO,X3_DESCRIC
A1_FILIAL,Filial,C,2,Filial do Sistema
A1_COD,Codigo,C,6,Codigo do Cliente
A1_NOME,Nome,C,40,Nome do Cliente
A1_CGC,CGC/CPF,C,14,CGC ou CPF do Cliente

Tipos: C=Char, N=Numérico, D=Fecha, M=Memo (texto largo).

Paso 3 — Ejecutar query informada (data query)

# Ahora construyes el SELECT con campos que SX3 confirmó que existen
protheus-db-cli data query \
  --sql "SELECT A1_COD, A1_NOME, A1_CGC FROM SA1010 WHERE D_E_L_E_T_ <> '*'" \
  2>/dev/null

⚠️ SIEMPRE incluir WHERE D_E_L_E_T_ <> '*'. Protheus usa eliminación lógica: los registros eliminados permanecen en la tabla marcados con * en el campo D_E_L_E_T_. Sin este filtro, los resultados son incorrectos.

Dual Stream Policy — Cómo Procesar la Salida

stdout → CSV puro (datos, para parsing)
stderr → logs de diagnóstico (ignorar en pipelines)

Suprimir stderr en pipelines:

# Linux/Mac
protheus-db-cli data query --sql "..." 2>/dev/null

# PowerShell
protheus-db-cli data query --sql "..." 2>$null

Leer solo los datos (sin logs al contexto): Siempre redirige stderr a /dev/null antes de pasar stdout al agente. Los logs de stderr son para humanos — cargarlos al contexto desperdicia tokens.

Técnicas de Filtrado con Pipes Unix

El CSV de stdout es pipeable. Usa estas técnicas para reducir tokens antes de leer al contexto:

grep — Filtrar filas que contienen un patrón

# Buscar solo campos cuyo nombre contenga "NOME" o "COD"
protheus-db-cli schema fields --table SA1 2>/dev/null | grep -i "nome\|cod"

# Buscar tablas de pedidos en el diccionario
protheus-db-cli schema probe --table "SC%" --top 15 2>/dev/null | grep -i "pedido\|order"

awk — Extraer columnas específicas del CSV

# Extraer solo la columna 2 (nombre del cliente), excluyendo header
protheus-db-cli data query \
  --sql "SELECT A1_COD, A1_NOME FROM SA1010 WHERE D_E_L_E_T_<>'*'" \
  2>/dev/null | awk -F',' 'NR>1 {print $2}'

# Extraer código y nombre, reformateando con separador distinto
protheus-db-cli data query \
  --sql "SELECT A1_COD, A1_NOME, A1_CGC FROM SA1010 WHERE D_E_L_E_T_<>'*'" \
  2>/dev/null | awk -F',' 'NR>1 {print $1 " → " $2}'

wc -l — Contar registros rápidamente

# Contar proveedores activos (restar 1 por el header)
protheus-db-cli data query \
  --sql "SELECT A2_COD FROM SA2010 WHERE D_E_L_E_T_<>'*'" \
  2>/dev/null | tail -n +2 | wc -l

tail — Saltar el header CSV

# Procesar solo los datos (sin la fila de headers)
protheus-db-cli data query --sql "SELECT A1_COD FROM SA1010" \
  2>/dev/null | tail -n +2

PowerShell — Convertir CSV a objetos

# Obtener objetos con propiedades nombradas por el header
$clientes = protheus-db-cli data query `
  --sql "SELECT A1_COD, A1_NOME FROM SA1010 WHERE D_E_L_E_T_<>'*'" `
  2>$null | ConvertFrom-Csv

# Acceder por nombre de columna
$clientes | Where-Object { $_.A1_NOME -like "*ABC*" }

Referencia de Exit Codes

Ejemplos de Flujo Completo

Ejemplo A: Explorar y consultar clientes

# Paso 1: confirmar tabla
protheus-db-cli schema probe --table SA1 2>/dev/null
# → CSV: SA1,Clientes,...

# Paso 2: ver campos disponibles, filtrar los relevantes
protheus-db-cli schema fields --table SA1 2>/dev/null | grep -i "cod\|nome\|cgc\|tipo"
# → X3_CAMPO,X3_TITULO,...
# → A1_COD,Codigo,...
# → A1_NOME,Nome,...

# Paso 3: query informada con solo los campos confirmados
protheus-db-cli data query \
  --sql "SELECT A1_COD, A1_NOME, A1_CGC FROM SA1010 WHERE D_E_L_E_T_<>'*'" \
  --top 20 2>/dev/null

Ejemplo B: Buscar facturas de salida del mes

# Paso 1
protheus-db-cli schema probe --table SF2 2>/dev/null

# Paso 2: ¿qué campo tiene la fecha de emisión?
protheus-db-cli schema fields --table SF2 2>/dev/null | grep -i "data\|fecha\|emiss"

# Paso 3: query filtrada por fecha y sin registros eliminados
protheus-db-cli data query \
  --sql "SELECT F2_DOC, F2_SERIE, F2_EMISSAO, F2_VALBRUT FROM SF2010 \
         WHERE D_E_L_E_T_<>'*' AND F2_EMISSAO >= '20260301'" \
  --top 50 2>/dev/null

Ejemplo C: Conteo rápido de productos activos

protheus-db-cli data query \
  --sql "SELECT B1_COD FROM SB1010 WHERE D_E_L_E_T_<>'*'" \
  2>/dev/null | tail -n +2 | wc -l

Tablas de Referencia Rápida

El sufijo 010 = empresa 01 + filial 0. Puede variar en otras instancias. Siempre verificar el nombre físico real con schema probe antes de asumir.