# Biblioteca `SQL` da Azion

import LinkButton from 'azion-webkit/linkbutton'

A biblioteca **SQL Database** fornece métodos para interagir com a API do **SQL Database**, permitindo que você crie, exclua e faça consultas em bancos de dados. Este cliente é configurável e suporta tanto o modo de debug quanto configuração baseada em variáveis de ambiente.

<LinkButton link="/pt-br/documentacao/produtos/azion-lib/visao-geral/" label="Saiba mais sobre as Azion Libraries" severity="secondary" />

Você pode interagir com a API do SQL usando um `client` ou chamando os métodos diretamente da biblioteca. Ao fazer chamadas diretas, você pode usar as variáveis de ambiente para configurar o `client` sem passar os parâmetros de token e debug diretamente.

Exemplo de um arquivo `.env` com suas variáveis de ambiente:

```sh
AZION_TOKEN=<your-api-token>
AZION_DEBUG=true
```

| Variável | Descrição |
|----------|-------------|
| `AZION_TOKEN` | Seu token de API da Azion. |
| `AZION_DEBUG` | Ativar o modo de debug (true/false). |

:::tip
Definir `AZION_DEBUG` como `true` ativa o **modo de debug**. Este modo fornece registros detalhados das requisições e respostas da API.
:::

Se você quiser criar um `client` específico para interagir com **SQL**, faça isso chamando o método `createClient` da biblioteca:

```typescript
import { createClient } from 'azion/purge';
import type { AzionSQLClient, AzionSQLResponse, AzionSQL } from 'azion/purge';

const client: AzionSQLClient = createClient({ token: 'your-api-token', options: { debug: true } });

const { data, error } = await client.createDatabase('my-new-db');
if (data) {
  console.log(`Database created with ID: ${data.id}`);
} else {
  console.error('Failed to create database', error);
}
```

O método `createClient` tem os seguintes **parâmetros** e **valor de retorno**:

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `config` | `Partial<{ token: string; options?: OptionsParams }>` | Opções de configuração para o cliente do SQL. |

**Retorno**:

| Tipo de retorno | Descrição |
|-------------|-------------|
| `AzionSQLClient` | Um objeto com métodos para interagir com o SQL. |

:::note
Nos exemplos a seguir, os métodos são chamados diretamente sem a criação de um `client`. Para mais informações sobre como interagir com serviços e produtos usando um `client`, verifique a [documentação do cliente Azion Lib](/pt-br/documentacao/produtos/azion-lib/client/).
:::

---

## Uso

### `createDatabase`

Cria um novo banco de dados.

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `name` | `string` | Nome do novo banco de dados. |
| `options` | `AzionClientOptions` (opcional) | Parâmetros opcionais para a criação. |

**Retorno**:

| Tipo de Retorno | Descrição |
|-------------|-------------|
| `Promise<AzionDatabaseResponse<AzionDatabase>>` | O objeto do banco de dados criado ou o erro em caso de falha. |

**Exemplo**:

```typescript
import { createDatabase, AzionDatabase } from 'azion/sql';
import type { AzionDatabaseResponse, AzionDatabase } from 'azion/sql';

const { data, error }: AzionDatabaseResponse<AzionDatabase> = await createDatabase('my-new-database', { debug: true });
if (data) {
  const database: AzionDatabase = data;
  console.log(`Database created with ID: ${database.id}`);
} else {
  console.error('Failed to create database', error);
}
```

### `deleteDatabase`

Exclui um banco de dados pelo seu ID.

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `id` | `number` | ID do banco de dados a ser excluído. |
| `options` | `AzionClientOptions` (opcional) | Parâmetros opcionais para a exclusão. |

**Retorno**:

| Tipo de retorno | Descrição |
|-------------|-------------|
| `Promise<AzionDatabaseResponse<AzionDatabaseDeleteResponse>>` | Objeto confirmando exclusão ou erro. |

**Exemplo**:

```typescript
import { deleteDatabase } from 'azion/sql';
import type { AzionDatabaseResponse, AzionDatabaseDeleteResponse } from 'azion/sql';

const { data, error }: AzionDatabaseResponse<AzionDatabaseDeleteResponse> = await deleteDatabase(123, { debug: true });
if (data) {
  console.log(`Database ${data.id} deleted successfully`);
} else {
  console.error('Failed to delete database', error);
}
```

### `getDatabase`

Recupera um banco de dados pelo seu nome.

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `name` | `string` | Nome do banco de dados a ser recuperado. |
| `options` | `AzionClientOptions` (opcional) | Parâmetros opcionais para a recuperação. |

**Retorno**:

| Tipo de retorno | Descrição |
|-------------|-------------|
| `Promise<AzionDatabaseResponse<AzionDatabase>>` | O objeto do banco de dados recuperado ou o erro em caso de falha. |

**Exemplo**:

```typescript
import { getDatabase } from 'azion/sql';
import type { AzionDatabaseResponse, AzionDatabase } from 'azion/sql';

const { data, error }: AzionDatabaseResponse<AzionDatabase> = await getDatabase('my-db', { debug: true });
if (data) {
  const database: AzionDatabase = data;
  console.log(`Retrieved database: ${database.id}`);
} else {
  console.error('Database not found', error);
}
```

