> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Como Expor Tabelas do MySQL como uma API REST

> Como servir tabelas do MySQL por HTTP com a extensão vsql_rest do VillageSQL — filtros, seleção de colunas, paginação, métodos por tabela e os padrões que você precisa mudar primeiro.

> [card] [VillageSQL is a drop-in replacement for MySQL with extensions.](https://villagesql.com/docs/en/8.4/stable/install-server.md)
>
> All examples on this page work on VillageSQL. Install Now →

> [!NOTE]
>
> Este guia usa uma capability Preview. Inicie o servidor com
> `--vsql_allow_preview_extensions=ON`, ou o `INSTALL EXTENSION` é recusado.

Colocar um endpoint JSON somente leitura na frente de algumas tabelas geralmente significa escrever um serviço pequeno, implantá-lo, dar a ele uma conta de banco de dados e mantê-lo vivo. A extensão `vsql_rest` do VillageSQL serve essas tabelas de dentro do processo do servidor, então não há um segundo processo nem uma implantação nova.

Os padrões foram feitos para uma máquina de desenvolvedor, não para uma rede. Leia "Antes de expor a porta" abaixo antes de abri-la para qualquer coisa.

## Ligando

```sql theme={null}
INSTALL EXTENSION vsql_rest;
```

Crie o banco de dados e as suas tabelas primeiro. O listener lê o layout do banco de dados quando inicia e o guarda em cache por `vsql_rest.schema_ttl` segundos, 60 por padrão, então uma tabela criada depois responde `table not found` até esse cache expirar.

```sql theme={null}
CREATE DATABASE shop;
USE shop;

CREATE TABLE products (
    id       INT PRIMARY KEY,
    name     VARCHAR(40),
    category VARCHAR(20),
    price    DECIMAL(8,2),
    in_stock INT
);

INSERT INTO products VALUES
    (1, 'Budget Widget',   'widget', 29.99, 120),
    (2, 'Standard Widget', 'widget', 79.99,  40),
    (3, 'Premium Widget',  'widget', 149.99,  4),
    (4, 'Cable, 2m',       'cable',   9.99, 500),
    (5, 'Cable, 5m',       'cable',  14.99,   0);
```

Depois, informe o banco de dados, informe as tabelas que você está disposto a servir e inicie o listener:

```sql theme={null}
SET GLOBAL vsql_rest.schema = 'shop';
SET GLOBAL vsql_rest.allowed_tables = 'products';
SET GLOBAL vsql_rest.vsql_rest_enabled = ON;
```

## Lendo

Uma tabela é um caminho, e a query string faz a filtragem. Cada filtro é `coluna=operador.valor`:

```bash theme={null}
curl 'http://127.0.0.1:3000/products?category=eq.widget&order=price.desc&limit=2'
```

```json theme={null}
[{"id":3,"name":"Premium Widget","category":"widget","price":"149.99","in_stock":4},{"id":2,"name":"Standard Widget","category":"widget","price":"79.99","in_stock":40}]
```

Peça as colunas que você quer, e nada mais:

```bash theme={null}
curl 'http://127.0.0.1:3000/products?select=name,price&in_stock=eq.0'
```

```json theme={null}
[{"name":"Cable, 5m","price":"14.99"}]
```

Combine condições com `or=(...)`:

```bash theme={null}
curl 'http://127.0.0.1:3000/products?or=(category.eq.cable,price.gt.100)&select=id,name'
```

```json theme={null}
[{"id":3,"name":"Premium Widget"},{"id":4,"name":"Cable, 2m"},{"id":5,"name":"Cable, 5m"}]
```

Pagine com `limit` e `offset`:

```bash theme={null}
curl 'http://127.0.0.1:3000/products?order=id.asc&limit=2&offset=2'
```

```json theme={null}
[{"id":3,"name":"Premium Widget","category":"widget","price":"149.99","in_stock":4},{"id":4,"name":"Cable, 2m","category":"cable","price":"9.99","in_stock":500}]
```

Os operadores são `eq`, `neq`, `lt`, `lte`, `gt`, `gte`, `like`, `cs_like`, `in` e `is`. `in` recebe uma lista, como em `?id=in.(1,3)`, e `is` recebe null, como em `?price=is.null` ou `?price=is.not.null`. Uma requisição sem `limit` retorna no máximo `vsql_rest.max_rows` linhas, que começa em 1000.

## A allowlist

Uma tabela que não está em `allowed_tables` não existe para a API:

```bash theme={null}
curl 'http://127.0.0.1:3000/orders'
```

```json theme={null}
{"message":"table not found: orders","details":null,"hint":null,"code":"VSQL0001"}
```

A resposta é 404, e ela é igual quer a tabela não exista, quer apenas não tenha sido liberada.

> [!WARNING]
>
> Deixar `allowed_tables` vazio não significa nenhuma tabela. Significa **todas**
> elas. Defina-o com as tabelas que você pretende publicar antes de habilitar o
> listener.

## Restringindo métodos por tabela

`table_methods` diz quais métodos HTTP cada tabela aceita, como `tabela:MÉTODO,MÉTODO` com um `|` entre as tabelas:

```sql theme={null}
SET GLOBAL vsql_rest.table_methods = 'products:GET';
```

Por padrão, toda tabela aceita todos os métodos, então defina isso antes de o listener iniciar. Um método que a tabela não concede é recusado:

```json theme={null}
{"message":"method not allowed: POST","details":null,"hint":null,"code":"VSQL0001"}
```

Conceder gravações é a mesma configuração:

```sql theme={null}
SET GLOBAL vsql_rest.table_methods = 'products:GET,POST';
```

```bash theme={null}
curl -X POST -H 'Content-Type: application/json' \
     -d '{"id":6,"name":"Cable, 10m","category":"cable","price":19.99,"in_stock":10}' \
     'http://127.0.0.1:3000/products'
```

Uma inserção bem-sucedida responde 201 com um corpo vazio. Uma chave duplicada volta como 409:

```json theme={null}
{"message":"Duplicate entry '6' for key 'products.PRIMARY'","details":null,"hint":null,"code":"VSQL0001"}
```

## Observando o funcionamento

Cinco contadores de status reportam sobre o listener, incluindo a porta que ele de fato vinculou:

```sql theme={null}
SHOW STATUS LIKE 'vsql_rest%';
```

```
+-----------------------------+-------+
| Variable_name               | Value |
+-----------------------------+-------+
| vsql_rest.connections_total | 0     |
| vsql_rest.http_port         | 3000  |
| vsql_rest.https_port        | 0     |
| vsql_rest.requests_active   | 0     |
| vsql_rest.requests_total    | 16    |
+-----------------------------+-------+
```

`http_port` mostra 0 quando nada está escutando, que é a forma mais rápida de saber se o listener iniciou. Definir `vsql_rest.port` como 0 pede ao sistema operacional que escolha uma porta, e esse contador é onde você lê qual porta ele escolheu.

## Antes de expor a porta

Os padrões deixam o acesso aberto, e cada um deles é razoável isoladamente.

`require_auth` começa em `OFF`, então nenhuma requisição carrega ou precisa de um token. Um `allowed_tables` vazio publica o schema inteiro. Um `table_methods` vazio permite todos os métodos, incluindo `DELETE`, e um `DELETE` contra um listener nesse estado tem sucesso:

```bash theme={null}
curl -X DELETE 'http://127.0.0.1:3000/products?id=eq.6'
```

Ele responde 204, e a linha se foi.

Somando tudo, um listener ligado sem nada mais configurado permite que qualquer pessoa que alcance a porta leia, insira, atualize e exclua todas as tabelas do schema. Em um laptop, isso é conveniente. Em qualquer outro lugar, mude quatro coisas antes de habilitá-lo:

```sql theme={null}
SET GLOBAL vsql_rest.allowed_tables = 'products';
SET GLOBAL vsql_rest.table_methods  = 'products:GET';
SET GLOBAL vsql_rest.require_auth   = ON;
SET GLOBAL vsql_rest.jwt_secret     = '...';
```

Depois, sirva-o por HTTPS definindo `ssl_cert` e `ssl_key`. Não existe uma configuração de endereço de bind, e o listener vincula todas as interfaces a partir do momento em que inicia, então bloqueie a porta no firewall e deixe somente um proxy reverso alcançá-la.

## Solução de Problemas

| Sintoma | Correção |
| - | - |
| `ERROR 3219 ... requires preview capabilities` na instalação | Inicie o servidor com `--vsql_allow_preview_extensions=ON` |
| Conexão recusada | O listener está desligado. Verifique `vsql_rest.vsql_rest_enabled` e depois leia `vsql_rest.http_port` em `SHOW STATUS` |
| `table not found` para uma tabela que existe | Ela está faltando em `allowed_tables`, ou `vsql_rest.schema` aponta para um banco de dados diferente |
| Uma gravação retorna 405 | `table_methods` não concede esse método para a tabela |
| As configurações sumiram depois de reinstalar a extensão | `UNINSTALL EXTENSION` exclui as configurações persistidas. Aplique-as de novo |

## Veja também

* [vsql\_rest](https://villagesql.com/docs/pt-BR/extensions/vsql-rest.md) — a página de referência da extensão, com todas as configurações que ela adiciona
* [Fazendo Requisições HTTP a partir do SQL](https://villagesql.com/docs/pt-BR/guides/http-requests-in-mysql.md) — o mesmo servidor chamando para fora em vez de responder
* [Enriquecendo Linhas com Dados de APIs Externas](https://villagesql.com/docs/pt-BR/guides/rest-api-enrichment.md) — unindo uma consulta à API de outra pessoa
* [Hardening de Segurança do MySQL](https://villagesql.com/docs/pt-BR/guides/security-hardening.md) — o que mais fechar antes de uma porta ficar acessível


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.