pg-erd 0.1.0

data/README.md

@@ -0,0 +1,66 @@
+# Postgres ERD
+
+## Generate Entity-Relationship Diagrams for Postgresql Databases
+
+Postgres ERD is a program that allows you to easily generate a diagram based on a postgresql database schema. The diagram gives an overview of how your tables are related. Having a diagram to describes your tables is perfect for documentation.
+
+Postgres ERD is heavily inspired by [Rails ERD](https://voormedia.github.io/rails-erd/) but it serves some different use cases. First and foremost it does not rely on Rails (like Rails ERD). Thus you can use it for any database schema regardless of your project's language.
+
+## An Example
+
+
+# Requirements
+
+- Ruby 2.4+
+- postgresql
+
+# Getting started
+
+[It's part of a two-step program](https://www.youtube.com/watch?v=_c1NJQ0UP_Q):
+
+Install the gem
+
+```sh
+gem install pg-erd
+```
+
+Use the thing:
+
+```sh
+pg-erd {{the-name-of-your-database}}
+```
+
+This will output a diagram of your database in [dot format](http://www.graphviz.org/). You can save it 
+
+```sh
+pg-erd {{the-name-of-your-database}} > my-awesome-database.dot
+```
+
+... or run it though graphviz to create a png file:
+
+```sh
+pg-erd {{the-name-of-your-database}} | dot -Tpng > erd.png
+```
+
+... which you may also do like this: 
+
+```sh
+pg-erd --title "Secret Project X" --format png {{the-name-of-your-database}} > erd.png
+```
+
+There are many more formats and a few more useful options. You can find them all with `--help`
+
+# Free extras
+
+## pg-erd-everything
+
+This command will create an ERD for every database on your system. It will write many image files, one for each database, to the current directory.
+
+## pg-list-databases
+
+Like `ls` but it lists the names of your postgres databases one by one.
+
+## pg-inspect
+
+This command outputs a summary of your database structure to the console. It shows the same information as an ERD but then in plain text.
+

data/bin/pg-erd

@@ -0,0 +1,63 @@
+#!/usr/bin/env ruby
+require 'optparse'
+require_relative '../lib/pgerd'
+
+def parse_arguments!(args = ARGV)
+  options = {
+    format: 'dot',
+    size: nil,
+    show_id: true,
+    show_timestamps: true,
+    verbose: false
+  }
+
+  opt_parser = OptionParser.new do |opts|
+    opts.banner = "Usage: #{$0} [options] DATABASE"
+    opts.separator ''
+
+    opts.on("-fFORMAT", "--format FORMAT", GraphViz::Constants::FORMATS.join(', ') + " (default=dot)") do |format|
+      options[:format] = format.downcase
+    end
+
+    opts.on("--[no-]id", 'Show (or hide) the id column (default=show)') do |show_id|
+      options[:show_id] = show_id
+    end
+
+    opts.on("--[no-]timestamps", 'Show (or hide) the timestamp columns (default=show)') do |show_timestamps|
+      options[:show_timestamps] = show_timestamps
+    end
+
+    opts.on("-tTITLE", "--title TITLE", "override the title") do |title|
+      options[:title] = title
+    end
+
+    opts.on("--a4", 'try to fit the erd on an A4') do |size|
+      options[:size] = 'A4'
+    end
+
+    opts.on("-v", "--[no-]verbose", "Verbose output") do |v|
+      options[:verbose] = v
+    end
+
+    opts.on_tail("-h", "--help", "Show this message") do
+      puts opts
+      exit
+    end
+  end
+  opt_parser.parse!(args)
+  options
+end
+
+options = parse_arguments!
+
+STDERR.puts options if options[:verbose]
+
+require 'pg'
+CONNECTION = PG.connect(dbname: ARGV.last)
+
+include Pgerd
+
+database = Database.new(ARGV.first)
+erd = Erd.new(database, options)
+
+puts erd.diagram.output(options[:format] => String)

data/bin/pg-erd-everything

@@ -0,0 +1,66 @@
+#!/usr/bin/env ruby
+
+require 'pg'
+require 'optparse'
+require_relative '../lib/pgerd'
+include Pgerd
+
+def parse_arguments!(args = ARGV)
+  options = {
+    format: 'svg',
+    show_id: true,
+    show_timestamps: true,
+    verbose: false
+  }
+
+  opt_parser = OptionParser.new do |opts|
+    opts.banner = "Usage: #{$0} [options] DATABASE"
+    opts.separator ''
+
+    # opts.on("-fFORMAT", "--format FORMAT", GraphViz::Constants::FORMATS.join(', ') + " (default=dot)") do |format|
+    #   options[:format] = format.downcase
+    # end
+
+    opts.on("--[no-]id", 'Show (or hide) the id column (default=show)') do |show_id|
+      options[:show_id] = show_id
+    end
+
+    opts.on("--[no-]timestamps", 'Show (or hide) the timestamp columns (default=show)') do |show_timestamps|
+      options[:show_timestamps] = show_timestamps
+    end
+
+    opts.on("-tTITLE", "--title TITLE", "override the title") do |title|
+      options[:title] = title
+    end
+
+    opts.on("-v", "--[no-]verbose", "Verbose output") do |v|
+      options[:verbose] = v
+    end
+
+    opts.on_tail("-h", "--help", "Show this message") do
+      puts opts
+      exit
+    end
+  end
+  opt_parser.parse!(args)
+  options
+end
+
+options = parse_arguments!
+
+STDERR.puts options if options[:verbose]
+
+def each_database
+  PG.connect.query("SELECT datname FROM pg_database WHERE datistemplate = false;").each do |result|
+    yield result['datname']
+  end
+end
+
+each_database do |name|
+  puts name
+  database = Database.new(name)
+  erd = Erd.new(database, options)
+  File.open("#{name}.#{options[:format]}", 'w') do |file|
+    file.puts erd.diagram.output(options[:format] => String)
+  end
+end

data/bin/pg-erd-png

@@ -0,0 +1,4 @@
+#!/bin/sh
+
+pg-erd $@ | dot -Tpng > erd.png
+optipng erd.png

data/bin/pg-erd-svg

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+pg-erd --format svg $@

data/bin/pg-inspect

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+require 'pg'
+CONNECTION = PG.connect(dbname: ARGV.first)
+
+require_relative '../lib/pgerd'
+include Pgerd
+
+database = Database.new(ARGV.first)
+
+database.tables.each do |table|
+  puts "#{table.name}"
+  puts "-" * 20
+  puts table.columns.map { |column| "#{column.name} - #{column.data_type}" }
+  puts
+end
+
+if database.foreign_keys.any?
+  puts '# foreign keys'
+  database.foreign_keys.each { |x| puts x }
+end

data/bin/pg-list-databases

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require 'pg'
+
+PG.connect.query("SELECT datname FROM pg_database WHERE datistemplate = false;").each do |result|
+  puts result['datname']
+end

data/lib/dot/id.rb

@@ -0,0 +1,24 @@
+module Dot
+  # An ID is one of the following:
+
+  # Any string of alphabetic ([a-zA-Z\200-\377]) characters, underscores ('_') or digits ([0-9]), not beginning with a digit;
+  # a numeral [-]?(.[0-9]+ | [0-9]+(.[0-9]*)? );
+  # any double-quoted string ("...") possibly containing escaped quotes ('");
+  # an HTML string (<...>).
+  class Id
+    def initialize(string)
+      @string = string.to_s
+      raise ArgumentError if @string.empty?
+    end
+
+    def escaped
+      @string.gsub!("\"", "\\\"")
+      @string.gsub!("\'", "\\\'")
+      @string
+    end
+
+    def to_dot
+      "\"#{escaped}\""
+    end
+  end
+end

data/lib/dot/node.rb

@@ -0,0 +1,4 @@
+module Dot
+  class Node
+  end
+end

data/lib/pgerd/column.rb

@@ -0,0 +1,48 @@
+module Pgerd
+  class Column
+    include Comparable
+    attr_accessor :name, :data_type
+    ID = %w(id)
+    GROUPS = %i(id other timestamps)
+
+    def initialize(name, data_type)
+      @name = name
+      @data_type = data_type
+    end
+
+    def <=>(other)
+      to_a_for_sorting <=> other.to_a_for_sorting
+    end
+
+    def group
+      if ID.include? @name
+        :id
+      elsif @data_type.include?("timestamp")
+        :timestamps
+      else
+        :other
+      end
+    end
+
+    def group_for_sorting
+      GROUPS.index(group)
+    end
+
+    def abbreviated_data_type
+      # The SQL standard requires that writing just timestamp be equivalent to timestamp without time zone,
+      # and PostgreSQL honors that behavior.
+      @data_type
+        .gsub('timestamp without time zone', 'timestamp')
+        .gsub(/\bwithout\b/, 'w/o')
+        .gsub(/\bwith\b/, 'w/')
+    end
+
+    def to_s
+      "#{name} [label = <>]"
+    end
+
+    def to_a_for_sorting
+      [group_for_sorting, name, data_type]
+    end
+  end
+end

data/lib/pgerd/database.rb

@@ -0,0 +1,75 @@
+require_relative 'foreign_key'
+require_relative 'table'
+require_relative 'view'
+
+module Pgerd
+  class Database
+    attr_reader :name
+    TABLES_TO_IGNORE = %w(ar_internal_metadata schema_migrations)
+
+    def initialize(name)
+      @name = name
+    end
+
+    def all_table_names
+      connection
+        .query("SELECT tablename FROM pg_catalog.pg_tables")
+        .map { |table| table['tablename'] }
+        .reject { |name| name.start_with?('pg_') || name.start_with?('sql_')}
+    end
+
+    def all_view_names
+      connection
+        .query("SELECT viewname FROM pg_catalog.pg_views WHERE schemaname NOT IN ('pg_catalog', 'information_schema')")
+        .map { |view| view['viewname'] }
+        .reject { |name| name.start_with?('pg_') || name.start_with?('sql_')}
+    end
+
+    def foreign_keys
+      @foreign_keys ||= raw_foreign_keys.map { |data| ForeignKey.new(data) }
+    end
+
+    def raw_foreign_keys
+      connection
+        .query <<-END_SQL
+            select c.constraint_name
+                , x.table_schema as from_schema
+                , x.table_name as from_table
+                , x.column_name as from_column
+                , y.table_schema as to_schema
+                , y.table_name as to_table
+                , y.column_name as to_column
+            from information_schema.referential_constraints c
+            join information_schema.key_column_usage x
+                on x.constraint_name = c.constraint_name
+            join information_schema.key_column_usage y
+                on y.ordinal_position = x.position_in_unique_constraint
+                and y.constraint_name = c.unique_constraint_name
+            order by c.constraint_name, x.ordinal_position
+          END_SQL
+    end
+
+    def table_names
+      all_table_names - TABLES_TO_IGNORE
+    end
+
+    def tables
+      @tables ||=
+	table_names
+        .map { |name| Table.new(self, name) }
+        .sort_by { |table| table.foreign_keys.size }
+        .reverse
+    end
+
+    def views
+      @views ||=
+        all_view_names
+        .map { |name| View.new(self, name) }
+        .reverse
+    end
+
+    def connection
+      @connection ||= PG.connect(dbname: name)
+    end
+  end
+end

data/lib/pgerd/erbal_t.rb

@@ -0,0 +1,8 @@
+require 'erb'
+require 'ostruct'
+
+class ErbalT < OpenStruct
+  def render(template)
+    ERB.new(template).result(binding)
+  end
+end

data/lib/pgerd/erd/table_node.rb

@@ -0,0 +1,46 @@
+require_relative '../erbal_t'
+
+module Pgerd
+  class Erd
+    class TableNode
+      TABLE_TEMPLATE = <<-END_HTML
+<table border="1" align="center" cellborder="0" cellpadding="2" cellspacing="2">
+  <tr><td bgcolor="#f8f8f8" align="center" cellpadding="8"><font point-size="11"><%= name %></font></td></tr>
+  <% grouped_columns.each_with_index do |group, index| %>
+    <% if index > 0 %>
+      <tr><td height='3'></td></tr>
+    <% end %>
+    <% group.each do |column| %>
+      <tr>
+        <td align="left" port="<%= column.name %>"><%= column.name %>   <font color="grey60"><%= column.abbreviated_data_type %></font></td>
+      </tr>
+    <% end %>
+  <% end %>
+</table>
+END_HTML
+
+      attr_reader :table, :groups_to_hide
+
+      def initialize(table, options = {})
+        @table = table
+
+        @groups_to_hide = []
+        @groups_to_hide << :id unless options.fetch(:show_id, true)
+        @groups_to_hide << :timestamps unless options.fetch(:show_timestamps, true)
+      end
+
+      def self.render(table, options = {})
+        new(table, options).to_html
+      end
+
+      def to_html
+        grouped_columns = @table.columns
+          .reject { |column| @groups_to_hide.include? column.group }
+          .group_by(&:group)
+          .values
+
+        ErbalT.new(name: @table.name, grouped_columns: grouped_columns).render(TABLE_TEMPLATE).strip
+      end
+    end
+  end
+end

data/lib/pgerd/erd/view_node.rb

@@ -0,0 +1,46 @@
+require_relative '../erbal_t'
+
+module Pgerd
+  class Erd
+    class ViewNode
+      VIEW_TEMPLATE = <<-END_HTML
+<table border="1" align="center" cellborder="0" cellpadding="2" cellspacing="2">
+  <tr><td bgcolor="#fafaf8" align="center" cellpadding="8"><font point-size="11"><%= name %> *view*</font></td></tr>
+  <% grouped_columns.each_with_index do |group, index| %>
+    <% if index > 0 %>
+      <tr><td height='3'></td></tr>
+    <% end %>
+    <% group.each do |column| %>
+      <tr>
+        <td align="left" port="<%= column.name %>"><%= column.name %>   <font color="grey60"><%= column.abbreviated_data_type %></font></td>
+      </tr>
+    <% end %>
+  <% end %>
+</table>
+END_HTML
+
+      attr_reader :view, :groups_to_hide
+
+      def initialize(view, options = {})
+        @view = view
+
+        @groups_to_hide = []
+        @groups_to_hide << :id unless options.fetch(:show_id, true)
+        @groups_to_hide << :timestamps unless options.fetch(:show_timestamps, true)
+      end
+
+      def self.render(view, options = {})
+        new(view, options).to_html
+      end
+
+      def to_html
+        grouped_columns = @view.columns
+          .reject { |column| @groups_to_hide.include? column.group }
+          .group_by(&:group)
+          .values
+
+        ErbalT.new(name: @view.name, grouped_columns: grouped_columns).render(VIEW_TEMPLATE).strip
+      end
+    end
+  end
+end

data/lib/pgerd/erd.rb

@@ -0,0 +1,136 @@
+require 'ruby-graphviz'
+require 'ruby-progressbar'
+require_relative 'erd/table_node'
+require_relative 'erd/view_node'
+
+module Pgerd
+  class Erd
+    attr_reader :diagram
+
+    def initialize(database, options = {})
+      @database = database
+      @title = options[:title] || @database.name
+      @size = options[:size].to_s.downcase
+      @options = options
+
+      create_a_digraph
+      draw_the_tables
+      draw_the_views
+      draw_the_foreign_keys
+    end
+
+    def to_s
+      @diagram.output(dot: String)
+    end
+
+    def a4?
+      @size == 'a4'
+    end
+
+    private
+
+    def create_a_digraph
+      @diagram = GraphViz.new(@title,
+        bgcolor: '#f4f8fa',
+        center: 1,
+        concentrate: true,
+        fontcolor: '#000000d0',
+        fontname: 'Helvetica',
+        fontsize: 13,
+        label: @title + "\n\n",
+        labelloc: 't',
+        # margin: 0,
+        nodesep: 0.2,
+        outputorder: 'nodesfirst',
+        overlap: false,
+        pad: '0.4,0.4',
+        rankdir: 'LR',
+        ranksep: '0.5',
+        splines: true,
+        type: :digraph)
+
+      if a4?
+        diagram[:size] = '8.3,11.7!'
+        diagram[:ratio] = 'compress'
+      end
+
+      @diagram.node[:color] = '#000000d0'
+      @diagram.node[:fillcolor] = '#ffffff'
+      @diagram.node[:fontname] = 'Helvetica'
+      @diagram.node[:fontsize] = 10
+      # @diagram.node[:margin] = "0.07,0.05"
+      @diagram.node[:margin] = "0"
+      @diagram.node[:penwidth] = "1.0"
+      @diagram.node[:shape] = 'box'
+      @diagram.node[:style] = 'filled'
+
+      @diagram.edge[:arrowsize] = "0.9"
+      @diagram.edge[:arrowtail] = "none"
+      @diagram.edge[:color] = '#000000d0'
+      @diagram.edge[:dir] = "both"
+      @diagram.edge[:fontname] = "Helvetica"
+      @diagram.edge[:fontsize] = "7"
+      @diagram.edge[:labelangle] = "32"
+      @diagram.edge[:labeldistance] = "1.8"
+      @diagram.edge[:penwidth] = "1.0"
+    end
+
+    def draw_the_tables
+      progress = ProgressBar.create(
+        title: 'Tables',
+        total: @database.tables.count,
+        format: '%t: |%B| %%%p %E',
+	output: $stderr)
+      @database.tables.each do |table|
+        draw_table(table)
+	progress.increment
+      end
+    end
+
+    def draw_table(table)
+      html = Erd::TableNode.render(table, @options)
+      @diagram.add_node(table.name, label: "<#{html}>")
+    end
+
+    def draw_the_views
+      progress = ProgressBar.create(
+        title: 'Views',
+        total: @database.tables.count,
+        format: '%t: |%B| %%%p %E',
+	output: $stderr)
+      @database.views.each do |view|
+        draw_view(view)
+        progress.increment
+      end
+    end
+
+    def draw_view(view)
+      html = Erd::ViewNode.render(view, @options)
+      @diagram.add_node(view.name, label: "<#{html}>")
+    end
+
+    def draw_the_foreign_keys
+      progress = ProgressBar.create(
+        title: 'Foreign Keys',
+        total: @database.foreign_keys.count,
+        format: '%t: |%B| %%%p %E',
+	output: $stderr)
+      @database.foreign_keys.each do |fk|
+        draw_foreign_key(fk)
+        progress.increment
+      end
+    end
+
+    def draw_foreign_key(fk)
+      from = address(fk.from_table, fk.from_column)
+      to = address(fk.to_table, fk.to_column)
+
+      @diagram.add_edge(from, to, weight: 2)
+    end
+
+    def address(table, column)
+      return table if column == 'id'
+      { table => column }
+    end
+  end
+end

data/lib/pgerd/foreign_key.rb

@@ -0,0 +1,29 @@
+module Pgerd
+  class ForeignKey
+    include Comparable
+    attr_reader :from_table, :from_column, :to_table, :to_column
+
+    def initialize(data)
+      @from_table = data['from_table']
+      @from_column = data['from_column']
+      @to_table = data['to_table']
+      @to_column = data['to_column']
+    end
+
+    def to_s
+      "#{@from_table}.#{@from_column} --> #{@to_table}.#{@to_column}"
+    end
+
+    def <=>(other)
+      to_a_for_sorting <=> other.to_a_for_sorting
+    end
+
+    def to_a_for_sorting
+      [@from_table, @from_column, @to_table, @to_column]
+    end
+
+    def for_table?(table)
+      @from_table == table || @to_table == table
+    end
+  end
+end