query-builder

Build parameterized SQL queries for Protheus ERP tables with soft-delete and branch filters.

115|54|Updated May 25, 2026
One-click install
npx skills add https://github.com/totvs/engpro-advpl-tlpp-skills --skill query-builder-totvs
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: query-builder
Source: https://github.com/totvs/engpro-advpl-tlpp-skills/tree/main/skills/advpl-tlpp/query-builder
Command: npx skills add https://github.com/totvs/engpro-advpl-tlpp-skills --skill query-builder-totvs

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill prevents incorrect or unsafe SQL for Protheus by enforcing mandatory filters, branch scoping, and parameter binding while helping you choose the best access pattern for performance.

Core Features & Use Cases

  • Mandatory Protheus Conventions: Always includes D_E_L_E_T_ = ' ' and the required XX_FILIAL branch filter, and uses RetSQLName() for physical table correctness.
  • Optimized Query Patterns: Produces Workarea (DbSelectArea/DbSeek) or Embedded SQL (FWExecStatement with prepared bind parameters) versions and supports JOINs, DML, and COUNT.
  • Safety Guardrails: Guides parameterized query construction to reduce SQL injection risk and avoids common Protheus pitfalls (missing soft-delete, hardcoded filial, SELECT *, missing index-aligned WHERE ordering).

Quick Start

Tell the AI: Build a parameterized FWExecStatement query for the Protheus table SA1 that returns customer code and name for the current branch while excluding deleted records, and include the recommended index-aware WHERE clause.

Frequently Asked Questions about query-builder

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write safe Protheus SQL queries with FWExecStatement in AdvPL?

Safe Protheus SQL queries with FWExecStatement require parameter binding to prevent SQL injection and ChangeQuery compatibility. You must use prepared bind parameters for all dynamic values and enforce D_E_L_E_T_ and branch filters.

How do I prevent SQL injection in Protheus Embedded SQL?

To prevent SQL injection in Protheus Embedded SQL, use parameterized query construction with prepared bind parameters via FWExecStatement instead of string concatenation. This approach ensures user inputs are treated strictly as data values.

Why are my Protheus SQL queries missing deleted records or returning wrong branches?

Protheus SQL queries miss records or return wrong branches by omitting mandatory D_E_L_E_T_ = ' ' and XX_FILIAL branch filters. Always include these filters in your WHERE clause and use RetSQLName() for physical table naming.

What is the best way to optimize Protheus SQL queries for performance?

To optimize Protheus SQL queries, align your WHERE clause ordering with SIX index structures and choose between Workarea DbSeek access or FWExecStatement based on whether you need joins, aggregations, or record counting.

Does this approach support complex JOINs and DML operations in TLPP?

Yes, this approach supports complex JOINs, aggregations, inserts, updates, and record counting in TLPP. It ensures proper alias and area handling while generating parameterized FWExecStatement queries or Workarea DbSeek patterns.

When should I use DbSeek instead of FWExecStatement for Protheus table access?

Use DbSeek for simple Workarea access aligned to SIX indexes, and use FWExecStatement for complex Protheus SQL requiring JOINs, aggregations, inserts, updates, or record counting. Both require correct alias and area handling.