78 lines
2.6 KiB
Markdown
78 lines
2.6 KiB
Markdown
---
|
|
name: vitruvio-criar-query
|
|
description: >
|
|
Use when the user wants to create a new named SQL query in a Vitruvio repository.
|
|
Triggers: "create query", "new query", "criar query", "nova query", "add query", "named query",
|
|
or any request to scaffold a queries/*.sql file and register it in vitruvio.json.
|
|
---
|
|
|
|
# Create Vitruvio Query
|
|
|
|
> All messages shown to the user must be written in Portuguese.
|
|
|
|
You are creating a new named SQL query inside a Vitruvio repository. Follow these steps in order.
|
|
|
|
## Step 1 — Confirm you are inside a Vitruvio repo
|
|
|
|
```bash
|
|
ls vitruvio.json 2>/dev/null && echo "OK" || echo "NOT_A_VITRUVIO_REPO"
|
|
```
|
|
|
|
If `NOT_A_VITRUVIO_REPO`, stop and tell the user to `cd` into the correct repo.
|
|
|
|
## Step 2 — Collect query details
|
|
|
|
Ask the user (in a single message, only ask what is missing from their original request):
|
|
|
|
- **Key** — kebab-case unique identifier. Used to reference this query in reports, DBTable components, and scripts.
|
|
- **Name** — human-readable label shown in the Vitruvio UI.
|
|
- **SQL** — the query itself, or enough context to write it.
|
|
- **Connection** — datasource name (default: `vitruvio_producao`). Ask only if the user mentions a specific datasource.
|
|
|
|
## Step 3 — Scaffold and create file
|
|
|
|
```bash
|
|
vitruvio new query <key> --name "<name>"
|
|
```
|
|
|
|
This creates `queries/<key>.sql` and registers it in `vitruvio.json` with `connection: "vitruvio_producao"`. Replace the generated SQL with the actual query. If a different datasource is needed, update `"connection"` in `vitruvio.json`.
|
|
|
|
Target path: `queries/<key>.sql`
|
|
|
|
Rules:
|
|
- One `SELECT` per file. No multiple statements, no DDL, no INSERT/UPDATE/DELETE.
|
|
- Named bind parameters use `:paramName` syntax — never concatenate user input into SQL.
|
|
- Write ANSI SQL where possible. If DB-specific syntax is unavoidable, note it in a comment.
|
|
- Keep Oracle and PostgreSQL compatibility in mind — avoid syntax that only works in one.
|
|
|
|
```sql
|
|
SELECT col1,
|
|
col2
|
|
FROM my_table
|
|
WHERE active = 1
|
|
AND id = :id
|
|
ORDER BY col1
|
|
```
|
|
|
|
## Step 4 — Update vitruvio.json entry
|
|
|
|
`vitruvio new` already added the query entry. The full entry shape is:
|
|
|
|
```json
|
|
{
|
|
"key": "<key>",
|
|
"name": "<name>",
|
|
"source": "queries/<key>.sql",
|
|
"connection": "vitruvio_producao"
|
|
}
|
|
```
|
|
|
|
Update `"connection"` only if the user specified a datasource other than `"vitruvio_producao"`.
|
|
|
|
## Step 5 — Report
|
|
|
|
Tell the user:
|
|
- File created: `queries/<key>.sql`
|
|
- Registered in `vitruvio.json` with key `<key>`
|
|
- How it can be used: as a datasource in a report, in a DBTable component, or loaded in a script via `db.executeNamedQuery('<key>', params)`
|