Biblioteca `SQL` da Azion

A biblioteca Edge SQL fornece métodos para interagir com a API do Edge SQL, 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.

Saiba mais sobre as Azion Libraries

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:

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).

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

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.

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:

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:

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:

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:

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:

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:

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');
}

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