Nexttag.Data.Sql 1.0.0

Nexttag.Data.Sql

Transforma perguntas em linguagem natural em consultas SQL seguras (NL→SQL via LLM) com guarda de segurança multicamadas e abstrações read-only agnósticas de engine.

Instalar

dotnet add package Nexttag.Data.Sql

Requer .NET 10.

Registrar (Program.cs)

Esta lib não tem extensão de DI própria — instancie NlToSql e use SqlGuard diretamente. A implementação de engine (Nexttag.Data.Sql.Postgres) provê as implementações de ISqlSchemaReader e ISqlExecutor.

// Registro manual (sem provider de banco ainda)
builder.Services.AddSingleton<NlToSql>(sp =>
    new NlToSql(sp.GetRequiredService<IChatClient>()));

Configurar

Sem configuração obrigatória na lib base. O IChatClient (Microsoft.Extensions.AI) deve apontar para o LiteLLM ou qualquer gateway OpenAI-compatível.

// appsettings.json — configuração do LLM (ex.: litellm)
{
  "LiteLlm": {
    "Endpoint": "http://localhost:4000/v1",
    "ApiKey": "<sua-virtual-key>",
    "AnalystModel": "qwen3:32b"
  }
}

Usar

Peças principais

Fluxo completo (propor → validar → executar)

// 1. Define a allowlist (tabelas que o bot pode ler)
var allow = new[] {
    new TableRef("public", "pedidos"),
    new TableRef("public", "clientes")
};

// 2. Lê o schema das tabelas liberadas (impl: PgSqlSchemaReader)
var schema = await schemaReader.ReadAsync(allow, ct);

// 3. LLM propõe a consulta — NÃO executa
var proposta = await nlToSql.GenerateAsync(
    "quanto faturamos em maio?", schema, dialect: "PostgreSQL", ct);
// proposta.Sql — SELECT gerado; proposta.Explanation — texto explicativo

// 4. Guard valida (+ revisão humana antes de aprovar)
var veredito = SqlGuard.Validate(proposta.Sql, allow, maxRows: 1000);
if (!veredito.Allowed)
    throw new InvalidOperationException(veredito.Reason);

// 5. Executa read-only (impl: PgSqlExecutor)
var resultado = await executor.ExecuteAsync(veredito.Sql, maxRows: 1000, timeoutSeconds: 15, ct);
// resultado.Columns — nomes das colunas
// resultado.Rows    — List<IReadOnlyList<object?>>
// resultado.RowCount

Formatar schema para prompt manual

string textoSchema = SqlSchemaFormatter.Format(schema);

Receitas

Testar a conexão antes de expor ao usuário

await executor.TestConnectionAsync(ct); // lança se falhar

Bloquear e relatar SQL inválido

var r = SqlGuard.Validate(sqlDoUsuario, allow);
if (!r.Allowed)
    return Results.Problem(r.Reason, statusCode: 422);
var resultado = await executor.ExecuteAsync(r.Sql);

Limitar tabelas visíveis por tenant

// Cada tenant tem sua própria allowlist carregada do banco
var allow = await db.DatasourceTables
    .Where(t => t.DatasourceId == tenantId && t.Enabled)
    .Select(t => new TableRef(t.SchemaName, t.TableName))
    .ToListAsync(ct);

Notas

• NlToSql só propõe — o host é responsável por revisar antes de executar.
• SqlGuard bloqueia DDL/DML, multi-statement, tabelas fora da allowlist e injeta LIMIT. Mesmo assim, use sempre usuário read-only no banco.
• CTEs (WITH x AS (...)) são reconhecidas como tabelas virtuais — não precisam estar na allowlist.
• O guard recusa SQL vazio, sem SELECT/WITH no início, ou com palavras como insert, update, drop, set, etc.
• Provider de banco obrigatório: Nexttag.Data.Sql.Postgres.