rails-schema 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ed18d27750908c4973c29dd17904a623b056b9636f7a61da0a15d710575327b
-  data.tar.gz: 88f5fe0cb1c8bc618f138afaf11792733324bdca5a27bbc21ae179f83277e173
+  metadata.gz: 97d15de972c2e7c9c3d9e395d0b610b95806e7f6ef5729eed214f5cb7723bb61
+  data.tar.gz: 7edc0d7d8cd246ad80cc2dd54936a0c9802b662476400f095d076bed651d6472
 SHA512:
-  metadata.gz: a5c174cade562f7b8026c4410fd2034a82fe325936ac32770e3604e7f3e68cea63f23364e48f929574993d3f7cf26f916b89c380459ae53537f81b39efd406c6
-  data.tar.gz: 9cc8c949efa541ffe58d0227c3ec0ae540529518bed58993530ea6890d41f5a43a0e6bda3533db7862e8cc2c0da6acaead494686f1f8f111623ab6f7fc873658
+  metadata.gz: 3ba7bf7dd2ac15538fa4a9f14b2772c4065fd6dc51a5325e1863e4d4e83838cdaa14497f5b4a4f6d7ffcdc014fe03ba9e1f3464e722ef57f73a56d14314997f0
+  data.tar.gz: f41572f08a43be003061f2e47914ed36ed27b2718b10d0d3e238c9ca436ea3230ca7e61e5213acdbf50cab6f19b96506d5d1c8d0de33bc2831e2ab84181adac0

data/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.2] - 2026-02-22
+
+### Added
+
+- `StructureSqlParser` for extracting schema from `db/structure.sql` files
+- `schema_format` configuration option (`:ruby`, `:sql`, `:auto`)
+- `warn` messages to all silent rescue blocks in `AssociationReader` and `ColumnReader`
+
+## [0.1.1] - 2026-02-17
+
+### Added
+
+- ERD-style connections with crow's foot notation, directional indicators, and column-level attachment points
+
+### Changed
+
+- Refactored edge routing with cubic Bezier curves and improved self-referential association handling
+
+## [0.1.0] - 2026-02-15
+
+### Added
+
+- Initial release
+- Interactive HTML visualization of Rails database schema (force-directed ERD)
+- Model introspection: associations, columns, and schema file parsing
+- Self-contained single HTML file output (no external dependencies)
+- Searchable sidebar, click-to-focus, dark/light theme, keyboard shortcuts
+- Rake task (`rails_schema:generate`) and programmatic API
+- Configuration DSL: output path, title, theme, expand columns, exclude models

data/PROJECT.md

@@ -8,7 +8,7 @@
 
 **Name:** `rails-schema`
 **Module:** `Rails::Schema`
-**Version:** `0.1.0`
+**Version:** `0.1.2`
 
 Rails::Schema introspects a Rails app's models, associations, and database columns at runtime, then generates a single self-contained HTML file with an interactive, explorable entity-relationship diagram. No external server, no SaaS dependency — just one command and a browser.
 
@@ -43,7 +43,7 @@ Rails::Schema.generate(output: "docs/schema.html")
 
 | Layer | Responsibility | Key Classes |
 |---|---|---|
-| **Extractor** | Introspects Rails environment; collects models, columns, associations | `Rails::Schema::Extractor::ModelScanner`, `ColumnReader`, `AssociationReader`, `SchemaFileParser` |
+| **Extractor** | Introspects Rails environment; collects models, columns, associations | `Rails::Schema::Extractor::ModelScanner`, `ColumnReader`, `AssociationReader`, `SchemaFileParser`, `StructureSqlParser` |
 | **Transformer** | Normalizes extracted data into a serializable graph structure (nodes + edges + metadata) | `Rails::Schema::Transformer::GraphBuilder`, `Node`, `Edge` |
 | **Renderer** | Takes the graph data and injects it into an HTML/JS/CSS template using ERB | `Rails::Schema::Renderer::HtmlGenerator` |
 | **Railtie** | Provides the `rails_schema:generate` rake task | `Rails::Schema::Railtie` |
@@ -52,13 +52,23 @@ Rails::Schema.generate(output: "docs/schema.html")
 
 ```ruby
 def generate(output: nil)
-  schema_data = Extractor::SchemaFileParser.new.parse
+  schema_data = parse_schema
   models = Extractor::ModelScanner.new(schema_data: schema_data).scan
   column_reader = Extractor::ColumnReader.new(schema_data: schema_data)
   graph_data = Transformer::GraphBuilder.new(column_reader: column_reader).build(models)
   generator = Renderer::HtmlGenerator.new(graph_data: graph_data)
   generator.render_to_file(output)
 end
+
+def parse_schema
+  case configuration.schema_format
+  when :ruby then Extractor::SchemaFileParser.new.parse
+  when :sql  then Extractor::StructureSqlParser.new.parse
+  when :auto
+    data = Extractor::SchemaFileParser.new.parse
+    data.empty? ? Extractor::StructureSqlParser.new.parse : data
+  end
+end
 ```
 
 ---
