SQL

O pacote @aziontech/sql é a biblioteca da Azion Lib para SQL Database. Ele cria, lista, lê e exclui bancos de dados e executa statements SQL em um banco de dados que você nomeia, pela Azion API v4. Suas funções recebem argumentos posicionais, e toda função informa uma falha dentro do objeto que retorna.

Instale o pacote:

Todos os exemplos desta página são módulos ES que usam await de nível superior e rodam no Node.js. Os exemplos em TypeScript importam tipos com import type, então continuam carregando depois que as anotações de tipo são removidas.

Autenticação

Cada função lê seu personal token da variável de ambiente AZION_TOKEN. Para passar o token no código, crie um client com createClient e defina o campo token dele.

Um arquivo .env com as duas variáveis tem esta forma:

Para saber como cada pacote da Azion Lib lê o token e a configuração de debug, consulte Como a Azion Lib funciona.

Envelope de resposta

Cada função resolve para um AzionDatabaseResponse, { data?, error? }. Uma chamada bem-sucedida preenche data. Uma chamada que falha preenche error com { message, operation }, em que operation nomeia a requisição que falhou, como post database ou apiQuery.

Um statement que falha dentro de useQuery também faz a chamada falhar: error contém o erro do banco de dados, como no such table: nope, e data não é definido.

Dois resultados fogem desse formato:

• deleteDatabase preenche data apenas com { state: 'pending' }. O envelope não traz id.
• getDatabase retorna um objeto vazio, {}, para um nome que não corresponde a nenhum banco de dados. Nem data nem error são definidos.

Um statement executado com useExecute resolve para este envelope. O array results contém uma entrada por statement:

Saída:

O resultado da consulta omite rows_read, rows_written e query_duration_ms, que a Azion API retorna para cada statement. Para medir o consumo, leia esses campos da API. Para mais informações, consulte Bancos de dados e consultas.

createClient

Cria um client que guarda um token e as opções de requisição. createClient também é o export padrão do pacote.

Retorna um AzionSQLClient com quatro métodos: createDatabase, deleteDatabase, getDatabase e getDatabases. Eles recebem os mesmos argumentos que as funções de mesmo nome, sem options. O client não executa statements: para isso, use useQuery, useExecute ou os métodos de banco de dados. Para um único client que cobre todos os módulos da Azion Lib, consulte Client.

Este exemplo cria um client e, com ele, um banco de dados:

Saída:

createDatabase

Cria um banco de dados. A função retorna enquanto o banco de dados ainda está sendo provisionado, então o status dele é creating. O status muda para created em poucos segundos; leia-o com getDatabase ou getDatabases.

Retorna data como o AzionDatabase criado. Uma conta comporta um número limitado de bancos de dados; acima desse número, a chamada preenche error com a mensagem listada em Erros.

Saída:

getDatabase

Retorna um banco de dados pelo nome.

Retorna data como um AzionDatabase, com os métodos de banco de dados. A função busca o nome entre os bancos de dados da conta e retorna a primeira correspondência. Um nome que não corresponde a nenhum banco de dados retorna {}: nem data nem error são definidos, então o ramo else do exemplo registra undefined para error.

Saída:

getDatabases

Lista os bancos de dados da conta, uma página por vez.

Retorna data como um AzionDatabaseCollections: databases contém a página, e count contém o número de bancos de dados.

Saída:

deleteDatabase

Exclui um banco de dados pelo ID. A exclusão é assíncrona: a API aceita a requisição, e o banco de dados sai da lista em poucos segundos. A exclusão é permanente, e as linhas que o banco de dados continha não podem ser recuperadas.

Retorna data como um AzionDatabaseDeleteResponse, { state: 'pending' }. A resposta não traz id, então o exemplo registra o ID que passou.

Saída:

useExecute

Executa statements SQL, como um INSERT ou um CREATE TABLE, no banco de dados que você nomeia.

Retorna data como um AzionDatabaseQueryResponse. Leia state em data, não no envelope: data.state é executed depois de uma execução bem-sucedida. A função primeiro procura o banco de dados pelo nome e depois envia os statements.

Este exemplo insere uma linha em uma tabela users com as colunas id e name:

Saída:

Escreva literais de string entre aspas simples dentro de um statement, como o exemplo faz.

useQuery

Executa consultas SQL, como um SELECT, no banco de dados que você nomeia e retorna as linhas que elas leem.

Retorna data como um AzionDatabaseQueryResponse. Cada statement tem uma entrada em data.results, na ordem de statements. As linhas do primeiro statement ficam em data.results[0].rows, e os nomes das colunas dele ficam em data.results[0].columns. data.toObject() retorna as mesmas linhas como objetos indexados pelo nome da coluna.

Saída:

getTables

Lista as tabelas de um banco de dados executando PRAGMA table_list nele.

Retorna data como um AzionDatabaseQueryResponse. data.results[0] contém uma linha por tabela, com as colunas schema, name, type, ncol, wr e strict. O nome da tabela é o segundo valor de cada linha. A lista inclui as tabelas do SQLite sqlite_schema e sqlite_temp_schema.

O banco de dados que getDatabase retorna também traz getTables, como um método que não recebe nome. Este exemplo lê um banco de dados e depois lista as tabelas dele com esse método:

Saída:

Métodos de banco de dados

O banco de dados que getDatabase retorna traz três métodos que agem sobre esse banco de dados. Eles retornam o mesmo envelope que as funções correspondentes e não recebem nome de banco de dados:

Este exemplo insere e conta linhas pelos métodos e depois lista as tabelas com a função independente getTables:

Saída:

Erros

Uma chamada que falha retorna uma destas mensagens em error.message, e error.operation nomeia a requisição.

Um nome que não corresponde a nenhum banco de dados não chega a esta tabela quando você chama getDatabase: a função retorna {}, sem error.

Tipos

O pacote exporta os tipos abaixo. Importe-os com import type.

AzionSQLClient

O client que createClient retorna.

AzionClientOptions

Opções de requisição que toda função recebe em options e que createClient aplica a todas as suas chamadas.

AzionEnvironment

O ambiente para onde vai uma chamada.

AzionDatabaseResponse

O envelope que toda função retorna. Para saber como lê-lo, consulte Envelope de resposta.

AzionSQLError

O erro que uma chamada que falha retorna em error.

AzionDatabase

Um banco de dados. O pacote também exporta apenas os campos dele como Database.

AzionDatabaseCollections

Uma página de bancos de dados.

AzionDatabaseCollectionOptions

Paginação e filtragem para getDatabases.

AzionDatabaseDeleteResponse

O que deleteDatabase retorna em data.

AzionDatabaseQueryResponse

O que useQuery, useExecute, getTables e os métodos de banco de dados retornam em data. O pacote também o exporta como AzionDatabaseExecutionResponse.

QueryResult

O resultado de um statement.

AzionQueryExecutionParams

Statements com seus parâmetros. Nenhuma função desta página recebe este tipo como argumento.

AzionQueryParams

O valor de um parâmetro de um statement SQL.

Recursos relacionados