### `getDatabases`

Recupera uma lista de bancos de dados com filtragem e paginação opcionais.

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `params` | `AzionDatabaseCollectionOptions` (opcional) | Parâmetros opcionais para filtragem e paginação. |
| `options` | `AzionClientOptions` (opcional) | Parâmetros opcionais para a recuperação. |

**Retorno**:

| Tipo de retorno | Descrição |
|-------------|-------------|
| `Promise<AzionDatabaseResponse<AzionDatabaseCollections>>` | Array de objetos de banco de dados ou erro. |

**Exemplo**:

```typescript
import { getDatabases } from 'azion/sql';
import type { AzionDatabaseResponse, AzionDatabaseCollections } from 'azion/sql';

const { data: allDatabases, error }: AzionDatabaseResponse<AzionDatabaseCollections> = await getDatabases(
  { page: 1, page_size: 10 },
  { debug: true },
);
if (allDatabases) {
  console.log(`Retrieved ${allDatabases.count} databases`);
} else {
  console.error('Failed to retrieve databases', error);
}
```

### `useQuery`

Executa uma consulta em um banco de dados específico.

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `name` | `string` | Nome do banco de dados a ser consultado. |
| `statements` | `string[]` | Array de declarações SQL a serem executadas. |
| `options` | `AzionClientOptions` (opcional) | Parâmetros opcionais para a consulta. |

**Retorno**:

| Tipo de retorno | Descrição |
|-------------|-------------|
| `Promise<AzionDatabaseResponse<AzionDatabaseQueryResponse>>` | Objeto de resultado da consulta ou erro. |

**Exemplo**:

```typescript
import { useQuery, AzionDatabaseQueryResponse, AzionDatabaseResponse } from 'azion/sql';

const { data: result, error }: AzionDatabaseResponse<AzionDatabaseQueryResponse> = await useQuery(
  'my-db',
  ['SELECT * FROM users'],
  {
    debug: true,
  },
);
if (result) {
  console.log(`Query executed. Rows returned: ${result.rows.length}`);
} else {
  console.error('Query execution failed', error);
}
```

### `useExecute`

Executa um conjunto de declarações SQL em um banco de dados específico.

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `name` | `string` | Nome do banco de dados no qual as declarações serão executadas. |
| `statements` | `string[]` | Array de declarações SQL a serem executadas. |
| `options` | `AzionClientOptions` (opcional) | Parâmetros opcionais para a execução. |

**Retorno**:

| Tipo de retorno | Descrição |
|-------------|-------------|
| `Promise<AzionDatabaseResponse<AzionDatabaseQueryResponse>>` | Objeto de resultado da execução ou erro. |

**Exemplo**:

```typescript
import { useExecute, AzionDatabaseQueryResponse } from 'azion/sql';

const result: AzionDatabaseQueryResponse | null = await useExecute(
  'my-db',
  ['INSERT INTO users (name) VALUES ("John")'],
  {
    debug: true,
  },
);
if (result?.state === 'executed') {
  console.log('Executed with success');
} else {
  console.error('Execution failed');
}
```

### `getTables`

Recupera uma lista de tabelas em um banco de dados específico.

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `name` | `string` | Nome do banco de dados do qual recuperar as tabelas. |
| `options` | `AzionClientOptions` (opcional) | Parâmetros opcionais para a recuperação. |

**Retorno**:

| Tipo de retorno | Descrição |
|-------------|-------------|
| `Promise<AzionDatabaseResponse<AzionDatabaseQueryResponse>>` | Resultado da consulta contendo informações das tabelas ou erro. |

**Exemplo**:

```typescript
import { getDatabase } from 'azion/sql';
import type { AzionDatabaseResponse, AzionDatabase, AzionDatabaseQueryResponse } from 'azion/sql';

// Primeiro obtenha o banco de dados
const { data: database, error }: AzionDatabaseResponse<AzionDatabase> = await getDatabase('my-db', { debug: true });

if (database) {
  // Então obtenha as tabelas usando o método do objeto database
  const { data: tables, error: tablesError }: AzionDatabaseResponse<AzionDatabaseQueryResponse> = await database.getTables();
  if (tables) {
    console.log('Tabelas:', tables.data);
  } else {
    console.error('Falha ao obter tabelas', tablesError);
  }
}
```

---

## Tipos

Esses são os tipos usados pela biblioteca **SQL** e seus métodos:

### `ClientConfig`

Opções de configuração para o cliente SQL.

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `token` | `string` (opcional) | Sua chave de API da Azion. |
| `options` | `AzionClientOptions` (opcional) | Parâmetros opcionais para a configuração do cliente. |

### `AzionSQLClient`

Um objeto com métodos para interagir com bancos de dados SQL.

