Skip to main content
bunny.net Database 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.

​
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 install -g @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

FlagDescription
--token <token>Auth token for the database
--mode <mode>Output mode: default, table, json, csv, markdown
--unmaskShow sensitive column values unmasked
--timingShow query execution timing
--helpShow 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:
ModeDescription
defaultBorderless table with headers
tableBordered ASCII table
jsonJSON array of row objects
csvComma-separated values
markdownGitHub-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:
CommandDescription
.tablesList all tables
.describe TABLEShow column details
.schema [TABLE]Show CREATE statements
.indexes [TABLE]List indexes
.fk TABLEShow foreign keys for a table
.erShow entity-relationship overview
.count TABLECount rows
.size TABLEShow table stats
.truncate TABLEDelete all rows from a table
.dump [TABLE]Dump schema and data as SQL
.read FILEExecute SQL from a file
.mode [MODE]Set output mode
.timingToggle query timing
.maskEnable sensitive column masking
.unmaskDisable sensitive column masking
.save NAMESave the last query as a named view
.view NAMEExecute a saved view
.viewsList all saved views
.unsave NAMEDelete a saved view
.clear-historyClear command history
.helpShow available commands
.quit / .exitExit 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: 
→  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.