---
name: azion-consulte-um-banco-de-dados-de-uma-function
description: >-
  Leia linhas do SQL Database dentro de uma function com o módulo de runtime azion:sql, e retorne essas linhas na resposta que a function envia.
---

# Consulte um banco de dados de uma function

Você lê linhas de um banco de dados no [SQL Database](/pt-br/documentacao/plataforma/sql-database/) dentro de uma [function](/pt-br/documentacao/plataforma/functions/), durante a requisição que a function atende. O módulo de runtime `azion:sql` abre a conexão e executa o SQL.

Esta página traz uma function completa. Para todos os métodos que o módulo expõe, consulte [SQL Database API](/pt-br/documentacao/devtools/runtime/api-reference/sql-database/).

---

## Pré-requisitos

- Uma aplicação para instanciar a function. Consulte [Instancie uma função em uma aplicação](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/primeiros-passos/instanciar-functions/).
- Um [personal token](/pt-br/documentacao/guias/plataforma/conta-e-billing/personal-tokens/) para autorizar as requisições à API.
- A permissão **Edit SQL Database**, que concede permissão para criar e editar bancos de dados e os seus dados pela API da Azion. Consulte [Teams Permissions](/pt-br/documentacao/fundamentos/teams-permissions/).
- SQL Database habilitado na sua conta. O produto está em Preview e não é habilitado por padrão, então solicite acesso pelo [Technical Support](/pt-br/documentacao/suporte/).

---

## Crie o banco de dados e a tabela

A function lê uma tabela que já existe, então as duas chamadas abaixo são o caminho mais curto até uma. Para criar o banco de dados e preenchê-lo com linhas:

1. **Crie o banco de dados**

   ```bash
   curl --location --request POST 'https://api.azion.com/v4/workspace/sql/databases' \
   --header 'Accept: application/json' \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Token [TOKEN VALUE]' \
   --data '{"name":"mydatabase"}'
   ```

   A API responde com HTTP `202` e retorna o identificador que a próxima chamada usa no seu caminho:

   ```json
   {
     "state": "pending",
     "data": {
       "id": 1234,
       "name": "mydatabase",
       "status": "creating",
       "active": true,
       "last_modified": "2026-01-01T12:00:00.000000Z",
       "last_editor": "user@example.com",
       "product_version": "1.0"
     }
   }
   ```

   O provisionamento leva cerca de 15 segundos. Envie `GET /databases/{database_id}` até que `status` marque `created`.

2. **Crie a tabela e insira as linhas**

   ```bash
   curl --location --request POST 'https://api.azion.com/v4/workspace/sql/databases/<database-id>/query' \
   --header 'Accept: application/json' \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Token [TOKEN VALUE]' \
   --data '{"statements":["CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL);","INSERT INTO users VALUES (1, '\''user 1'\'');","INSERT INTO users VALUES (2, '\''user 2'\'');","INSERT INTO users VALUES (3, '\''user 3'\'');"]}'
   ```

   A API responde com HTTP `200` e `"state": "executed"`, e `data` traz uma entrada por statement, na ordem em que você as enviou.

O banco de dados `mydatabase` contém uma tabela `users` com três linhas. O nome que você define aqui é o nome que a function passa para `Database.open`.

> **nota**
>
> Um statement que falha não faz a requisição falhar. A chamada ainda responde HTTP `200`, e a entrada desse statement traz `error` em vez de `results`, então leia `data[].error` antes de considerar a chamada concluída.

---

## Escreva a function

`Database.open` abre uma conexão com a réplica de leitura do banco de dados, então uma function lê os dados e não escreve neles. O handler abaixo responde a uma requisição `GET` com o conteúdo de `users`:

```javascript
import { Database } from "azion:sql";

async function db_query() {
  let connection = await Database.open("mydatabase");
  let rows = await connection.query("select * from users");
  let column_count = rows.columnCount();
  let column_names = [];
  for (let i = 0; i < column_count; i++) {
    column_names.push(rows.columnName(i));
  }
  let response_lines = [];
  response_lines.push(column_names.join("|"));
  let row = await rows.next();
  while (row) {
    let row_items = [];
    for (let i = 0; i < column_count; i++) {
      row_items.push(row.getString(i));
    }
    response_lines.push(row_items.join("|"));
    row = await rows.next();
  }
  const response_text = response_lines.join("\n");
  return response_text;
}

async function handle_request(request) {
  if (request.method != "GET") {
    return new Response("Method not allowed", { status: 405 });
  }
  try {
    return new Response(await db_query());
  } catch (e) {
    console.log(e.message, e.stack);
    return new Response(e.message, { status: 500 });
  }
}

addEventListener("fetch", (event) =>
  event.respondWith(handle_request(event.request))
);
```

`connection.query` retorna um handle de linhas. `rows.columnCount()` e `rows.columnName(i)` nomeiam as colunas, `rows.next()` avança uma linha e retorna um valor falsy quando o conjunto de resultados termina, e `row.getString(i)` lê uma célula pela sua posição. O exemplo junta as células de uma linha com `|` e as linhas com uma quebra de linha, e depois envia o texto como corpo da resposta. Uma falha dentro do módulo é registrada com `e.message` e `e.stack` e retornada como HTTP `500`.

> **nota**
>
> O exemplo lê dados, então ele responde a `GET` e recusa todos os outros métodos com `405`. Ajuste a verificação para os métodos que a sua própria lógica atende.

---

## Instancie e execute a function

Uma function só é executada depois de ser vinculada a uma aplicação e de uma regra dessa aplicação selecioná-la. Para executar a function e ler as linhas:

1. **Crie a function no Azion Console**

   Acesse [Azion Console](https://console.azion.com/) e crie uma function que carrega o código acima. Consulte [Functions](/pt-br/documentacao/plataforma/functions/).

2. **Instancie a function em uma aplicação**

   Vincule a function à aplicação que atende o seu domínio e adicione a regra que executa a instância. Consulte [Instancie uma função em uma aplicação](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/primeiros-passos/instanciar-functions/).

3. **Faça uma requisição à aplicação**

   ```bash
   curl 'https://<your-application-domain>/'
   ```

A resposta traz os nomes das colunas na primeira linha e uma linha para cada registro de `users`:

```text
id|name
1|user 1
2|user 2
3|user 3
```

---

## Próximos passos

- [SQL Database API](/pt-br/documentacao/devtools/runtime/api-reference/sql-database.md): Todos os métodos que o módulo azion:sql expõe a uma function, com a sua assinatura.
- [Crie tabelas e consulte dados](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/dados/criar-tabelas-edge-sql.md): Defina as tabelas que a function lê, insira linhas e leia-as de volta com SQL.
- [Instancie uma função em uma aplicação](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/primeiros-passos/instanciar-functions.md): Vincule a function a uma aplicação, nomeie a instância e passe os seus Args em JSON.
- [Bancos de dados e consultas](/pt-br/documentacao/plataforma/sql-database/bancos-de-dados-e-consultas.md): Todos os campos, operações, envelopes e códigos de erro dos endpoints do SQL Database.