@@ -68,8 +78,9 @@ end
 ### 3.1 Sources of Truth
 
 1. **`db/schema.rb` parsing** — `SchemaFileParser` parses the schema file line-by-line with regex to extract table names, column definitions (name, type, nullable, default), and primary key info. This is attempted first and used as a fast, database-free source.
-2. **ActiveRecord reflection API** — `AssociationReader` uses `Model.reflect_on_all_associations` for associations (`has_many`, `belongs_to`, `has_one`, `has_and_belongs_to_many`), including `:through` and `:polymorphic`.
-3. **`Model.columns`** — `ColumnReader` falls back to `model.columns` via ActiveRecord when a table is not found in schema_data.
+2. **`db/structure.sql` parsing** — `StructureSqlParser` parses SQL `CREATE TABLE` statements for projects using `config.active_record.schema_format = :sql`. Maps SQL types to Rails-friendly types, detects `NOT NULL`, `DEFAULT` values, and primary keys. Handles schema-qualified names (`public.users`), timestamp precision (`timestamp(6)`), and both quoted and unquoted identifiers.
+3. **ActiveRecord reflection API** — `AssociationReader` uses `Model.reflect_on_all_associations` for associations (`has_many`, `belongs_to`, `has_one`, `has_and_belongs_to_many`), including `:through` and `:polymorphic`.
+4. **`Model.columns`** — `ColumnReader` falls back to `model.columns` via ActiveRecord when a table is not found in schema_data.
 
 ### 3.2 Model Discovery
 
@@ -92,7 +103,19 @@ When `schema_data` is available, table existence is checked against parsed schem
 - Handles custom primary key types (`id: :uuid`, `id: :bigint`) and `id: false`
 - Skips index definitions
 
-### 3.4 Intermediate Data Format (JSON Graph)
+### 3.4 Structure SQL Parser
+
+`StructureSqlParser` provides database-free column extraction from SQL dumps:
+
+- Parses `CREATE TABLE` statements from `db/structure.sql`
+- Maps SQL types to Rails types (e.g. `character varying` → `string`, `bigint` → `bigint`, `timestamp without time zone` → `datetime`)
+- Handles schema-qualified table names (`public.users` → `users`)
+- Handles timestamp precision (`timestamp(6) without time zone`)
+- Detects primary keys from `CONSTRAINT ... PRIMARY KEY` and inline `PRIMARY KEY`
+- Extracts `NOT NULL`, `DEFAULT` values (strings, numbers, booleans)
+- Skips constraint lines (`CONSTRAINT`, `UNIQUE`, `CHECK`, `FOREIGN KEY`, etc.)
+
+### 3.5 Intermediate Data Format (JSON Graph)
 
 ```json
 {
@@ -195,6 +218,7 @@ Rails::Schema.configure do |config|
   config.title          = "Database Schema"      # Page title
   config.theme          = :auto                  # :light, :dark, :auto
   config.expand_columns = false                  # Start with columns expanded
+  config.schema_format  = :auto                  # :auto, :ruby, or :sql
 end
 ```
 
@@ -207,14 +231,15 @@ rails-schema/
 ├── lib/
 │   ├── rails/schema.rb                    # Entry point, configuration DSL, generate method
 │   └── rails/schema/
-│       ├── version.rb                     # VERSION = "0.1.0"
-│       ├── configuration.rb               # Config object (5 attributes)
+│       ├── version.rb                     # VERSION = "0.1.2"
+│       ├── configuration.rb               # Config object (6 attributes)
 │       ├── railtie.rb                     # Rails integration, rake task
 │       ├── extractor/
 │       │   ├── model_scanner.rb           # Discovers AR models
 │       │   ├── association_reader.rb      # Reads reflections
 │       │   ├── column_reader.rb           # Reads columns (schema_data or AR)
-│       │   └── schema_file_parser.rb      # Parses db/schema.rb
+│       │   ├── schema_file_parser.rb      # Parses db/schema.rb
+│       │   └── structure_sql_parser.rb   # Parses db/structure.sql
 │       ├── transformer/
 │       │   ├── graph_builder.rb           # Builds node/edge graph
 │       │   ├── node.rb                    # Value object
