> ## Documentation Index
> Fetch the complete documentation index at: https://bunny.net/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Database Shell

> Connect to Bunny Database using the interactive SQL shell

![bunny.net Database Shell](https://mintcdn.com/bunnynet-cb9733c2/GYo51EPI6zuebYhU/images/database/bunny-database-shell.png?fit=max\&auto=format\&n=GYo51EPI6zuebYhU\&q=85\&s=dc4cc7d7f4b50deb5cb5f4c93981df6a)

The Bunny Database Shell (`bsql`) is a standalone, interactive SQL shell for querying and managing your database from the terminal. It supports dot-commands, multiple output formats, sensitive column masking, and persistent history.

In this quickstart you will learn how to:

* Install the Database Shell
* Connect to a remote Bunny Database
* Execute queries interactively and non-interactively

> [!NOTE]
>
> Bunny Database is currently in [Public
> Preview](https://bunny.net/docs/product-release-stages.md#stage-2-public-preview). Features and APIs
> may evolve during this period.

> [!TIP]
>
> Already using the [Bunny CLI](https://bunny.net/docs/cli/quickstart.md)? The same shell is built in as
> `bunny db shell`, which resolves your database and credentials automatically:
>
> ```bash theme={null}
> bunny db shell                                    # interactive REPL
> bunny db shell -e "SELECT * FROM users LIMIT 10"  # execute and exit
> ```
>
> See [`bunny db`](https://bunny.net/docs/cli/commands/db) for the full command reference.

## Quickstart

**1. Retrieve database credentials**

You will need an existing database to continue. If you don't have one, [create one](https://bunny.net/docs/database/quickstart.md).

Navigate to **Dashboard > Edge Platform > Database > \[Select Database] > Access** to find your database URL and generate an access token.

> [!NOTE]
>
> You should store these as environment variables to keep them secure.

**2. Install the Database Shell**

Install the Database Shell globally using npm:

```bash npm theme={null}
npm install -g @bunny.net/database-shell
```

```bash pnpm theme={null}
pnpm add -g @bunny.net/database-shell
```

```bash yarn theme={null}
yarn global add @bunny.net/database-shell
```

**3. Connect to your database**

Start an interactive shell session:

```bash theme={null}
bsql libsql://<your-database>.lite.bunnydb.net --token <your-token>
```

If you store your credentials in a `.env` file as `BUNNY_DATABASE_URL` and `BUNNY_DATABASE_AUTH_TOKEN`, you can connect without passing any flags:

```bash theme={null}
bsql
```

See [Authorization](https://bunny.net/docs/database/connect/authorization.md) for more on environment variables.

**4. Execute a query**

Run a SQL query directly in the shell:

```sql theme={null}
SELECT * FROM users;
```

You can also execute a query without entering interactive mode:

```bash theme={null}
bsql libsql://<your-database>.lite.bunnydb.net --token <your-token> "SELECT * FROM users"
```

## CLI Flags

| Flag | Description |
| - | - |
| `--token <token>` | Auth token for the database |
| `--mode <mode>` | Output mode: `default`, `table`, `json`, `csv`, `markdown` |
| `--unmask` | Show sensitive column values unmasked |
| `--timing` | Show query execution timing |
| `--help` | Show help |

## Execute a SQL file

You can execute a `.sql` file directly from the command line:

```bash theme={null}
bsql libsql://<your-database>.lite.bunnydb.net --token <your-token> seed.sql
```

## Output modes

Change the output format using the `--mode` flag or the `.mode` dot-command inside an interactive session:

| Mode | Description |
| - | - |
| `default` | Borderless table with headers |
| `table` | Bordered ASCII table |
| `json` | JSON array of row objects |
| `csv` | Comma-separated values |
| `markdown` | GitHub-flavored pipe table |

```bash theme={null}
bsql libsql://<your-database>.lite.bunnydb.net --token <your-token> "SELECT * FROM users" --mode json
```

## Dot-commands

The following dot-commands are available inside an interactive session:

| Command | Description |
| - | - |
| `.tables` | List all tables |
| `.describe TABLE` | Show column details |
| `.schema [TABLE]` | Show CREATE statements |
| `.indexes [TABLE]` | List indexes |
| `.fk TABLE` | Show foreign keys for a table |
| `.er` | Show entity-relationship overview |
| `.count TABLE` | Count rows |
| `.size TABLE` | Show table stats |
| `.truncate TABLE` | Delete all rows from a table |
| `.dump [TABLE]` | Dump schema and data as SQL |
| `.read FILE` | Execute SQL from a file |
| `.mode [MODE]` | Set output mode |
| `.timing` | Toggle query timing |
| `.mask` | Enable sensitive column masking |
| `.unmask` | Disable sensitive column masking |
| `.save NAME` | Save the last query as a named view |
| `.view NAME` | Execute a saved view |
| `.views` | List all saved views |
| `.unsave NAME` | Delete a saved view |
| `.clear-history` | Clear command history |
| `.help` | Show available commands |
| `.quit` / `.exit` | Exit the shell |

## Sensitive column masking

Columns matching patterns like `password`, `secret`, `api_key`, `auth_token`, and `ssn` are masked by default. Email columns are partially masked (e.g. `a****e@example.com`).

Toggle masking with `.mask` / `.unmask` in interactive mode, or pass `--unmask` as a CLI flag.

## Saved views

Save frequently used queries as named views to recall them later:

```sql theme={null}
→  SELECT name, count(*) as orders FROM users JOIN orders USING (user_id) GROUP BY name ORDER BY orders DESC LIMIT 10;

→  .save top-customers
✓ View "top-customers" saved.

→  .view top-customers
```

Manage saved views with `.views`, `.view NAME`, and `.unsave NAME`.

## Browse tables in your browser

If you have the [Bunny CLI](https://bunny.net/docs/cli/quickstart.md) installed, `bunny db studio` opens a visual database explorer in your browser for the resolved database:

```bash theme={null}
bunny db studio            # auto-detect database and open the browser
bunny db studio --port 3000 # use a custom port
bunny db studio --no-open   # start the server without opening a browser
```

> [!NOTE]
>
> `bunny db studio` is experimental and provides a view-only table browser. Use
> `bunny db shell` to run queries or modify data.

Like `bunny db shell`, it resolves the database and credentials automatically, generating a short-lived token when one isn't already available. The server runs until you stop it with `Ctrl+C`. See [`bunny db`](https://bunny.net/docs/cli/commands/db) for the full command reference.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.