Database Shell

Connect to Bunny Database using the interactive SQL shell

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

Bunny Database is currently in Public Preview. Features and APIs may evolve during this period.

Already using the Bunny CLI? The same shell is built in as bunny db shell, which resolves your database and credentials automatically:

bunny db shell                                    # interactive REPL
bunny db shell -e "SELECT * FROM users LIMIT 10"  # execute and exit

See bunny 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.

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

   You should store these as environment variables to keep them secure.

2. Install the Database Shell

   Install the Database Shell globally using npm:

   npm

   npm install -g @bunny.net/database-shell
   

   pnpm add -g @bunny.net/database-shell
   

   yarn global add @bunny.net/database-shell
   
3. Connect to your database

   Start an interactive shell session:

   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:

   bsql
   

   See Authorization for more on environment variables.

4. Execute a query

   Run a SQL query directly in the shell:

   SELECT * FROM users;
   

   You can also execute a query without entering interactive mode:

   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:

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

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-mail]).

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:

→  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 installed, bunny db studio opens a visual database explorer in your browser for the resolved database:

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

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 for the full command reference.