@@ -238,7 +263,8 @@ rails-schema/
 │       │   ├── model_scanner_spec.rb
 │       │   ├── column_reader_spec.rb
 │       │   ├── association_reader_spec.rb
-│       │   └── schema_file_parser_spec.rb
+│       │   ├── schema_file_parser_spec.rb
+│       │   └── structure_sql_parser_spec.rb
 │       ├── transformer/
 │       │   └── graph_builder_spec.rb
 │       └── renderer/
@@ -263,9 +289,9 @@ rails-schema/
 
 A mounted engine requires a running server. A static file can be generated in CI, committed to the repo, and opened by anyone — including non-developers looking at a data model.
 
-### Why parse schema.rb?
+### Why parse schema.rb / structure.sql?
 
-Parsing `db/schema.rb` allows column extraction without a database connection. This means the gem can work in CI environments or development setups where the database isn't running. It also avoids eager-loading the entire app just to read column metadata.
+Parsing `db/schema.rb` or `db/structure.sql` allows column extraction without a database connection. This means the gem can work in CI environments or development setups where the database isn't running. It also avoids eager-loading the entire app just to read column metadata. The `schema_format: :auto` default tries `schema.rb` first, then falls back to `structure.sql`, so the gem works out of the box regardless of which format a project uses.
 
 ### Why force-directed layout?
 
@@ -292,12 +318,12 @@ spec.add_dependency "railties", ">= 6.0"
 
 | Layer | Approach |
 |---|---|
-| Extractor | Unit tests with in-memory SQLite models (User, Post, Comment, Tag) |
+| Extractor | Unit tests with in-memory SQLite models (User, Post, Comment, Tag); rescue-path warnings tested via `output(...).to_stderr` |
 | Transformer | Pure Ruby unit tests — graph building, edge filtering |
 | Renderer | Output tests — verify HTML structure, embedded data, script injection safety |
 | Configuration | Unit tests for defaults and attribute setting |
 
-**66 tests, all passing.** Run with `bundle exec rspec`.
+**108 tests, all passing.** Run with `bundle exec rspec`.
 
 ---
 
@@ -319,4 +345,4 @@ spec.add_dependency "railties", ">= 6.0"
 
 ---
 
-*Document reflects the current implementation (v0.1.0). Future enhancements are aspirational and subject to refinement.*
+*Document reflects the current implementation (v0.1.2). Future enhancements are aspirational and subject to refinement.*

data/README.md

@@ -48,6 +48,7 @@ Rails::Schema.configure do |config|
   config.title = "My App Schema"
   config.theme = :auto          # :auto, :light, or :dark
   config.expand_columns = false # start with columns collapsed
