> For the complete documentation index, see [llms.txt](https://docs.tunnelhub.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tunnelhub.io/produto/sql-tables.md).

# Tabelas de Apoio

Tabelas de Apoio são tabelas relacionais gerenciadas pelo TunnelHub para guardar dados operacionais que precisam ser consultados ou alterados por automações.

Use esse recurso quando o dado tem estrutura própria, chave primária, colunas tipadas e precisa ir além de um simples de/para.

## Quando usar

Tabelas de Apoio fazem sentido para cenários como:

* cache operacional compartilhado por execuções;
* controle de processamento por entidade de negócio;
* tabelas auxiliares com várias colunas;
* dados importados por CSV e consumidos por automações;
* estado de integração que precisa ser visível e administrado no produto.

Se o caso for apenas traduzir um valor de origem para um valor de destino, prefira [Tabelas De/Para](/produto/data-stores.md).

## Modelo de dados

Cada Tabela de Apoio possui:

* `externalCode`, usado por automações e SDK;
* descrição funcional;
* pacote associado;
* lista opcional de usuários limitados;
* `schemaDefinition`, com colunas e tipos;
* `primaryKey`, com uma ou mais colunas;
* `indexesDefinition`, para índices adicionais.

Tipos de coluna suportados:

* `TEXT`;
* `INTEGER`;
* `REAL`;
* `NUMERIC`;
* `BOOLEAN`;
* `DATETIME`.

Além da chave primária definida no schema, o TunnelHub mantém um `rowId` técnico para operações sobre linhas.

## Operações disponíveis

No produto, Tabelas de Apoio permitem:

* criar e editar a definição da tabela;
* listar linhas com paginação, filtros e ordenação;
* inserir, editar e remover linhas;
* importar dados por CSV;
* exportar dados por CSV;
* controlar visibilidade para usuários limitados.

Alterações de schema são tratadas pela plataforma. Mudanças destrutivas ou troca de chave primária podem exigir recriação planejada da tabela.

## Uso em automações

Para usar Tabelas de Apoio em uma automação, associe a tabela à automação no produto e habilite o runtime compatível no `tunnelhub.yml`.

Exemplo:

```yaml
configuration:
  runtimeEngine: LAMBDA
  entrypoint: index.handler
  runtime: nodejs24.x
  memorySize: 1024
  timeout: 60
  runInVpc: true
  sqlTables:
    enabled: true
```

Requisitos quando `sqlTables.enabled` é `true`:

* `runtime` deve ser `nodejs24.x`;
* `runInVpc` deve ser `true`;
* `runtimeEngine` deve ser `LAMBDA` ou `ECS_FARGATE`.

## Uso no SDK

O SDK expõe o helper `SqlTables` para operar linhas durante a execução.

Exemplo conceitual:

```ts
const sqlTables = new SqlTables(event);

const inserted = await sqlTables.insertRow('customer-cache', {
  document: '12345678900',
  name: 'Cliente exemplo',
  active: true,
});

const page = await sqlTables.queryRows('customer-cache', {
  current: 1,
  pageSize: 20,
  filter: {
    document: ['12345678900'],
  },
});

await sqlTables.updateRow('customer-cache', inserted.rowId, {
  name: 'Cliente atualizado',
});
```

O helper acessa o arquivo SQLite montado pela plataforma durante a execução. Ele não deve ser usado fora do runtime gerenciado do TunnelHub.

## Boas práticas

* escolha `externalCode` estável e orientado ao domínio;
* defina uma chave primária natural quando possível;
* modele colunas com tipos claros;
* use índices somente para consultas recorrentes;
* evite armazenar segredos ou credenciais;
* prefira Tabelas de Apoio para dados estruturados e Tabelas De/Para para mapeamentos simples.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tunnelhub.io/produto/sql-tables.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.