# EdgeSQL Shell

EdgeSQL Shell is a Python command-line tool that manages [SQL Database](/en/documentation/platform/sql-database/) databases and runs SQL against them. It is not published on a package index: you clone [the repository](https://github.com/aziontech/edgesql-shell) and install it from source. The shell authenticates with the `AZION_TOKEN` environment variable, and its prompt is `EdgeSQL>`. For the installation steps, refer to [Install the EdgeSQL Shell](/en/documentation/guides/application-development/data/install-edge-sql-shell/).

> **Caution**
>
> EdgeSQL Shell does not start on a clean install. Every command fails before the `EdgeSQL>` prompt appears, with `ImportError: cannot import name 'Configuration' from 'kaggle.api.kaggle_api_extended'`: `commands/import.py` imports the Kaggle module unconditionally while the shell starts, and the pinned `kaggle==1.8.3` no longer defines that symbol. Downgrading does not rescue it on a machine with no Kaggle credentials, because the package authenticates inside its own `__init__.py` — `1.6.17` and `1.7.4` fail there instead. A fix is pending.
>
> Stubbing that one import out locally leaves the rest of the tool working. It is a local workaround, not a supported step. For the interfaces that run the same SQL until the fix ships, refer to [Troubleshooting](/en/documentation/platform/sql-database/troubleshooting/).

---

## Usage

Start EdgeSQL Shell from the directory you cloned it into, with its virtual environment active. Export the token first:

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

The shell opens on the `EdgeSQL>` prompt. Each line you enter is one command from the table under [Commands](#commands), or a SQL statement that runs against the database in use.

Two flags run the shell without the prompt: `-n` makes the run non-interactive, and `-c` passes one command. Repeat `-c` to run several commands in order and exit:

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

---

## Commands

EdgeSQL Shell accepts fifteen commands at the `EdgeSQL>` prompt. `help` with no argument prints the list of commands, and `help .dump` prints the text for one of them.

| Command                         | What it does                                                          |
| ------------------------------- | --------------------------------------------------------------------- |
| `help`                          | Shows information about the available commands, or about one command. |
| `.databases`                    | Lists all databases.                                                  |
| `.use <database-name>`          | Switches to a specific database.                                      |
| `.tables`                       | Lists all tables in the database.                                     |
| `.schema <table-name>`          | Describes the schema of a specific table.                             |
| `.dbinfo`                       | Retrieves information about the current database.                     |
| `.read <file_path>`             | Loads and runs the SQL statements held in a file.                     |
| `.create <database-name>`       | Creates a new database.                                               |
| `.destroy <database-name>`      | Destroys a specific database.                                         |
| `.output`                       | Sets the output destination.                                          |
| `.dump <table-name>`            | Renders the table structure as SQL.                                   |
| `.mode`                         | Sets the output mode.                                                 |
| `.import <params> <table-name>` | Imports data from an external source into the table.                  |
| `.dbsize`                       | Gets the size of the current database in MB.                          |
| `.exit`                         | Exits the EdgeSQL Shell.                                              |

### .output

`.output` sets where EdgeSQL Shell writes results. Pass `stdout` to write them to the terminal:

```bash
.output stdout
```

Pass a file path to write them to that file instead:

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

### .dump

`.dump` renders the structure of a table as SQL. It writes to the destination `.output` holds, so point `.output` at a file before you run it to save the dump to that file:

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

Two options narrow what it renders. `--schema-only` renders the schema of the table alone, and `--data-only` renders its data alone:

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

### .mode

`.mode` sets the format EdgeSQL Shell prints results in. It takes one of seven values:

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

Pass the value as the argument of the command:

```bash
.mode tabular
```

### .import

`.import` loads data from an external source into a table. Six sources are available. `file` and `sqlite` read from a path on your machine; `kaggle`, `mysql`, `postgres`, and `turso` reach a remote server and read their credentials from the variables under [Environment variables](#environment-variables). `.import file` accepts a CSV or an XLSX file and no other format.

| Source     | Argument form                                             |
| ---------- | --------------------------------------------------------- |
| `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` prints the parameters of every source. Select a database with `.use` first: with none selected, the command answers `No database selected. Use '.use <database_name>' to select a database.` instead of the help text.

```bash
help .import
```

The shell answers with this text:

```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>
```

That text does not match the shell it documents. It leaves `sqlite` out of the command formats, and it lists five formats against four examples, because `postgres` has no example. The `turso` example repeats the placeholders of its command format instead of showing a value. And `Import data from file files` is a typo the shell prints.

---

## Environment variables

EdgeSQL Shell reads its credentials from the environment. Set each variable with `export` before you start the shell: the Azion personal token it authenticates with, and the credentials of the source an `.import` run reads from. The Required column states whether the source that reads a variable needs it.

| Source     | Variable                   | Required | What it holds                                                        |
| ---------- | -------------------------- | -------- | -------------------------------------------------------------------- |
| Azion      | `AZION_TOKEN`              | Yes      | The Azion personal token the shell authenticates with                |
| Kaggle     | `KAGGLE_USERNAME`          | Yes      | The Kaggle user name                                                 |
| Kaggle     | `KAGGLE_KEY`               | Yes      | The Kaggle API key                                                   |
| MySQL      | `MYSQL_USERNAME`           | Yes      | The user name on the MySQL server                                    |
| MySQL      | `MYSQL_PASSWORD`           | Yes      | The password of that user                                            |
| MySQL      | `MYSQL_HOST`               | Yes      | The address of the MySQL server                                      |
| MySQL      | `MYSQL_PORT`               | No       | The port of the MySQL server                                         |
| MySQL      | `MYSQL_SSL_CA`             | No       | The certificate authority for a TLS connection                       |
| MySQL      | `MYSQL_SSL_CERT`           | No       | The client certificate for a TLS connection                          |
| MySQL      | `MYSQL_SSL_KEY`            | No       | The client key for a TLS connection                                  |
| MySQL      | `MYSQL_SSL_VERIFY_CERT`    | No       | Whether the server certificate is verified: `True` or `False`        |
| PostgreSQL | `POSTGRES_USERNAME`        | Yes      | The user name on the PostgreSQL server                               |
| PostgreSQL | `POSTGRES_PASSWORD`        | Yes      | The password of that user                                            |
| PostgreSQL | `POSTGRES_HOST`            | Yes      | The address of the PostgreSQL server                                 |
| PostgreSQL | `POSTGRES_PORT`            | No       | The port of the PostgreSQL server                                    |
| PostgreSQL | `POSTGRES_SSL_CA`          | No       | The certificate authority for a TLS connection                       |
| PostgreSQL | `POSTGRES_SSL_CERT`        | No       | The client certificate for a TLS connection                          |
| PostgreSQL | `POSTGRES_SSL_KEY`         | No       | The client key for a TLS connection                                  |
| PostgreSQL | `POSTGRES_SSL_VERIFY_CERT` | No       | Whether the server certificate is verified: `True` or `False`        |
| Turso      | `TURSO_DATABASE_URL`       | Yes      | The database URL, shaped `https://<db_name>-<organization>.turso.io` |
| Turso      | `TURSO_AUTH_TOKEN`         | Yes      | The Turso authentication token                                       |
| Turso      | `TURSO_ENCRYPTION_KEY`     | No       | The encryption key of the Turso database                             |

Set the token, and then the credentials of the source you import from:

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

---

## Working commands

With the Kaggle import stubbed to get past the startup error, these commands work: `.databases`, `.use`, `.tables`, `.schema`, `.dbinfo`, `.dbsize`, `.read`, `.import file csv`, `.import sqlite`, `.dump --schema-only`, and a bare `SELECT` statement.

Four of them answer with a message or a table of their own. `.read` answers `SQL statements from <file_path> executed successfully.` and `.import sqlite` answers `Data imported successfully into table '<table_name>'.` `.dbsize` answers with a one-column table headed `size_in_mb`, and `.dbinfo` answers with an Attribute and Value table carrying Database ID, Database Name, Status, Active, Last Modified, Last Editor, and Product Version.

The argument forms of the other import sources, `mysql`, `postgres`, `kaggle`, and `turso`, come from the `help .import` text of the shell itself.

---

## Related resources

- [Install the EdgeSQL Shell](/en/documentation/guides/application-development/data/install-edge-sql-shell.md): The clone, the virtual environment, and the requirements that put the shell on your machine.
- [Import data with the EdgeSQL Shell](/en/documentation/guides/application-development/data/import-data-sql-database.md): The steps that load a file into a table with the import command on this page.
- [Databases and queries](/en/documentation/platform/sql-database/databases-and-queries.md): The same databases and tables through the Azion API v4, with every field and every error.
- [How SQL Database works](/en/documentation/platform/sql-database/how-it-works.md): Where a database lives, and how a statement reaches the data the shell prints.
- [Troubleshooting](/en/documentation/platform/sql-database/troubleshooting.md): What to check when a command or a query does not answer the way this page describes.