# Primeiros passos com SQL Database Este guia orienta você a armazenar e ler a sua primeira linha no [SQL Database](/pt-br/documentacao/plataforma/sql-database/). No fim, você vai ter: - O seu primeiro banco de dados, com o status `created`. - Uma tabela `users` dentro dele. - Uma linha armazenada nessa tabela. - A mesma linha retornada por uma instrução `SELECT`. O resultado se apoia em dois objetos. O **banco de dados** é o container, e o seu nome não pode ser alterado depois da criação. Cada **tabela** fica dentro de um banco de dados, e este guia cria a tabela com uma instrução `CREATE TABLE`. Um banco de dados é provisionado de forma assíncrona. O seu status marca `creating` primeiro, e uma instrução só é executada contra ele depois que o status marca `created`. --- Selecione a interface que você vai usar. Os pré-requisitos e todas as etapas abaixo seguem essa escolha. ## Pré-requisitos - SQL Database habilitado na conta. O produto está em Preview, e o acesso é solicitado ao time de suporte técnico. Para solicitá-lo, consulte [Technical Support](/pt-br/documentacao/suporte/). - A permissão **Edit SQL Database** na conta. Ela concede permissão para criar e editar bancos de dados e os seus dados. Para mais informações, consulte [Teams Permissions](/pt-br/documentacao/fundamentos/teams-permissions/). **Console** - Acesso ao Azion Console. Para entrar, consulte [Como acessar o Azion Console](/pt-br/documentacao/guias/plataforma/conta-e-billing/como-acessar-o-azion-console/). **API** - Um [personal token](/pt-br/documentacao/guias/plataforma/conta-e-billing/personal-tokens/) e o `curl`. --- ## Crie um banco de dados Um banco de dados guarda as tabelas que você cria. O seu nome tem de 6 a 50 caracteres e usa letras, números e o hífen. O provisionamento é assíncrono, então o banco de dados não aceita consultas no instante em que é criado. **Console** Para criar o banco de dados pelo Azion Console: 1. **Abra a lista de bancos de dados** Acesse [Azion Console](https://console.azion.com/) > **SQL Database**. 2. **Abra o formulário de criação** Inicie um novo banco de dados a partir da lista, com o controle **SQL Database**. 3. **Nomeie o banco de dados** Em **General**, no campo **Name**, insira um nome seu. Um nome que outro banco de dados da conta já tem é recusado. 4. **Selecione Save** O banco de dados aparece na lista, que mostra o seu **Name**, **Status**, **Last Editor** e **Last Modified**. O seu status marca `creating` até marcar `created`, o que leva cerca de 15 segundos. **API** Para criar o banco de dados com a Azion API e esperar que ele fique pronto: 1. **Envie a requisição de criação** Substitua `[TOKEN VALUE]` pelo seu personal token e `my-database` por um nome seu: ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/sql/databases \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data '{ "name": "my-database" }' ``` 2. **Leia a resposta** Um `202` carrega o banco de dados: ```json { "state": "pending", "data": { "id": 1235, "name": "my-database", "status": "creating", "active": true, "last_modified": "2026-01-01T12:13:01.399970Z", "last_editor": "user@example.com", "product_version": "1.0" } } ``` Registre o `id`, `1235` neste exemplo. Todas as requisições abaixo endereçam o banco de dados por ele. Um `400` com o código `14001` significa que a conta já tem um banco de dados com esse nome. Escolha um nome diferente e envie a requisição outra vez. 3. **Consulte até o status marcar created** Substitua `1235` pelo `id` que a resposta de criação retornou: ```bash curl --request GET \ --url https://api.azion.com/v4/workspace/sql/databases/1235 \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' ``` Um `200` carrega o banco de dados, e esta resposta não tem a chave `state`: ```json { "data": { "id": 1235, "name": "my-database", "status": "created", "active": true, "last_modified": "2026-01-01T12:13:13.920246Z", "last_editor": "user@example.com", "product_version": "1.0" } } ``` O provisionamento leva cerca de 15 segundos. Envie a requisição outra vez enquanto o status marcar `creating`. O banco de dados está pronto quando o `status` marca `created`. Não pule a espera: uma instrução enviada enquanto o status marca `creating` não pode ter sucesso. --- ## Crie uma tabela Uma tabela guarda as linhas que você armazena, e as suas colunas são fixadas pela instrução `CREATE TABLE`. **Console** A aba **Editor** executa SQL contra um banco de dados. Para criar a tabela que este guia usa: 1. **Abra o banco de dados** Na lista **SQL Database**, selecione o banco de dados que você criou. 2. **Vá para a aba Editor** 3. **Insira a instrução CREATE TABLE** Crie a tabela `users` com três colunas: ```sql CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT); ``` 4. **Selecione Run query** A tabela aparece na aba **Tables**. **API** O endpoint de query executa SQL contra um banco de dados. O body carrega um array `statements`, e a Azion executa as instruções em ordem. 1. **Envie a requisição de query** Substitua `1235` pelo `id` do seu banco de dados: ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/sql/databases/1235/query \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data '{ "statements": ["CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT);"] }' ``` 2. **Leia a resposta** Um `200` carrega uma entrada por instrução: ```json { "state": "executed", "data": [ { "results": { "columns": [], "rows": [], "rows_read": 1, "rows_written": 2, "query_duration_ms": 2.592 } } ] } ``` A instrução não retorna linhas, então `columns` e `rows` vêm vazios. Ela ainda reporta linhas lidas e escritas, porque o `CREATE TABLE` escreve o próprio schema. A Azion cobra por `rows_read` e `rows_written`, e retorna os dois por instrução. O banco de dados guarda uma tabela `users` sem nenhuma linha. --- ## Insira uma linha Uma instrução `INSERT` armazena uma linha na tabela. **Console** Para armazenar a primeira linha pela aba **Editor**: 1. **Insira a instrução INSERT** Na aba **Editor**, insira a seguinte instrução: ```sql INSERT INTO users (name, email) VALUES ('Ada', 'ada@example.com'); ``` 2. **Selecione Run query** A tabela guarda uma linha. **API** Para armazenar a primeira linha pelo endpoint de query: 1. **Envie a requisição de query** A instrução `INSERT` carrega aspas simples, então o body é enviado pela entrada padrão: ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/sql/databases/1235/query \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data @- <<'EOF' { "statements": ["INSERT INTO users (name, email) VALUES ('Ada', 'ada@example.com');"] } EOF ``` 2. **Leia a resposta** Um `200` reporta a escrita: ```json { "state": "executed", "data": [ { "results": { "columns": [], "rows": [], "rows_read": 0, "rows_written": 1, "query_duration_ms": 2.649 } } ] } ``` A tabela guarda uma linha. --- ## Leia a linha de volta Uma instrução `SELECT` retorna o que a tabela guarda. **Console** Para ler a linha que você inseriu pela aba **Editor**: 1. **Insira a instrução SELECT** Na aba **Editor**, insira a seguinte instrução: ```sql SELECT id, name, email FROM users; ``` 2. **Selecione Run query** O resultado traz uma linha sob as colunas `id`, `name` e `email`: `1`, `Ada` e `ada@example.com`. **API** Para ler a linha que você inseriu pelo endpoint de query: 1. **Envie a requisição de query** ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/sql/databases/1235/query \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data '{ "statements": ["SELECT id, name, email FROM users;"] }' ``` 2. **Leia a resposta** Um `200` carrega os nomes das colunas e um array por linha: ```json { "state": "executed", "data": [ { "results": { "columns": ["id", "name", "email"], "rows": [[1, "Ada", "ada@example.com"]], "rows_read": 1, "rows_written": 0, "query_duration_ms": 0.041 } } ] } ``` O resultado traz uma linha sob as colunas `id`, `name` e `email`: `1`, `Ada` e `ada@example.com`. O seu primeiro banco de dados guarda uma tabela `users` com uma linha, e a lê de volta. As mesmas instruções são executadas no Azion Console, pela Azion API e dentro de uma function. > **Atenção** > > Uma instrução que falha não faz a requisição da API falhar. A resposta responde HTTP `200`, e a entrada dessa instrução carrega `error` no lugar de `results`: > > ```json > { > "state": "executed", > "data": [ > { > "error": "no such table: nope" > } > ] > } > ``` > > Verifique `data[].error` em cada instrução, não o código de status HTTP. Para mais informações, consulte [Bancos de dados e consultas](/pt-br/documentacao/plataforma/sql-database/bancos-de-dados-e-consultas/). --- ## Próximos passos - [Como o SQL Database funciona](/pt-br/documentacao/plataforma/sql-database/como-funciona.md): A instância principal, as réplicas de leitura e como uma instrução chega aos seus dados. - [Bancos de dados e consultas](/pt-br/documentacao/plataforma/sql-database/bancos-de-dados-e-consultas.md): Todos os campos que um banco de dados carrega, as cinco operações e os códigos de erro. - [Consulte um banco de dados de uma function](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/dados/listando-dados-edge-functions-edge-sql.md): Leia a mesma tabela de uma function em tempo de execução. - [Limites do SQL Database](/pt-br/documentacao/plataforma/sql-database/limites.md): Os limites de um nome e de uma tabela, e o uso incluído em cada plano.