embedded-sql

Write SQL queries in ADVPL/TLPP code using BeginSQL blocks and macros.

176|37|Updated Mar 4, 2026
One-click install
npx skills add https://github.com/thalysjuvenal/advpl-specialist --skill embedded-sql
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: embedded-sql
Source: https://github.com/thalysjuvenal/advpl-specialist/tree/main/skills/embedded-sql
Command: npx skills add https://github.com/thalysjuvenal/advpl-specialist --skill embedded-sql

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps developers write SQL queries directly within ADVPL/TLPP code, replacing error-prone string concatenation with a safer, more readable, and maintainable approach using BeginSQL blocks and special macros.

Core Features & Use Cases

  • Safe SQL Querying: Use BeginSQL with macros like %table%, %xfilial%, %notDel%, and %exp% for secure and efficient data retrieval.
  • Readability & Maintainability: Write SQL in a natural, readable format, making code easier to understand and modify.
  • Use Case: When developing a Protheus report that needs to join tables SE2 (Expenses) and SA2 (Suppliers), use this Skill to construct a robust BeginSQL query that correctly handles filial filtering, logical deletions, and variable binding.

Quick Start

Use the embedded-sql skill to generate a BeginSQL block for selecting data from the SA1 table, filtering by filial and non-deleted records.

Frequently Asked Questions about embedded-sql

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

FAQPage Schema
How do I write SQL queries safely in ADVPL and TLPP code?

To write SQL queries safely in ADVPL and TLPP, use the BeginSQL construct with specialized macros like %table% and %xfilial% to replace error-prone string concatenation with secure, readable database interactions.

What is the best way to handle filial filtering and logical deletions in TOTVS Protheus SQL?

The best way to handle filial filtering and logical deletions in TOTVS Protheus is using %xfilial% and %notDel% macros within a BeginSQL block, ensuring queries correctly filter branch data and exclude logically deleted records.

How do I bind variables in a Protheus BeginSQL block?

You bind variables in a Protheus BeginSQL block using the %exp% macro, which safely injects values into your SELECT statements and prevents SQL injection vulnerabilities common in manual string concatenation.

Can I use BeginSQL to join Protheus tables like SE2 and SA2?

Yes, you can use BeginSQL to join Protheus tables like SE2 and SA2, constructing robust queries that correctly handle cross-table filial filtering, logical deletions, and safe variable binding for reporting.

Why should I use macros instead of string concatenation for embedded SQL in ADVPL?

You should use macros instead of string concatenation for embedded SQL in ADVPL because macros provide a safer, more readable, and maintainable approach to database interactions, preventing common syntax and injection errors.