+  config.schema_format = :auto  # :auto, :ruby, or :sql
   config.exclude_models = [
     "ActiveStorage::Blob",
     "ActiveStorage::Attachment",
@@ -56,13 +57,32 @@ Rails::Schema.configure do |config|
 end
 ```
 
+| Option | Default | Description |
+|--------|---------|-------------|
+| `output_path` | `"docs/schema.html"` | Path for the generated HTML file |
+| `title` | `"Database Schema"` | Title shown in the HTML page |
+| `theme` | `:auto` | Color theme — `:auto`, `:light`, or `:dark` |
+| `expand_columns` | `false` | Whether model nodes start with columns expanded |
+| `schema_format` | `:auto` | Schema source — `:auto`, `:ruby`, or `:sql` (see below) |
+| `exclude_models` | `[]` | Models to hide; supports exact names and wildcard prefixes (`"ActionMailbox::*"`) |
+
+### Schema format
+
+Rails projects can use either `db/schema.rb` (Ruby DSL) or `db/structure.sql` (raw SQL dump) to represent the database schema. Set `config.active_record.schema_format = :sql` in your Rails app to use `structure.sql`.
+
+| Value | Behavior |
+|-------|----------|
+| `:auto` | Tries `db/schema.rb` first, falls back to `db/structure.sql` |
+| `:ruby` | Only reads `db/schema.rb` |
+| `:sql` | Only reads `db/structure.sql` |
+
 ## How it works
 
-The gem parses your `db/schema.rb` file to extract table and column information — **no database connection required**. It also introspects loaded ActiveRecord models for association metadata. This means the gem works even if you don't have a local database set up, as long as `db/schema.rb` is present (which is standard in Rails projects under version control).
+The gem parses your `db/schema.rb` or `db/structure.sql` file to extract table and column information — **no database connection required**. It also introspects loaded ActiveRecord models for association metadata. This means the gem works even if you don't have a local database set up, as long as a schema file is present (which is standard in Rails projects under version control).
 
 ## Features
 
-- **No database required** — reads directly from `db/schema.rb`
+- **No database required** — reads from `db/schema.rb` or `db/structure.sql`
 - **Force-directed layout** — models cluster naturally by association density
 - **Searchable sidebar** — filter models by name or table
 - **Click-to-focus** — click a model to highlight its neighborhood, fading unrelated models

data/lib/rails/schema/configuration.rb

@@ -3,7 +3,7 @@
 module Rails
   module Schema
     class Configuration
-      attr_accessor :output_path, :exclude_models, :title, :theme, :expand_columns
+      attr_accessor :output_path, :exclude_models, :title, :theme, :expand_columns, :schema_format
 
       def initialize
         @output_path = "docs/schema.html"
@@ -11,6 +11,7 @@ module Rails
         @title = "Database Schema"
         @theme = :auto
         @expand_columns = false
+        @schema_format = :auto
       end
     end
   end

data/lib/rails/schema/extractor/association_reader.rb

@@ -26,16 +26,27 @@ module Rails
             association_type: ref.macro.to_s,
             label: ref.name.to_s,
             foreign_key: ref.foreign_key.to_s,
-            through: ref.options[:through]&.to_s,
-            polymorphic: ref.options[:as] ? true : false
+            through: through_name(ref),
+            polymorphic: polymorphic?(ref)
           }
-        rescue StandardError
+        rescue StandardError => e
+          warn "[rails-schema] Could not read association #{ref.name} on #{model.name}: #{e.class}: #{e.message}"
           nil
         end
 
+        def through_name(ref)
+          ref.options[:through]&.to_s
+        end
+
+        def polymorphic?(ref)
+          ref.options[:as] ? true : false
+        end
+
         def target_model_name(ref)
           ref.klass.name
-        rescue StandardError
+        rescue StandardError => e
+          warn "[rails-schema] Could not resolve target for #{ref.name}, " \
+               "falling back to #{ref.class_name}: #{e.class}: #{e.message}"
           ref.class_name
         end
       end

data/lib/rails/schema/extractor/column_reader.rb

@@ -28,7 +28,8 @@ module Rails
               default: col.default
             }
           end
-        rescue StandardError
+        rescue StandardError => e
+          warn "[rails-schema] Could not read columns for #{model.name}: #{e.class}: #{e.message}"
           []
         end
       end

data/lib/rails/schema/extractor/structure_sql_parser.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Rails
+  module Schema
+    module Extractor
+      class StructureSqlParser
+        SQL_TYPE_MAP = {
+          "character varying" => "string", "varchar" => "string",
+          "integer" => "integer", "smallint" => "integer", "serial" => "integer",
+          "bigint" => "bigint", "bigserial" => "bigint",
+          "boolean" => "boolean", "text" => "text",
+          "timestamp without time zone" => "datetime", "timestamp with time zone" => "datetime",
+          "timestamp" => "datetime",
+          "json" => "json", "jsonb" => "jsonb", "uuid" => "uuid",
+          "numeric" => "decimal", "decimal" => "decimal", "money" => "decimal",
+          "date" => "date",
+          "float" => "float", "double precision" => "float", "real" => "float",
+          "bytea" => "binary"
+        }.freeze
+
+        COMPOUND_TYPE_RE = /\A(character\s+varying|bit\s+varying|double\s+precision|
+                               timestamp(?:\(\d+\))?\s+with(?:out)?\s+time\s+zone)/ix
+        CONSTRAINT_RE = /\A(CONSTRAINT|UNIQUE|CHECK|EXCLUDE|FOREIGN\s+KEY)\b/i
+        PK_CONSTRAINT_RE = /PRIMARY\s+KEY\s*\(([^)]+)\)/i
+
+        def initialize(structure_path = nil)
+          @structure_path = structure_path
+        end
+
+        def parse
+          path = resolve_path
+          return {} unless path && File.exist?(path)
+
+          parse_content(File.read(path))
+        end
+
+        def parse_content(content)
+          tables = {}
+
+          content.scan(/CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?([\w."]+)\s*\((.*?)\)\s*;/mi) do |table_name, body|
+            name = extract_table_name(table_name)
+            columns, pk_columns = parse_table_body(body)
+            pk_columns.each { |pk| columns.find { |c| c[:name] == pk }&.[]= :primary, true }
+            tables[name] = columns
+          end
+
+          tables
+        end
+
+        private
+
+        def resolve_path
+          return @structure_path if @structure_path
+          return ::Rails.root.join("db", "structure.sql").to_s if defined?(::Rails.root) && ::Rails.root
+
+          File.join(Dir.pwd, "db", "structure.sql")
+        end
+
+        def unquote(identifier) = identifier.delete('"')
+
+        def extract_table_name(raw)
+          unquote(raw).split(".").last
+        end
+
+        def parse_table_body(body)
+          columns = []
+          pk_columns = []
+          body.each_line do |raw|
+            line = raw.strip.chomp(",")
+            next if line.empty?
+
+            if (pk = extract_pk_constraint(line))
+              pk_columns.concat(pk)
+            elsif !line.match?(CONSTRAINT_RE) && (col = parse_column_line(line))
+              pk_columns << col[:name] if col.delete(:inline_pk)
+              columns << col
+            end
+          end
+          [columns, pk_columns]
+        end
+
+        def extract_pk_constraint(line)
+          return unless (match = line.match(PK_CONSTRAINT_RE))
+
+          match[1].split(",").map { |c| unquote(c.strip) }
+        end
+
+        def parse_column_line(line)
+          match = line.match(/\A("?\w+"?)\s+(.+)/i)
+          return nil unless match
+
+          rest = match[2]
+          type = extract_type(rest)
+          return nil unless type
+
+          build_column(unquote(match[1]), rest, type)
+        end
+
+        def build_column(col_name, rest, type)
+          {
+            name: col_name,
+            type: SQL_TYPE_MAP.fetch(type, type),
+            nullable: !rest.match?(/\bNOT\s+NULL\b/i),
+            default: extract_default(rest),
+            primary: false,
+            inline_pk: rest.match?(/\bPRIMARY\s+KEY\b/i)
+          }
+        end
+
+        def extract_type(rest)
+          if (m = rest.match(COMPOUND_TYPE_RE))
+            m[1].downcase.gsub(/\(\d+\)/, "")
+          elsif rest.match?(/\A(FOREIGN\s+KEY)\b/i)
+            nil
+          else
+            rest[/\A(\w+)/i, 1]&.downcase
+          end
+        end
+
+        def extract_default(rest)
+          case rest
+          when /\bDEFAULT\s+'([^']*)'(?:::\w+)?/i, /\bDEFAULT\s+(\d+(?:\.\d+)?)\b/i
+            Regexp.last_match(1)
+          when /\bDEFAULT\s+true\b/i then "true"
+          when /\bDEFAULT\s+false\b/i then "false"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails/schema/version.rb

@@ -2,6 +2,6 @@
 
 module Rails
   module Schema
-    VERSION = "0.1.1"
+    VERSION = "0.1.2"
   end
 end

data/lib/rails/schema.rb

@@ -5,6 +5,7 @@ require_relative "schema/configuration"
 require_relative "schema/transformer/node"
 require_relative "schema/transformer/edge"
 require_relative "schema/extractor/schema_file_parser"
+require_relative "schema/extractor/structure_sql_parser"
 require_relative "schema/extractor/model_scanner"
 require_relative "schema/extractor/column_reader"
 require_relative "schema/extractor/association_reader"
@@ -29,13 +30,27 @@ module Rails
       end
 
       def generate(output: nil)
-        schema_data = Extractor::SchemaFileParser.new.parse
+        schema_data = parse_schema
         models = Extractor::ModelScanner.new(schema_data: schema_data).scan
         column_reader = Extractor::ColumnReader.new(schema_data: schema_data)
         graph_data = Transformer::GraphBuilder.new(column_reader: column_reader).build(models)
         generator = Renderer::HtmlGenerator.new(graph_data: graph_data)
         generator.render_to_file(output)
       end
+
+      private
+
+      def parse_schema
+        case configuration.schema_format
+        when :ruby
+          Extractor::SchemaFileParser.new.parse
+        when :sql
+          Extractor::StructureSqlParser.new.parse
+        when :auto
+          data = Extractor::SchemaFileParser.new.parse
+          data.empty? ? Extractor::StructureSqlParser.new.parse : data
+        end
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-schema
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Andrei Kislichenko
@@ -45,6 +45,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE.txt
 - PROJECT.md
 - README.md
@@ -61,6 +62,7 @@ files:
 - lib/rails/schema/extractor/column_reader.rb
 - lib/rails/schema/extractor/model_scanner.rb
 - lib/rails/schema/extractor/schema_file_parser.rb
+- lib/rails/schema/extractor/structure_sql_parser.rb
 - lib/rails/schema/railtie.rb
 - lib/rails/schema/renderer/html_generator.rb
 - lib/rails/schema/transformer/edge.rb