RDBr

RDBr is a read-only relational database browser.

Give it a PostgreSQL, SQLite, MySQL, or MariaDB connection and it opens a local web interface where you can:

  • browse tables and views;
  • inspect columns, types, keys, and relationships;
  • search, sort, filter, and paginate records;
  • follow links between associated records;
  • group values and see their counts;
  • view a diagram of the database structure; and
  • inspect JSON, long text, dates, binary data, and other database values.

RDBr is useful when you want to explore an unfamiliar database, investigate particular records, understand how tables relate, or answer a question without writing SQL.

Installation

RDBr requires Ruby 3.2 or newer. Install the gem together with the driver for the database you intend to browse:

gem install rdbr pg          # PostgreSQL
gem install rdbr sqlite3     # SQLite
gem install rdbr mysql2      # MySQL or MariaDB

Applications using Bundler can use bundle add rdbr pg, replacing pg with the required driver. Database drivers are optional so installing RDBr does not require client libraries for every supported database.

The mysql2 driver requires MySQL or MariaDB client development headers; on Debian/Ubuntu these are provided by libmariadb-dev or libmysqlclient-dev. Building pg from source may similarly require libpq-dev.

Commands

Start the browser:

rdbr serve [--database-url URL] [--host HOST] [--port PORT] [--no-open]

Write a description of the database structure to standard output:

rdbr inspect [--database-url URL]

Show the installed version:

rdbr version

Both serve and inspect accept --include-system. Run rdbr --help for the complete list of options.

Try the demonstration

The included demo is a fictional online shop with customers, addresses, products, categories, tags, orders, order items, and shipments. It is ready to run with SQLite:

bundle install
bundle exec ruby demo/seed.rb
bundle exec rdbr serve --database-url sqlite3:$(pwd)/tmp/rdbr-demo.sqlite3

Then open http://127.0.0.1:9292.

The demo can also run on PostgreSQL or MariaDB. See demo/README.md for those instructions.

Browse a database

Prefer the DATABASE_URL environment variable so credentials are not placed in command history:

export DATABASE_URL='postgresql://user:password@host/database'
rdbr serve

RDBr opens http://127.0.0.1:9292 in your default browser when the server is ready. Pass --no-open when running without a graphical browser or when you want to open it yourself.

A database URL can instead be supplied directly:

rdbr serve --database-url postgresql://user:password@host/database
rdbr serve --database-url sqlite3:/home/user/application.sqlite3
rdbr serve --database-url mysql2://readonly:password@localhost/application

Use inspect when you want the database structure as JSON rather than the web interface:

rdbr inspect --database-url postgresql://user:password@host/database > catalog.json

System schemas are hidden by default. Pass --include-system if you need to see them.

Progressive drill-down

You can begin with a whole table and narrow it directly from the records in front of you. For example, in the demonstration database you can:

  • open products, click a category, and continue with only products in that category;
  • search products for “travel”, sort the matches by price, and group them by their active value;
  • open a customer, follow the customer's orders, then inspect the individual order items and products;
  • open an order item to see the quantity, unit price, and discount recorded on the association itself; or
  • open the database diagram, find orders, and inspect its columns and links to customers, addresses, order items, and shipments.

Filters remain visible as you browse and can be removed individually. Following a record and returning to its table preserves the list you came from.

Read-only by design

RDBr does not provide editing or arbitrary SQL. It rejects write requests and uses read-only database sessions where the database supports them. It also limits query duration, page size, and the amount returned for an individual value.

The server listens only on the local computer by default. These safeguards are not a substitute for database permissions: use a dedicated account with SELECT access only, especially for production databases.

Configuration

The most commonly useful server options are:

--statement-timeout MS
--pool-size COUNT
--checkout-timeout MS
--max-value-bytes BYTES
--max-results COUNT

They can also be set with RDBR_STATEMENT_TIMEOUT, RDBR_POOL_SIZE, RDBR_CHECKOUT_TIMEOUT, RDBR_MAX_VALUE_BYTES, and RDBR_MAX_RESULTS. Command-line options take precedence over environment variables.