# EdgeSQL Shell

EdgeSQL Shell é uma ferramenta de linha de comando em Python que gerencia os bancos de dados do [SQL Database](/pt-br/documentacao/plataforma/sql-database/) e executa SQL neles. Ela não é publicada em um índice de pacotes: você clona [o repositório](https://github.com/aziontech/edgesql-shell) e a instala a partir do código-fonte. O shell se autentica com a variável de ambiente `AZION_TOKEN`, e seu prompt é `EdgeSQL>`. Para as etapas de instalação, consulte [Instale o EdgeSQL Shell](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/dados/install-edge-sql-shell/).

> **Atenção**
>
> EdgeSQL Shell não inicia em uma instalação limpa. Todo comando falha antes de o prompt `EdgeSQL>` aparecer, com `ImportError: cannot import name 'Configuration' from 'kaggle.api.kaggle_api_extended'`: `commands/import.py` importa o módulo do Kaggle incondicionalmente enquanto o shell inicia, e o `kaggle==1.8.3` fixado não define mais esse símbolo. Fixar uma versão anterior não resolve em uma máquina sem credenciais da Kaggle, porque o pacote autentica dentro do próprio `__init__.py` — `1.6.17` e `1.7.4` falham nesse ponto. Uma correção está pendente.
>
> Neutralizar essa única importação localmente mantém o resto da ferramenta funcionando. Isso é uma solução local, não uma etapa suportada. Para as interfaces que executam o mesmo SQL até a correção ser lançada, consulte [Solução de problemas](/pt-br/documentacao/plataforma/sql-database/solucao-de-problemas/).

---

## Uso

Inicie EdgeSQL Shell a partir do diretório em que você o clonou, com o ambiente virtual ativo. Exporte o token antes:

```bash
export AZION_TOKEN="[TOKEN VALUE]"
python edgesql-shell.py
```

O shell abre no prompt `EdgeSQL>`. Cada linha que você digita é um comando da tabela em [Comandos](#comandos) ou uma instrução SQL que é executada no banco de dados em uso.

Duas flags executam o shell sem o prompt: `-n` torna a execução não interativa e `-c` passa um comando. Repita `-c` para executar vários comandos em ordem e sair:

```bash
python edgesql-shell.py -n -c ".use MyDB" -c ".tables"
```

---

## Comandos

EdgeSQL Shell aceita quinze comandos no prompt `EdgeSQL>`. `help` sem argumento imprime a lista de comandos, e `help .dump` imprime o texto de um deles.

| Comando                         | O que faz                                                             |
| ------------------------------- | --------------------------------------------------------------------- |
| `help`                          | Mostra informações sobre os comandos disponíveis ou sobre um comando. |
| `.databases`                    | Lista todos os bancos de dados.                                       |
| `.use <database-name>`          | Muda para um banco de dados específico.                               |
| `.tables`                       | Lista todas as tabelas do banco de dados.                             |
| `.schema <table-name>`          | Descreve o esquema de uma tabela específica.                          |
| `.dbinfo`                       | Recupera informações sobre o banco de dados atual.                    |
| `.read <file_path>`             | Carrega e executa as instruções SQL contidas em um arquivo.           |
| `.create <database-name>`       | Cria um novo banco de dados.                                          |
| `.destroy <database-name>`      | Destrói um banco de dados específico.                                 |
| `.output`                       | Define o destino da saída.                                            |
| `.dump <table-name>`            | Renderiza a estrutura da tabela como SQL.                             |
| `.mode`                         | Define o modo de saída.                                               |
| `.import <params> <table-name>` | Importa dados de uma fonte externa para a tabela.                     |
| `.dbsize`                       | Obtém o tamanho do banco de dados atual em MB.                        |
| `.exit`                         | Sai do EdgeSQL Shell.                                                 |

### .output

`.output` define onde EdgeSQL Shell escreve os resultados. Passe `stdout` para escrevê-los no terminal:

```bash
.output stdout
```

Passe o caminho de um arquivo para escrevê-los nesse arquivo:

```bash
.output /file.csv
```

### .dump

`.dump` renderiza a estrutura de uma tabela como SQL. Ele escreve no destino que `.output` guarda, então aponte `.output` para um arquivo antes de executá-lo para salvar o dump nesse arquivo:

```bash
.dump <table-name>
```

Duas opções restringem o que ele renderiza. `--schema-only` renderiza apenas o esquema da tabela, e `--data-only` renderiza apenas os dados dela:

```bash
.dump --schema-only <table-name>
```

### .mode

`.mode` define o formato em que EdgeSQL Shell imprime os resultados. Ele aceita um de sete valores:

- `excel`
- `tabular`
- `csv`
- `json`
- `html`
- `markdown`
- `raw`

Passe o valor como argumento do comando:

```bash
.mode tabular
```

### .import

`.import` carrega dados de uma fonte externa para uma tabela. Seis fontes estão disponíveis. `file` e `sqlite` leem de um caminho na sua máquina; `kaggle`, `mysql`, `postgres` e `turso` alcançam um servidor remoto e leem suas credenciais das variáveis em [Variáveis de ambiente](#variaveis-de-ambiente). `.import file` aceita um arquivo CSV ou XLSX e nenhum outro formato.

| Fonte      | Forma do argumento                                        |
| ---------- | --------------------------------------------------------- |
| `file`     | `.import file <csv\|xlsx> <file_path> <table_name>`       |
| `kaggle`   | `.import kaggle <dataset> <data_name> <table_name>`       |
| `mysql`    | `.import mysql <database> <source_table> <table_name>`    |
| `postgres` | `.import postgres <database> <source_table> <table_name>` |
| `sqlite`   | `.import sqlite <file_path> <source_table> <table_name>`  |
| `turso`    | `.import turso <database> <source_table> <table_name>`    |

`help .import` imprime os parâmetros de cada fonte. Selecione um banco de dados com `.use` antes: sem nenhum selecionado, o comando responde `No database selected. Use '.use <database_name>' to select a database.` em vez do texto de ajuda.

```bash
help .import
```

O shell responde com este texto:

```text
.import: Import data from file files, Kaggle datasets, or databases into a database table.

    Args:
        arg (str): The import command and its arguments.

    Command Formats:
        .import file <csv|xlsx> <file_path> <table_name>: Import data from a file CSV or Excel file.
        .import kaggle <dataset> <data_name> <table_name>: Import data from a Kaggle dataset.
        .import mysql <database> <source_table> <table_name>: Import data from a MySQL database table.
        .import postgres <database> <source_table> <table_name>: Import data from PostgreSQL database table.
        .import turso <database> <source_table> <table_name>: Import data from Turso database.

    Examples:
        .import file csv /path/to/file.csv my_table
        .import kaggle joonasyoon/google-doodles list.csv list
        .import mysql mydb_name source_table_name my_table
        .import turso <database> <source_table> <table_name>
```

Esse texto não corresponde ao shell que ele documenta. Ele deixa `sqlite` de fora dos formatos de comando e lista cinco formatos contra quatro exemplos, porque `postgres` não tem exemplo. O exemplo de `turso` repete os placeholders do formato de comando dele em vez de mostrar um valor. E `Import data from file files` é um erro de digitação que o shell imprime.

---

## Variáveis de ambiente

EdgeSQL Shell lê suas credenciais do ambiente. Defina cada variável com `export` antes de iniciar o shell: o personal token da Azion com que ele se autentica e as credenciais da fonte que uma execução de `.import` lê. A coluna Obrigatória indica se a fonte que lê a variável precisa dela.

| Fonte      | Variável                   | Obrigatória | O que guarda                                                                    |
| ---------- | -------------------------- | ----------- | ------------------------------------------------------------------------------- |
| Azion      | `AZION_TOKEN`              | Sim         | O personal token da Azion com que o shell se autentica                          |
| Kaggle     | `KAGGLE_USERNAME`          | Sim         | O nome de usuário do Kaggle                                                     |
| Kaggle     | `KAGGLE_KEY`               | Sim         | A chave de API do Kaggle                                                        |
| MySQL      | `MYSQL_USERNAME`           | Sim         | O nome de usuário no servidor MySQL                                             |
| MySQL      | `MYSQL_PASSWORD`           | Sim         | A senha desse usuário                                                           |
| MySQL      | `MYSQL_HOST`               | Sim         | O endereço do servidor MySQL                                                    |
| MySQL      | `MYSQL_PORT`               | Não         | A porta do servidor MySQL                                                       |
| MySQL      | `MYSQL_SSL_CA`             | Não         | A autoridade certificadora de uma conexão TLS                                   |
| MySQL      | `MYSQL_SSL_CERT`           | Não         | O certificado do cliente de uma conexão TLS                                     |
| MySQL      | `MYSQL_SSL_KEY`            | Não         | A chave do cliente de uma conexão TLS                                           |
| MySQL      | `MYSQL_SSL_VERIFY_CERT`    | Não         | Se o certificado do servidor é verificado: `True` ou `False`                    |
| PostgreSQL | `POSTGRES_USERNAME`        | Sim         | O nome de usuário no servidor PostgreSQL                                        |
| PostgreSQL | `POSTGRES_PASSWORD`        | Sim         | A senha desse usuário                                                           |
| PostgreSQL | `POSTGRES_HOST`            | Sim         | O endereço do servidor PostgreSQL                                               |
| PostgreSQL | `POSTGRES_PORT`            | Não         | A porta do servidor PostgreSQL                                                  |
| PostgreSQL | `POSTGRES_SSL_CA`          | Não         | A autoridade certificadora de uma conexão TLS                                   |
| PostgreSQL | `POSTGRES_SSL_CERT`        | Não         | O certificado do cliente de uma conexão TLS                                     |
| PostgreSQL | `POSTGRES_SSL_KEY`         | Não         | A chave do cliente de uma conexão TLS                                           |
| PostgreSQL | `POSTGRES_SSL_VERIFY_CERT` | Não         | Se o certificado do servidor é verificado: `True` ou `False`                    |
| Turso      | `TURSO_DATABASE_URL`       | Sim         | A URL do banco de dados, no formato `https://<db_name>-<organization>.turso.io` |
| Turso      | `TURSO_AUTH_TOKEN`         | Sim         | O token de autenticação do Turso                                                |
| Turso      | `TURSO_ENCRYPTION_KEY`     | Não         | A chave de criptografia do banco de dados Turso                                 |

Defina o token e, em seguida, as credenciais da fonte de onde você importa:

```bash
export AZION_TOKEN="[TOKEN VALUE]"
export MYSQL_USERNAME="<username>"
export MYSQL_PASSWORD="<password>"
export MYSQL_HOST="<host_address>"
```

---

## Comandos que funcionam

Com a importação do Kaggle substituída por um stub para passar do erro de inicialização, estes comandos funcionam: `.databases`, `.use`, `.tables`, `.schema`, `.dbinfo`, `.dbsize`, `.read`, `.import file csv`, `.import sqlite`, `.dump --schema-only` e uma instrução `SELECT` simples.

Quatro deles respondem com uma mensagem ou com uma tabela própria. `.read` responde `SQL statements from <file_path> executed successfully.` e `.import sqlite` responde `Data imported successfully into table '<table_name>'.` `.dbsize` responde com uma tabela de uma coluna com o cabeçalho `size_in_mb`, e `.dbinfo` responde com uma tabela de Attribute e Value que traz Database ID, Database Name, Status, Active, Last Modified, Last Editor e Product Version.

As formas dos argumentos das outras fontes de importação, `mysql`, `postgres`, `kaggle` e `turso`, vêm do próprio texto de `help .import` do shell.

---

## Recursos relacionados

- [Instale o EdgeSQL Shell](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/dados/install-edge-sql-shell.md): O clone, o ambiente virtual e os requisitos que colocam o shell na sua máquina.
- [Importe dados com o EdgeSQL Shell](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/dados/importar-dados-edge-sql.md): As etapas que carregam um arquivo para uma tabela com o comando de importação desta página.
- [Bancos de dados e consultas](/pt-br/documentacao/plataforma/sql-database/bancos-de-dados-e-consultas.md): Os mesmos bancos de dados e tabelas pela API da Azion v4, com cada campo e cada erro.
- [Como o SQL Database funciona](/pt-br/documentacao/plataforma/sql-database/como-funciona.md): Onde um banco de dados vive e como uma instrução alcança os dados que o shell imprime.
- [Solução de problemas](/pt-br/documentacao/plataforma/sql-database/solucao-de-problemas.md): O que verificar quando um comando ou uma consulta não responde como esta página descreve.