db_diagram 0.1.0

data/lib/db_diagram/domain/attribute.rb

@@ -0,0 +1,162 @@
+# encoding: utf-8
+
+#--
+module DBDiagram
+  class Domain
+    # Describes an entity's attribute. Attributes correspond directly to
+    # database columns.
+    class Attribute
+      TIMESTAMP_NAMES = %w{created_at created_on updated_at updated_on} # @private :nodoc:
+
+      class << self
+        def from_model(domain, model) # @private :nodoc:
+          attributes = model.columns.collect { |column| new(domain, model, column) }
+          attributes.sort! if DBDiagram.options[:sort]
+
+          if DBDiagram.options[:prepend_primary]
+            attributes = prepend_primary(model, attributes)
+          end
+
+          attributes
+        end
+
+        def prepend_primary(model, attributes)
+          primary_key = ActiveRecord::Base.get_primary_key(model)
+          primary = attributes.index { |column| column.name == primary_key }
+
+          return attributes if primary || primary == 0
+
+          [primary_key, *attributes[0...primary], *attributes[(primary+1)..-1]]
+        end
+      end
+
+      extend Inspectable
+      inspection_attributes :name, :type
+
+      attr_reader :column # @private :nodoc:
+
+      def initialize(domain, model, column) # @private :nodoc:
+        @domain, @model, @column = domain, model, column
+      end
+
+      # The name of the attribute, equal to the column name.
+      def name
+        column.name
+      end
+
+      # The type of the attribute, equal to the Rails migration type. Can be any
+      # of +:string+, +:integer+, +:boolean+, +:text+, etc.
+      def type
+        column.sql_type.downcase.to_sym or column.type
+      end
+
+      # Returns +true+ if this attribute is a content column, that is, if it
+      # is not a primary key, foreign key, timestamp, or inheritance column.
+      def content?
+        !primary_key? and !foreign_key? and !timestamp? and !inheritance?
+      end
+
+      # Returns +true+ if this attribute is mandatory. Mandatory attributes
+      # either have a presence validation (+validates_presence_of+), or have a
+      # <tt>NOT NULL</tt> database constraint.
+      def mandatory?
+        !column.null or @model.validators_on(name).map(&:kind).include?(:presence)
+      end
+
+       def unique?
+         @model.validators_on(name).map(&:kind).include?(:uniqueness)
+       end
+
+      # Returns +true+ if this attribute is the primary key of the entity.
+      def primary_key?
+        @model.primary_key.to_s == name.to_s
+      end
+
+      # Returns +true+ if this attribute is used as a foreign key for any
+      # relationship.
+      def foreign_key?
+        @domain.relationships_by_entity_name(@model.name).map(&:associations).flatten.map { |associaton|
+          associaton.send(Domain.foreign_key_method_name)
+        }.include?(name)
+      end
+
+      # Returns +true+ if this attribute is used for single table inheritance.
+      # These attributes are typically named +type+.
+      def inheritance?
+        @model.inheritance_column == name
+      end
+
+      # Method allows false to be set as an attributes option when making custom graphs.
+      # It rejects all attributes when called from Diagram#filtered_attributes method
+      def false?
+        false
+      end
+
+      def true?
+        true
+      end
+
+      # Returns +true+ if this attribute is one of the standard 'magic' Rails
+      # timestamp columns, being +created_at+, +updated_at+, +created_on+ or
+      # +updated_on+.
+      def timestamp?
+        TIMESTAMP_NAMES.include? name
+      end
+
+      def <=>(other) # @private :nodoc:
+        name <=> other.name
+      end
+
+      def to_s # @private :nodoc:
+        name
+      end
+
+      # Returns a description of the attribute type. If the attribute has
+      # a non-standard limit or if it is mandatory, this information is included.
+      #
+      # Example output:
+      # <tt>:integer</tt>:: integer
+      # <tt>:string, :limit => 255</tt>:: string
+      # <tt>:string, :limit => 128</tt>:: string (128)
+      # <tt>:decimal, :precision => 5, :scale => 2/tt>:: decimal (5,2)
+      # <tt>:boolean, :null => false</tt>:: boolean *
+      def type_description
+        type.to_s.tap do |desc|
+          # desc << " #{limit_description}" if limit_description
+          desc << " ∗" if mandatory? && !primary_key? # Add a hair space + low asterisk (Unicode characters)
+          desc << " U" if unique? && !primary_key? && !foreign_key? # Add U if unique but non-key
+          desc << " PK" if primary_key?
+          desc << " FK" if foreign_key?
+        end
+      end
+
+      # Returns any non-standard limit for this attribute. If a column has no
+      # limit or uses a default database limit, this method returns +nil+.
+      def limit
+        return if native_type == 'geometry' || native_type == 'geography'
+        return column.limit.to_i if column.limit != native_type[:limit] and column.limit.respond_to?(:to_i)
+        column.precision.to_i if column.precision != native_type[:precision] and column.precision.respond_to?(:to_i)
+      end
+
+      # Returns any non-standard scale for this attribute (decimal types only).
+      def scale
+        return column.scale.to_i if column.scale != native_type[:scale] and column.scale.respond_to?(:to_i)
+        0 if column.precision
+      end
+
+      # Returns a string that describes the limit for this attribute, such as
+      # +(128)+, or +(5,2)+ for decimal types. Returns nil if no non-standard
+      # limit was set.
+      def limit_description # @private :nodoc:
+        return "(#{limit},#{scale})" if limit and scale
+        return "(#{limit})" if limit
+      end
+
+      private
+
+      def native_type
+        @model.connection.native_database_types[type] or {}
+      end
+    end
+  end
+end

