rdbr 0.1.0

data/demo/seed.rb

@@ -0,0 +1,270 @@
+require 'active_record'
+require 'date'
+require 'fileutils'
+require 'json'
+require 'uri'
+
+module RDBrDemo
+  module_function
+
+  FIRST_NAMES = %w[Aisha Alice Amelia Daniel Eleanor Farah George Grace Hannah Isaac James Maya Noah Priya Thomas
+                   Yusuf].freeze
+  LAST_NAMES = %w[Ahmed Blake Chen Davies Evans Foster Garcia Hughes Ibrahim Jones Khan Morgan Patel Reed Singh
+                  Wilson].freeze
+  CITIES = [ 'Bath', 'Belfast', 'Birmingham', 'Bristol', 'Cardiff', 'Edinburgh', 'Leeds', 'London',
+             'Manchester' ].freeze
+  CATEGORIES = [ 'Books', 'Garden', 'Home', 'Kitchen', 'Office', 'Outdoors', 'Toys', 'Travel' ].freeze
+  PRODUCT_ADJECTIVES = %w[Compact Everyday Foldable Lightweight Modular Recycled Reusable Softwood].freeze
+  PRODUCT_NOUNS = [
+    'Backpack', 'Basket', 'Blanket', 'Bottle', 'Desk lamp', 'Journal', 'Plant pot', 'Puzzle',
+    'Shelf', 'Storage box', 'Travel mug', 'Utensil set'
+  ].freeze
+  TAGS = [ 'bestseller', 'compact', 'eco-friendly', 'gift', 'handmade', 'new', 'outdoor', 'recycled',
+           'travel', 'warranty' ].freeze
+
+  class Category < ActiveRecord::Base; end
+  class Product < ActiveRecord::Base; end
+  class Tag < ActiveRecord::Base; end
+  class ProductTag < ActiveRecord::Base; end
+  class Customer < ActiveRecord::Base; end
+  class Address < ActiveRecord::Base; end
+  class Order < ActiveRecord::Base; end
+  class OrderItem < ActiveRecord::Base; end
+  class Shipment < ActiveRecord::Base; end
+
+  def run
+    database_url = ENV.fetch('DEMO_DATABASE_URL', default_sqlite_url)
+    validate_target!(database_url)
+    prepare_sqlite_directory(database_url)
+    ActiveRecord::Base.establish_connection(database_url)
+    rebuild_schema
+    seed_records
+    puts "Seeded RDBr demonstration database at #{sanitized_target(database_url)}"
+  ensure
+    ActiveRecord::Base.connection_pool.disconnect! if ActiveRecord::Base.connected?
+  end
+
+  def rebuild_schema
+    ActiveRecord::Schema.define do
+      %i[shipments order_items orders addresses customers product_tags tags products categories].each do |table|
+        drop_table table, if_exists: true
+      end
+
+      create_table(:categories){|table| table.string :name, null: false, index: { unique: true } }
+      create_table :products do |table|
+        table.references :category, null: false, foreign_key: true
+        table.string :sku, null: false, index: { unique: true }
+        table.string :name, null: false
+        table.text :description, null: false
+        table.decimal :price, precision: 10, scale: 2, null: false
+        table.integer :stock, null: false
+        table.boolean :active, null: false, default: true
+        table.json :details
+        table.timestamps null: false
+      end
+      create_table(:tags){|table| table.string :name, null: false, index: { unique: true } }
+      create_table :product_tags do |table|
+        table.references :product, null: false, foreign_key: true
+        table.references :tag, null: false, foreign_key: true
+        table.index [ :product_id, :tag_id ], unique: true
+      end
+      create_table :customers do |table|
+        table.string :first_name, null: false
+        table.string :last_name, null: false
+        table.string :email, null: false, index: { unique: true }
+        table.string :phone
+        table.date :joined_on, null: false
+        table.timestamps null: false
+      end
+      create_table :addresses do |table|
+        table.references :customer, null: false, foreign_key: true
+        table.string :label, null: false
+        table.string :line_1, null: false
+        table.string :line_2
+        table.string :city, null: false
+        table.string :postcode, null: false
+        table.string :country_code, null: false, limit: 2
+        table.timestamps null: false
+      end
+      create_table :orders do |table|
+        table.references :customer, null: false, foreign_key: true
+        table.references :shipping_address, null: false, foreign_key: { to_table: :addresses }
+        table.string :number, null: false, index: { unique: true }
+        table.string :status, null: false
+        table.date :ordered_on, null: false
+        table.decimal :total, precision: 12, scale: 2, null: false
+        table.json :preferences
+        table.timestamps null: false
+      end
+      create_table :order_items do |table|
+        table.references :order, null: false, foreign_key: true
+        table.references :product, null: false, foreign_key: true
+        table.integer :quantity, null: false
+        table.decimal :unit_price, precision: 10, scale: 2, null: false
+        table.decimal :discount, precision: 5, scale: 2, null: false, default: 0
+        table.index [ :order_id, :product_id ], unique: true
+      end
+      create_table :shipments do |table|
+        table.references :order, null: false, foreign_key: true, index: { unique: true }
+        table.string :carrier, null: false
+        table.string :tracking_number, index: { unique: true }
+        table.date :dispatched_on
+        table.date :delivered_on
+        table.timestamps null: false
+      end
+    end
+  end
+
+  def seed_records
+    now = Time.utc(2026, 7, 21, 10, 30)
+    Category.insert_all!(CATEGORIES.map{|name| { name: name } })
+    Tag.insert_all!(TAGS.map{|name| { name: name } })
+    seed_products(now)
+    seed_product_tags
+    seed_customers(now)
+    seed_addresses(now)
+    seed_orders(now)
+    seed_shipments(now)
+  end
+
+  def seed_products(now)
+    category_ids = Category.order(:id).pluck(:id)
+    rows = 80.times.map do |index|
+      name = "#{PRODUCT_ADJECTIVES[index % PRODUCT_ADJECTIVES.length]} " \
+             "#{PRODUCT_NOUNS[(index * 5) % PRODUCT_NOUNS.length]}"
+      {
+        category_id: category_ids[index % category_ids.length],
+        sku: format('RDBR-%04d', 1001 + index),
+        name: "#{name} #{index + 1}",
+        description: "#{name} made for an ordinary demonstration shop. " * (2 + (index % 5)),
+        price: 4.95 + (index * 2.35), stock: (index * 13) % 121, active: (index % 11) != 0,
+        details: JSON.generate(
+          colour: %w[blue green natural red yellow][index % 5],
+          material: %w[canvas ceramic cotton paper wood][index % 5],
+          weight_grams: 150 + (index * 17)
+        ),
+        created_at: now - (index * 86_400), updated_at: now - (index * 1_800)
+      }
+    end
+    Product.insert_all!(rows)
+  end
+
+  def seed_product_tags
+    tag_ids = Tag.order(:id).pluck(:id)
+    rows = Product.order(:id).flat_map.with_index do |product, index|
+      [ index % tag_ids.length, (index * 3 + 1) % tag_ids.length ].uniq.map do |tag_index|
+        { product_id: product.id, tag_id: tag_ids[tag_index] }
+      end
+    end
+    ProductTag.insert_all!(rows)
+  end
+
+  def seed_customers(now)
+    rows = 45.times.map do |index|
+      first_name = FIRST_NAMES[index % FIRST_NAMES.length]
+      last_name = LAST_NAMES[(index * 3) % LAST_NAMES.length]
+      {
+        first_name: first_name, last_name: last_name,
+        email: "#{first_name}.#{last_name}.#{index}@example.test".downcase,
+        phone: index.even? ? format('+44 20 7%<area>03d %<number>04d', area: 100 + index, number: 1000 + index) : nil,
+        joined_on: Date.new(2023 + (index % 4), 1 + ((index * 5) % 12), 1 + ((index * 7) % 24)),
+        created_at: now - (index * 172_800), updated_at: now - (index * 3_600)
+      }
+    end
+    Customer.insert_all!(rows)
+  end
+
+  def seed_addresses(now)
+    rows = Customer.order(:id).flat_map.with_index do |customer, index|
+      count = (index % 3).zero? ? 2 : 1
+      count.times.map do |offset|
+        {
+          customer_id: customer.id, label: offset.zero? ? 'Home' : 'Work',
+          line_1: "#{12 + index + offset} #{%w[Oak Station Market Garden][index % 4]} Street",
+          line_2: (index % 4).zero? ? "Flat #{1 + (index % 9)}" : nil,
+          city: CITIES[(index + offset) % CITIES.length],
+          postcode: format('AB%<area>d %<number>dCD', area: 1 + (index % 9), number: 1 + (index % 8)),
+          country_code: 'GB', created_at: now - (index * 86_400), updated_at: now - (index * 2_400)
+        }
+      end
+    end
+    Address.insert_all!(rows)
+  end
+
+  def seed_orders(now)
+    products = Product.order(:id).to_a
+    135.times do |index|
+      customer = Customer.order(:id).offset(index % Customer.count).first
+      customer_addresses = Address.where(customer_id: customer.id)
+      address = customer_addresses.order(:id).offset(index % customer_addresses.count).first
+      ordered_on = Date.new(2025 + (index % 2), 1 + ((index * 5) % 12), 1 + ((index * 7) % 24))
+      status = %w[awaiting_payment processing dispatched delivered cancelled][index % 5]
+      items = (2 + (index % 4)).times.map do |offset|
+        product = products[(index * 7 + offset * 11) % products.length]
+        quantity = 1 + ((index + offset) % 4)
+        discount = ((index + offset) % 9).zero? ? 10 : 0
+        { product: product, quantity: quantity, unit_price: product.price, discount: discount }
+      end
+      total = items.sum{|item| item[:unit_price] * item[:quantity] * (1 - item[:discount] / 100.to_d) }
+      order = Order.create!(
+        customer_id: customer.id, shipping_address_id: address.id, number: format('ORD-%06d', 10_001 + index),
+        status: status, ordered_on: ordered_on, total: total,
+        preferences: JSON.generate(
+          gift_wrap: (index % 8).zero?,
+          delivery_note: (index % 6).zero? ? 'Leave in a safe place' : nil
+        ),
+        created_at: now - (index * 21_600), updated_at: now - (index * 1_200)
+      )
+      OrderItem.insert_all!(
+        items.map do |item|
+          {
+            order_id: order.id, product_id: item[:product].id, quantity: item[:quantity],
+            unit_price: item[:unit_price], discount: item[:discount]
+          }
+        end
+      )
+    end
+  end
+
+  def seed_shipments(now)
+    carriers = [ 'Parcel Post', 'Swift Delivery', 'Town Courier' ]
+    rows = Order.where(status: %w[dispatched delivered]).order(:id).map.with_index do |order, index|
+      dispatched_on = order.ordered_on + 2 + (index % 3)
+      delivered = order.status == 'delivered'
+      {
+        order_id: order.id, carrier: carriers[index % carriers.length],
+        tracking_number: format('TRACK%08d', 50_000 + index),
+        dispatched_on: dispatched_on, delivered_on: delivered ? dispatched_on + 1 + (index % 3) : nil,
+        created_at: now - (index * 14_400), updated_at: now - (index * 900)
+      }
+    end
+    Shipment.insert_all!(rows)
+  end
+
+  def validate_target!(database_url)
+    return if database_url == default_sqlite_url
+
+    uri = URI.parse(database_url)
+    safe_host = [ 'localhost', '127.0.0.1' ].include?(uri.host)
+    safe_database = uri.path == '/rdbr_demo'
+    return if safe_host && safe_database
+
+    abort 'Refusing to rebuild a database unless it is the local rdbr_demo database'
+  rescue URI::InvalidURIError
+    abort 'DEMO_DATABASE_URL must be a valid local rdbr_demo URL'
+  end
+
+  def default_sqlite_url
+    "sqlite3:#{File.expand_path('../tmp/rdbr-demo.sqlite3', __dir__)}"
+  end
+
+  def prepare_sqlite_directory(database_url)
+    FileUtils.mkdir_p(File.dirname(database_url.delete_prefix('sqlite3:'))) if database_url.start_with?('sqlite3:')
+  end
+
+  def sanitized_target(database_url)
+    database_url.sub(%r{://[^@]+@}, '://***@')
+  end
+end
+
+RDBrDemo.run if $PROGRAM_NAME == __FILE__

data/demo/smoke.rb

@@ -0,0 +1,13 @@
+require 'rdbr'
+
+database_url = ENV.fetch('DEMO_DATABASE_URL') do
+  "sqlite3:#{File.expand_path('../tmp/rdbr-demo.sqlite3', __dir__)}"
+end
+catalog = RDBr::Catalog.read(database_url: database_url)
+query = RDBr::Query.build(database_url: database_url, catalog: catalog)
+namespace = catalog.namespaces.find{|candidate| candidate.relation('products') } or abort 'products table not found'
+page = query.page(namespace: namespace.name, relation: 'products', per_page: 10, include_total: true)
+abort "expected 80 products, found #{page.total_count}" unless page.total_count == 80
+
+puts "Verified #{catalog.adapter} catalog and row queries against #{catalog.name}"
+query.disconnect

data/docs/RELEASING.md

@@ -0,0 +1,30 @@
+# Releasing RDBr
+
+RDBr uses semantic versions and RubyGems trusted publishing. No long-lived
+RubyGems API key belongs in GitHub secrets.
+
+## One-time setup
+
+Create a pending trusted publisher in your RubyGems.org account with:
+
+- gem name: `rdbr`;
+- repository owner: `andrewtblake`;
+- repository name: `rdbr`;
+- workflow filename: `release.yml`; and
+- GitHub environment: `release`.
+
+Protect the `release` environment in GitHub if a manual approval before
+publication is desirable.
+
+## Release checklist
+
+1. Move the relevant `CHANGELOG.md` entries from Unreleased into a dated version.
+2. Set `RDBr::VERSION` to that version.
+3. Run `bundle exec rake` and `bundle exec rake build`.
+4. Commit and push the release preparation.
+5. Create and push an annotated `vVERSION` tag.
+
+The tag starts `release.yml`, which verifies that the tag and gem version agree,
+runs the full default checks, builds the gem, and publishes it using a short-lived
+OpenID Connect credential. Publishing is deliberately impossible from an
+untagged branch build.

data/docs/VALUE_PRESENTATION.md

@@ -0,0 +1,54 @@
+# Value presentation
+
+RDBr chooses an HTML presentation from discovered column metadata and the
+returned value. This remains a zero-configuration policy: it does not require
+application models, type registrations, or per-database settings.
+
+Compact scalar values stay inline. Values that would dominate a row, are hard
+to scan, or are unsafe to emit as text use a **View** control, a short summary,
+and a clipboard button. The shared popover is keyboard accessible, remains open
+while its content is scrolled, and constrains both its height and width.
+
+## Recognized families
+
+| Family | Recognition | Presentation |
+| --- | --- | --- |
+| Identifiers | UUID types and UUID-like names/values | View and copy controls |
+| JSON/JSONB | Native metadata, including nested serialized JSON | Pretty-printed document view with copy |
+| Vectors | PostgreSQL `vector`, `halfvec`, `sparsevec`; MariaDB vectors; inferred bit embeddings | Dimension summary, view, and copy |
+| Arrays | PostgreSQL array metadata | Small one-dimensional arrays inline; large or multidimensional arrays deferred |
+| Binary | `bytea`, binary, and blob families | Byte count; Base64 view and copy so arbitrary bytes never enter the page |
+| Key/value and documents | PostgreSQL `hstore` and XML | Entry count or XML root summary with exact-source view and copy |
+| Bit strings | `bit` and `varbit` not inferred as embeddings | Bit count, view, and copy |
+| Full-text search | PostgreSQL `tsvector` and `tsquery` | Lexeme or term count, view, and copy |
+| Spatial | PostgreSQL geometric types, PostGIS, and MySQL/MariaDB geometry | Geometry/SRID summary for text; byte count and Base64 for binary WKB |
+| Ranges | PostgreSQL range and multirange types | Range type, empty state, or contained-range count |
+| Unfamiliar types | Extension and custom types without another match | Short values inline; values over 160 characters deferred with their SQL type |
+
+Long ordinary text uses its existing preview and full-text dialog. Timestamps
+are normalized to `YYYY-MM-DD HH:MM:SS`. Nulls remain visibly distinct from
+empty strings.
+
+## Precedence
+
+Some physical representations are ambiguous, so classification is deliberately
+ordered:
+
+1. inferred vectors before ordinary arrays or bit strings;
+2. spatial metadata before generic binary detection, preserving WKB context;
+3. binary normalization before generic structured-value rendering;
+4. known document, search, and range families before the unfamiliar-type
+   fallback; and
+5. identifier inference after type-specific presentation.
+
+Related-record labels take precedence over all of these in table cells because
+the relationship supplies the most useful navigation. Filtering still uses the
+underlying stored key.
+
+## Safety and limits
+
+All values and summaries are HTML-escaped. Binary content is never decoded into
+the document as arbitrary text. RDBr does not execute, deserialize, or render
+XML, spatial data, or custom extension values; it presents their textual form or
+a Base64 representation. Query-layer value limits apply before presentation,
+so the popover does not bypass `--max-value-bytes` truncation safeguards.

data/exe/rdbr

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'rdbr'
+
+exit RDBr::CLI.run(ARGV)

data/lib/rdbr/access/read_only.rb

@@ -0,0 +1,61 @@
+module RDBr
+  module Access
+    class ReadOnly
+      MODE = 'read-only'.freeze
+      READ_STATEMENT = /\A\s*SELECT\b/i
+
+      attr_reader :statement_timeout
+
+      def initialize(statement_timeout: 5000)
+        @statement_timeout = positive_integer(statement_timeout, 'statement timeout')
+      end
+
+      def mode
+        MODE
+      end
+
+      def allow_http_method?(method)
+        [ 'GET', 'HEAD' ].include?(method)
+      end
+
+      def validate_statement!(sql)
+        return if READ_STATEMENT.match?(sql.to_s)
+
+        raise Query::AccessViolationError, 'Only read-only SELECT statements are permitted'
+      end
+
+      def configure(connection, adapter_name:, mariadb: false)
+        case adapter_name
+        when 'postgresql', 'postgis'
+          connection.execute('SET default_transaction_read_only = on')
+          connection.execute("SET statement_timeout = #{statement_timeout}")
+        when 'sqlite', 'sqlite3'
+          connection.execute('PRAGMA query_only = ON')
+          connection.execute("PRAGMA busy_timeout = #{statement_timeout}")
+        when 'mysql', 'mysql2', 'trilogy'
+          connection.execute('SET SESSION TRANSACTION READ ONLY')
+          configure_mysql_timeout(connection, mariadb)
+        else
+          raise ArgumentError, "unsupported query adapter: #{adapter_name}"
+        end
+      end
+
+      private
+
+      def configure_mysql_timeout(connection, mariadb)
+        if mariadb
+          connection.execute("SET SESSION max_statement_time = #{statement_timeout.fdiv(1000)}")
+        else
+          connection.execute("SET SESSION max_execution_time = #{statement_timeout}")
+        end
+      end
+
+      def positive_integer(value, label)
+        number = Integer(value)
+        raise ArgumentError, "#{label} must be positive" unless number.positive?
+
+        number
+      end
+    end
+  end
+end

data/lib/rdbr/access.rb

@@ -0,0 +1,6 @@
+require_relative 'access/read_only'
+
+module RDBr
+  module Access
+  end
+end

data/lib/rdbr/browser_launcher.rb

@@ -0,0 +1,71 @@
+require 'net/http'
+require 'rbconfig'
+require 'uri'
+
+module RDBr
+  class BrowserLauncher
+    READY_TIMEOUT = 10
+    RETRY_INTERVAL = 0.1
+    WILDCARD_HOSTS = [ '0.0.0.0', '::', '[::]' ].freeze
+
+    class << self
+      def open_when_ready(host:, port:, output: $stdout)
+        url = browser_url(host: host, port: port)
+        Thread.new do
+          Thread.current.report_on_exception = false
+          next unless wait_until_ready(url)
+
+          output.puts "Open RDBr at #{url}" unless launch(url)
+        end
+      end
+
+      def browser_url(host:, port:)
+        browser_host = WILDCARD_HOSTS.include?(host) ? '127.0.0.1' : host
+        URI::HTTP.build(host: browser_host, port: port, path: '/').to_s
+      end
+
+      private
+
+      def wait_until_ready(url)
+        health_uri = URI.join(url, '/health')
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + READY_TIMEOUT
+        loop do
+          return true if healthy?(health_uri)
+          return false if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+          sleep RETRY_INTERVAL
+        end
+      end
+
+      def healthy?(uri)
+        client = Net::HTTP.new(uri.hostname, uri.port)
+        client.open_timeout = RETRY_INTERVAL
+        client.read_timeout = RETRY_INTERVAL
+        client.get(uri.request_uri).is_a?(Net::HTTPSuccess)
+      rescue IOError, SystemCallError, Timeout::Error
+        false
+      end
+
+      def launch(url)
+        launch_commands(url).any? do |command|
+          pid = Process.spawn(*command, out: File::NULL, err: File::NULL)
+          Process.detach(pid)
+          true
+        rescue Errno::ENOENT
+          false
+        end
+      end
+
+      def launch_commands(url)
+        case RbConfig::CONFIG.fetch('host_os')
+        when /darwin/
+          [[ 'open', url ]]
+        when /mingw|mswin|cygwin/
+          [[ 'cmd', '/c', 'start', '', url ]]
+        else
+          [[ 'xdg-open', url ], [ 'gio', 'open', url ]]
+        end
+      end
+    end
+  end
+end

data/lib/rdbr/catalog/connection.rb

@@ -0,0 +1,68 @@
+module RDBr
+  module Catalog
+    class Connection
+      class Record < ActiveRecord::Base
+        self.abstract_class = true
+
+        def readonly?
+          true
+        end
+      end
+
+      def initialize(database_url)
+        @record_class = Record
+        @record_class.establish_connection(database_url)
+      rescue ActiveRecord::AdapterNotSpecified, ActiveRecord::AdapterNotFound, ArgumentError => e
+        raise ConnectionError, "Unable to configure database connection (#{e.class})"
+      end
+
+      def adapter_name
+        connection.adapter_name.downcase
+      rescue ActiveRecord::ActiveRecordError => e
+        raise ConnectionError, "Unable to connect to database (#{e.class})"
+      end
+
+      def database_version
+        connection.database_version
+      rescue ActiveRecord::ActiveRecordError => e
+        raise ConnectionError, "Unable to read database version (#{e.class})"
+      end
+
+      def database_product
+        connection.select_value('SELECT VERSION()')
+      rescue ActiveRecord::ActiveRecordError => e
+        raise ConnectionError, "Unable to read database product (#{e.class})"
+      end
+
+      def select_all(sql)
+        connection.select_all(sql).to_a
+      rescue ActiveRecord::ActiveRecordError => e
+        raise ConnectionError, "Database catalog query failed (#{e.class})"
+      end
+
+      def select_all_optional(sql)
+        connection.select_all(sql).to_a
+      rescue ActiveRecord::StatementInvalid
+        []
+      rescue ActiveRecord::ActiveRecordError => e
+        raise ConnectionError, "Database catalog query failed (#{e.class})"
+      end
+
+      delegate :quote, to: :connection
+
+      def quote_identifier(identifier)
+        connection.quote_column_name(identifier.to_s)
+      end
+
+      def disconnect
+        @record_class.connection_pool.disconnect!
+      end
+
+      private
+
+      def connection
+        @record_class.connection
+      end
+    end
+  end
+end

data/lib/rdbr/catalog/errors.rb

@@ -0,0 +1,12 @@
+module RDBr
+  module Catalog
+    class Error < StandardError
+    end
+
+    class ConnectionError < Error
+    end
+
+    class UnsupportedAdapterError < Error
+    end
+  end
+end