rdbr 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 87da572f183e27a7a655a00bfe361c5f41b1c6804839d70937dffbc78f43ecd2
+  data.tar.gz: 05bc097aa41fd2fbdd8514013cbcca12c6ee113e1d5aaee98f469ff8710976c5
+SHA512:
+  metadata.gz: a0bba4640c5e90eca6058d6213e8c3b95d119992af39d12bee882b7118a38eb0e6a348fee053c8da41effad5d3067dfe75d01caa6f2eb1413678d015564c82ab
+  data.tar.gz: 76ff18c1b73aa3036eeda5434ea024c89c96e0f4d363684e019eb06258bc0c4c0eeb56193af5089673d97fb6d7008f1ad3eff8176fc56573fdd94cef8b4d5abd

data/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+RDBr follows [Semantic Versioning](https://semver.org/). Until version 1.0,
+minor releases may change public interfaces with an accompanying migration note.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-25
+
+First public release.
+
+- Browse PostgreSQL, SQLite, MySQL, and MariaDB tables and views through a
+  standalone, read-only web interface.
+- Inspect table definitions, row counts, keys, relationships, and a searchable,
+  interactive database diagram.
+- Search, sort, paginate, filter, and group records, with date-range controls
+  and persistent column preferences.
+- Follow declared and confidently inferred relationships, including
+  many-to-many associations and their junction records.
+- Navigate records using inferred human-readable identities while preserving
+  filters, pagination, and wide-table scroll position.
+- Present JSON, long text, arrays, binary values, identifiers, vectors, spatial
+  values, ranges, and other specialised types with suitable viewing and
+  clipboard controls.
+- Provide default and dark themes with shared theme-aware components.
+- Protect database access with read-only sessions and requests, bounded query
+  time and result sizes, and loopback-only serving by default.
+- Open the browser automatically when the server is ready, with `--no-open` for
+  headless and manually managed environments.
+- Include a deterministic online-shop demonstration for SQLite, PostgreSQL, and
+  MariaDB.
+- Test supported Ruby and database versions in CI and publish through RubyGems
+  trusted publishing.
+
+[Unreleased]: https://github.com/andrewtblake/rdbr/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/andrewtblake/rdbr/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Blake
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,155 @@
+# 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:
+
+```sh
+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:
+
+```text
+rdbr serve [--database-url URL] [--host HOST] [--port PORT] [--no-open]
+```
+
+Write a description of the database structure to standard output:
+
+```text
+rdbr inspect [--database-url URL]
+```
+
+Show the installed version:
+
+```text
+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:
+
+```sh
+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`](demo/README.md) for those instructions.
+
+## Browse a database
+
+Prefer the `DATABASE_URL` environment variable so credentials are not placed in
+command history:
+
+```sh
+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:
+
+```sh
+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:
+
+```sh
+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:
+
+```text
+--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.