data/lib/db_diagram/domain/entity.rb

@@ -0,0 +1,81 @@
+module DBDiagram
+  class Domain
+    # Entities represent your Active Record models. Entities may be connected
+    # to other entities.
+    class Entity
+      class << self
+        def from_models(domain, models) # @private :nodoc:
+          concrete_from_models(domain, models).sort
+        end
+
+        private
+
+        def concrete_from_models(domain, models)
+          models.collect { |model| new(domain, model) }
+        end
+      end
+
+      extend Inspectable
+      inspection_attributes :model
+
+      # The domain in which this entity resides.
+      attr_reader :domain
+
+      # The Active Record model that this entity corresponds to.
+      attr_reader :model
+
+      # The name of this entity. Equal to the class name of the corresponding
+      # model (for concrete entities) or given name (for abstract entities).
+      attr_reader :name
+
+      def initialize(domain, model) # @private :nodoc:
+        @domain, @model = domain, model
+        @name = !!model.abstract_class? ? model.name : model.table_name
+      end
+
+      # Returns an array of attributes for this entity.
+      def attributes
+        @attributes ||= generalized? ? [] : Attribute.from_model(domain, model)
+      end
+
+      # Returns an array of all relationships that this entity has with other
+      # entities in the domain model.
+      def relationships
+        domain.relationships_by_entity_name(name)
+      end
+
+      # Returns +true+ if this entity is a generalization, which does not
+      # correspond with a database table. Generalized entities are either
+      # models that are defined as +abstract_class+ or they are constructed
+      # from polymorphic interfaces. Any +has_one+ or +has_many+ association
+      # that defines a polymorphic interface with <tt>:as => :name</tt> will
+      # lead to a generalized entity to be created.
+      def generalized?
+        !!model.abstract_class?
+      end
+
+      # Returns +true+ if this entity does not correspond directly with a
+      # database table (if and only if the entity is specialized or
+      # generalized).
+      def abstract?
+        generalized?
+      end
+
+      def namespace
+        $1 if name.match(/(.*)::.*/)
+      end
+
+      def model_name
+        model.name
+      end
+
+      def to_s # @private :nodoc:
+        name
+      end
+
+      def <=>(other) # @private :nodoc:
+        self.name <=> other.name
+      end
+    end
+  end
+end

data/lib/db_diagram/domain/relationship.rb