| Método | Parâmetros | Tipo de Retorno |
|--------|------------|-------------|
| `createDatabase` | `name: string` | `Promise<AzionDatabaseResponse<AzionDatabase>>` |
| `deleteDatabase` | `id: number` | `Promise<AzionDatabaseResponse<AzionDatabaseDeleteResponse>>` |
| `getDatabase` | `name: string` | `Promise<AzionDatabaseResponse<AzionDatabase>>` |
| `getDatabases` | `params?: AzionDatabaseCollectionOptions` | `Promise<AzionDatabaseResponse<AzionDatabaseCollections>>` |
| `useQuery` | `name: string, statements: string[], options?: AzionClientOptions` | `Promise<AzionDatabaseResponse<AzionDatabaseQueryResponse>>` |
| `useExecute` | `name: string, statements: string[], options?: AzionClientOptions` | `Promise<AzionDatabaseResponse<AzionDatabaseExecutionResponse>>` |

### `AzionDatabase`

O objeto de banco de dados.

| Propriedade | Tipo | Descrição |
|----------|------|-------------|
| `id` | `number` | Identificador único do banco de dados. |
| `name` | `string` | O nome do banco de dados. |
| `clientId` | `string` | O ID do cliente associado ao banco de dados. |
| `status` | `string` | O status atual do banco de dados. |
| `createdAt` | `string` | O timestamp de quando o banco de dados foi criado. |
| `updatedAt` | `string` | O timestamp de quando o banco de dados foi atualizado. |
| `deletedAt` | `string \| null` | Timestamp de quando o banco de dados foi excluído, ou nulo se não foi excluído. |
| `query` | `(statements: string[], options?: AzionClientOptions) => Promise<AzionDatabaseResponse<AzionDatabaseQueryResponse>>` | Executa uma consulta SQL no banco de dados. |
| `execute` | `(statements: string[], options?: AzionClientOptions) => Promise<AzionDatabaseResponse<AzionDatabaseExecutionResponse>>` | Executa um comando SQL no banco de dados. |
| `getTables` | `(options?: AzionClientOptions) => Promise<AzionDatabaseResponse<AzionDatabaseQueryResponse>>` | Retorna uma lista de tabelas no banco de dados. |

### `AzionDatabaseResponse<T>`

O objeto de resposta de uma operação de banco de dados.

| Propriedade | Tipo | Descrição |
|----------|------|-------------|
| `data` | `T` (opcional) | Os dados retornados da operação. |
| `error` | `{ message: string, operation: string }` (opcional) | Os detalhes do erro se a operação falhar. |

### `QueryResult`

| Propriedade | Tipo | Descrição |
|----------|------|-------------|
| `state` | `string` | O estado da execução da consulta. |
| `columns` | `string[]` | Um array de nomes de colunas. |
| `statement` | `string` | O comando SQL executado. |
| `rows` | `(number \| string)[][]` | Um array de linhas, onde cada linha é um array de valores. |

### `AzionClientOptions`

Parâmetros opcionais para a configuração do cliente.

| Propriedade | Tipo | Descrição |
|----------|------|-------------|
| `debug` | `boolean` (opcional) | Habilita o modo de debug. |
| `force` | `boolean` (opcional) | Força a execução da operação. |

### `AzionDatabaseCollectionOptions`

Parâmetros opcionais para filtragem e paginação.

| Propriedade | Tipo | Descrição |
|----------|------|-------------|
| `ordering` | `string` (opcional) | Define a ordem dos resultados. |
| `page` | `number` (opcional) | O número da página para paginação. |
| `page_size` | `number` (opcional) | O número de itens por página. |
| `search` | `string` (opcional) | Uma busca para filtrar os resultados. |

### `AzionDatabaseQueryResponse`

O objeto de resposta da execução de uma consulta.

| Propriedade | Tipo | Descrição |
|----------|------|-------------|
| `state` | (`'executed' \| 'pending' \| 'executed-runtime' \| 'failed'`) | O estado da execução da consulta. |
| `data` | `QueryResult[]` | Os dados retornados da operação. |
| `toObject` | `() => JsonObjectQueryExecutionResponse` (opcional) | Um método para converter a resposta em um objeto JSON. |

### `AzionDatabaseExecutionResponse`

O objeto de resposta da execução de um comando.

| Propriedade | Tipo | Descrição |
|----------|------|-------------|
| `state` | (`'executed' \| 'pending' \| 'executed-runtime' \| 'failed'`) | O estado da execução do comando. |
| `data` | `QueryResult[]` | Os dados retornados da operação. |
| `toObject` | `() => JsonObjectQueryExecutionResponse` (opcional) | Um método para converter a resposta em um objeto JSON. |

### `AzionQueryExecutionParams`

Parâmetros para execução de consulta.

| Propriedade | Tipo | Descrição |
|----------|------|-------------|
| `statements` | `string[]` | Um array de comandos SQL. |
| `params` | `(AzionQueryParams \| `Record\<`string`, `AzionQueryParams`>`)[]` (opcional) | Um array de parâmetros de consulta. |

### `AzionQueryParams`

Parâmetros de consulta.

| Propriedade | Tipo | Descrição |
|----------|------|-------------|
| `param` | `string | number | boolean | null` | O parâmetro para o comando SQL. |