@@ -0,0 +1,194 @@
+require "set"
+require "active_support/core_ext/module/delegation"
+require "db_diagram/domain/relationship/cardinality"
+
+module DBDiagram
+  class Domain
+    # Describes a relationship between two entities. A relationship is detected
+    # based on Active Record associations. One relationship may represent more
+    # than one association, however. Related associations are grouped together.
+    # Associations are related if they share the same foreign key, or the same
+    # join table in the case of many-to-many associations.
+    class Relationship
+      N = Cardinality::N
+
+      class << self
+        def from_associations(domain, associations) # @private :nodoc:
+          assoc_groups = associations.group_by { |assoc| association_identity(assoc) }
+          assoc_groups.collect { |_, assoc_group| new(domain, assoc_group.to_a) }
+        end
+
+        private
+
+        def association_identity(association)
+          Set[association_owner(association), association_target(association)]
+        end
+
+        def association_identifier(association)
+          if association.macro == :has_and_belongs_to_many
+            # Rails 4+ supports the join_table method, and doesn't expose it
+            # as an option if it's an implicit default.
+            (association.respond_to?(:join_table) && association.join_table) || association.options[:join_table]
+          else
+            association.options[:through] || association.send(Domain.foreign_key_method_name).to_s
+          end
+        end
+
+        def association_owner(association)
+          association.options[:as] ? association.options[:as].to_s.classify : association.active_record.name
+        end
+
+        def association_target(association)
+          association.options[:polymorphic] ? association.class_name : association.klass.name
+        end
+      end
+
+      extend Inspectable
+      inspection_attributes :source, :destination
+
+      # The domain in which this relationship is defined.
+      attr_reader :domain
+
+      # The source entity. It corresponds to the model that has defined a
+      # +has_one+ or +has_many+ association with the other model.
+      attr_reader :source
+
+      # The destination entity. It corresponds to the model that has defined
+      # a +belongs_to+ association with the other model.
+      attr_reader :destination
+
+      delegate :one_to_one?, :one_to_many?, :many_to_many?, :source_optional?,
+        :destination_optional?, :to => :cardinality
+
+      def initialize(domain, associations) # @private :nodoc:
+        @domain = domain
+        @reverse_associations, @forward_associations = partition_associations(associations)
+
+        assoc = @forward_associations.first || @reverse_associations.first
+        @source      = @domain.entity_by_name(self.class.send(:association_owner, assoc))
+        @destination = @domain.entity_by_name(self.class.send(:association_target, assoc))
+        @source, @destination = @destination, @source if assoc.belongs_to?
+      end
+
+      # Returns all Active Record association objects that describe this
+      # relationship.
+      def associations
+        @forward_associations + @reverse_associations
+      end
+
+      # Returns the cardinality of this relationship.
+      def cardinality
+        @cardinality ||= begin
+          reverse_max = any_habtm?(associations) ? N : 1
+          forward_range = associations_range(@forward_associations, N)
+          reverse_range = associations_range(@reverse_associations, reverse_max)
+          Cardinality.new(reverse_range, forward_range)
+        end
+      end
+
+      # Indicates whether or not the relationship is defined by two inverse
+      # associations (e.g. a +has_many+ and a corresponding +belongs_to+
+      # association).
+      def mutual?
+        @forward_associations.any? and @reverse_associations.any?
+      end
+
+      # Indicates whether or not this relationship connects an entity with itself.
+      def recursive?
+        @source == @destination
+      end
+
+      # Indicates whether the destination cardinality class of this relationship
+      # is equal to one. This is +true+ for one-to-one relationships only.
+      def to_one?
+        cardinality.cardinality_class[1] == 1
+      end
+
+      # Indicates whether the destination cardinality class of this relationship
+      # is equal to infinity. This is +true+ for one-to-many or
+      # many-to-many relationships only.
+      def to_many?
+        cardinality.cardinality_class[1] != 1
+      end
+
+      # Indicates whether the source cardinality class of this relationship
+      # is equal to one. This is +true+ for one-to-one or
+      # one-to-many relationships only.
+      def one_to?
+        cardinality.cardinality_class[0] == 1
+      end
+
+      # Indicates whether the source cardinality class of this relationship
+      # is equal to infinity. This is +true+ for many-to-many relationships only.
+      def many_to?
+        cardinality.cardinality_class[0] != 1
+      end
+
+      # The strength of a relationship is equal to the number of associations
+      # that describe it.
+      def strength
+        if source.generalized? then 1 else associations.size end
+      end
+
+      def <=>(other) # @private :nodoc:
+        (source.name <=> other.source.name).nonzero? or (destination.name <=> other.destination.name)
+      end
+
+      private
+
+      def partition_associations(associations)
+        if any_habtm?(associations)
+          # Many-to-many associations don't have a clearly defined direction.
+          # We sort by name and use the first model as the source.
+          source = associations.map(&:active_record).sort_by(&:name).first
+          associations.partition { |association| association.active_record != source }
+        else
+          associations.partition(&:belongs_to?)
+        end
+      end
+
+      def associations_range(associations, absolute_max)
+        # The minimum of the range is the maximum value of each association
+        # minimum. If there is none, it is zero by definition. The reasoning is
+        # that from all associations, if only one has a required minimum, then
+        # this side of the relationship has a cardinality of at least one.
+        min = associations.map { |assoc| association_minimum(assoc) }.max || 0
+
+        # The maximum of the range is the maximum value of each association
+        # maximum. If there is none, it is equal to the absolute maximum. If
+        # only one association has a high cardinality on this side, the
+        # relationship itself has the same maximum cardinality.
+        max = associations.map { |assoc| association_maximum(assoc) }.max || absolute_max
+
+        min..max
+      end
+
+      def association_minimum(association)
+        minimum = association_validators(:presence, association).any? ||
+          foreign_key_required?(association) ? 1 : 0
+        length_validators = association_validators(:length, association)
+        length_validators.map { |v| v.options[:minimum] }.compact.max or minimum
+      end
+
+      def association_maximum(association)
+        maximum = association.collection? ? N : 1
+        length_validators = association_validators(:length, association)
+        length_validators.map { |v| v.options[:maximum] }.compact.min or maximum
+      end
+
+      def association_validators(kind, association)
+        association.active_record.validators_on(association.name).select { |v| v.kind == kind }
+      end
+
+      def any_habtm?(associations)
+        associations.any? { |association| association.macro == :has_and_belongs_to_many }
+      end
+
+      def foreign_key_required?(association)
+        if !association.active_record.abstract_class? and association.belongs_to?
+          column = association.active_record.columns_hash[association.send(Domain.foreign_key_method_name)] and !column.null
+        end
+      end
+    end
+  end
+end

data/lib/db_diagram/domain/relationship/cardinality.rb

@@ -0,0 +1,118 @@
+module DBDiagram
+  class Domain
+    class Relationship
+      class Cardinality
+        extend Inspectable
+        inspection_attributes :source_range, :destination_range
+
+        N = Infinity = 1.0/0 # And beyond.
+
+        CLASSES = {
+          [1, 1] => :one_to_one,
+          [1, N] => :one_to_many,
+          [N, 1] => :many_to_one,
+          [N, N] => :many_to_many
+        } # @private :nodoc:
+
+        # Returns a range that indicates the source (left) cardinality.
+        attr_reader :source_range
+
+        # Returns a range that indicates the destination (right) cardinality.
+        attr_reader :destination_range
+
+        # Create a new cardinality based on a source range and a destination
+        # range. These ranges describe which number of values are valid.
+        def initialize(source_range, destination_range) # @private :nodoc:
+          @source_range = compose_range(source_range)
+          @destination_range = compose_range(destination_range)
+        end
+
+        # Returns the name of this cardinality, based on its two cardinal
+        # numbers (for source and destination). Can be any of
+        # +:one_to_one:+, +:one_to_many+, or +:many_to_many+. The name
+        # +:many_to_one+ also exists, but Rails ERD always normalises these
+        # kinds of relationships by inverting them, so they become
+        # +:one_to_many+ associations.
+        #
+        # You can also call the equivalent method with a question mark, which
+        # will return true if the name corresponds to that method. For example:
+        #
+        #   cardinality.one_to_one?
+        #   #=> true
+        #   cardinality.one_to_many?
+        #   #=> false
+        def name
+          CLASSES[cardinality_class]
+        end
+
+        # Returns +true+ if the source (left side) is not mandatory.
+        def source_optional?
+          source_range.first < 1
+        end
+
+        # Returns +true+ if the destination (right side) is not mandatory.
+        def destination_optional?
+          destination_range.first < 1
+        end
+
+        # Returns the inverse cardinality. Destination becomes source, source
+        # becomes destination.
+        def inverse
+          self.class.new destination_range, source_range
+        end
+
+        CLASSES.each do |cardinality_class, name|
+          class_eval <<-RUBY
+            def #{name}?
+              cardinality_class == #{cardinality_class.inspect}
+            end
+          RUBY
+        end
+
+        def ==(other) # @private :nodoc:
+          source_range == other.source_range and destination_range == other.destination_range
+        end
+
+        def <=>(other) # @private :nodoc:
+          (cardinality_class <=> other.cardinality_class).nonzero? or
+          compare_with(other) { |x| x.source_range.first + x.destination_range.first }.nonzero? or
+          compare_with(other) { |x| x.source_range.last + x.destination_range.last }.nonzero? or
+          compare_with(other) { |x| x.source_range.last }.nonzero? or
+          compare_with(other) { |x| x.destination_range.last }
+        end
+
+        # Returns an array with the cardinality classes for the source and
+        # destination of this cardinality. Possible return values are:
+        # <tt>[1, 1]</tt>, <tt>[1, N]</tt>, <tt>[N, N]</tt>, and (in theory)
+        # <tt>[N, 1]</tt>.
+        def cardinality_class
+          [source_cardinality_class, destination_cardinality_class]
+        end
+
+        protected
+
+        # The cardinality class of the source (left side). Either +1+ or +Infinity+.
+        def source_cardinality_class
+          source_range.last == 1 ? 1 : N
+        end
+
+        # The cardinality class of the destination (right side). Either +1+ or +Infinity+.
+        def destination_cardinality_class
+          destination_range.last == 1 ? 1 : N
+        end
+
+        private
+
+        def compose_range(r)
+          return r..r if r.kind_of?(Integer) && r > 0
+          return (r.begin)..(r.end - 1) if r.exclude_end?
+          r
+        end
+
+        def compare_with(other, &block)
+          yield(self) <=> yield(other)
+        end
+      end
+    end
+  end
+end