gadget 0.5.4 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 18e3c423cd66791b21ebc7240290b6698656370f
-  data.tar.gz: 11c63cb1a1c7cdef27a822cc5c535d1eb6e5c759
+  metadata.gz: b2bf83e177e0c22d39fbdd338c5df052bcf7ea6e
+  data.tar.gz: 092f282fbacd8cb1858bbf96fff28e4cd74033e6
 SHA512:
-  metadata.gz: d2288ae89e92612f0c95a7167a0525b135768183558be94b12ca9dd4149181eb1230665b4b5c403ebf6ef955633e8c04fdbc3d0aa45b5ae3082b55389b63fc5d
-  data.tar.gz: f8b3889fb07d5c4a7e50cddc663b8f40391044990437a3a9ddfecf3e77e0ec8b31a74b719e6f9564134b49ad0091d1e622f05e4d819b45edc307f247607688c7
+  metadata.gz: e4dd82afa75702c5c8953d4dceb7086cde36b787365d61e0a6441f6edd25e79fc3322ac92654a60972279ff9988b3f470618f95bf78883ecccf66296cfd7c564
+  data.tar.gz: ee495b40222d0a17d18864d526ea84af4e2721204b016fe6639e8870093423dc49c974872ecdda070162cad9271bb536d475a4af3ad8d9c8877dab293944fc25

data/lib/gadget.rb

@@ -5,6 +5,24 @@ require 'tsort'
 
 require 'gadget/version'
 
+## monkey patch Hash to gain .extractable_options?
+class Hash
+  def extractable_options?
+    instance_of?(Hash)
+  end
+end
+
+## monkey patch Array to gain .extract_options!
+class Array
+  def extract_options!
+    if last.is_a?(Hash) && last.extractable_options?
+      pop
+    else
+      {}
+    end
+  end
+end
+
 module Gadget
 
   class TsortableHash < Hash
@@ -15,7 +33,21 @@ module Gadget
     end
   end
 
-  def self.tables(conn)
+  # Return a collection enumerating the tables in a database.
+  #
+  # ==== Usage
+  #   tables = Gadget.tables(conn)
+  #
+  # ==== Parameters
+  # * +conn+ - a +PG::Connection+ to the database
+  #
+  # ==== Returns
+  # * a Hash:
+  #   table name::  a Hash:
+  #     +:oid+::  the table's OID
+  def self.tables(conn, *args)
+    _ = args.extract_options!
+
     sql = <<-END_OF_SQL
 SELECT c.oid, t.tablename
 FROM pg_catalog.pg_tables t
@@ -33,15 +65,34 @@ WHERE t.schemaname='public'
     tuples
   end
 
-  def self.columns(conn, tablename = nil)
+  # Return a collection enumerating the columns in a table or database.
+  #
+  # ==== Usage
+  #   columns = Gadget.columns(conn)
+  #   columns_in_table = Gadget.columns(conn, 'tablename')
+  #
+  # ==== Parameters
+  # * +conn+ - a +PG::Connection+ to the database
+  # * +tablename - if given, return columns only for the named table
+  #
+  # ==== Returns
+  # * a Hash:
+  #   table name::  a Hash:
+  #     +:columns+::  an Array of column names
+  def self.columns(conn, *args)
+    options = args.extract_options!
+    tablename = args.shift
+
     sql = <<-END_OF_SQL
 SELECT t.tablename, a.attname
 FROM pg_catalog.pg_attribute a
 INNER JOIN pg_catalog.pg_class c ON a.attrelid = c.oid
 INNER JOIN pg_catalog.pg_tables t ON c.relname = t.tablename
 WHERE a.attnum >= 0
-AND a.attisdropped IS FALSE
     END_OF_SQL
+    unless options[:include_dropped]
+      sql += " AND a.attisdropped IS FALSE"
+    end
     if tablename.nil?
       rs = conn.exec(sql)
     else
@@ -57,7 +108,28 @@ AND a.attisdropped IS FALSE
     tuples
   end
 
-  def self.foreign_keys(conn, tablename = nil)
+  # Return a collection enumerating the foreign keys in a table or database.
+  #
+  # ==== Usage
+  #   fks = Gadget.foreign_keys(conn)
+  #   fks_in_table = Gadget.foreign_keys(conn, 'tablename')
+  #
+  # ==== Parameters
+  # * +conn+ - a +PG::Connection+ to the database
+  # * +tablename - if given, return foreign keys only for the named table
+  #
+  # ==== Returns
+  # * a Hash:
+  #   table name::  a Hash:
+  #     +:refs+::   an Array of Hashes:
+  #       +:name+::       the name of the foreign key
+  #       +:cols+::       the columns in _this table_ that make up the foreign key
+  #       +:ref_name+::   the name of the table referred to by this foreign key
+  #       +:ref_cols+::   the columns in _the other table_ that are referred to by this foreign key
+  def self.foreign_keys(conn, *args)
+    _ = args.extract_options!
+    tablename = args.shift
+
     sql = <<-END_OF_SQL
 SELECT pg_constraint.conname AS name,
        t1.tablename AS tablename, pg_constraint.conkey AS cols,
@@ -80,13 +152,13 @@ AND pg_constraint.contype = 'f'
     tuples = rs.reduce({}) do | h, row |
       name = row['tablename']
       h[name] ||= { :refs => [] }
-      col_names = self.columns(conn, name)[name][:columns]
-      refcol_names = self.columns(conn, row['refname'])[row['refname']][:columns]
+      col_names = self.columns(conn, name, :include_dropped => true)[name][:columns]
+      refcol_names = self.columns(conn, row['refname'], :include_dropped => true)[row['refname']][:columns]
       new_ref = {
         :name => row['name'],
         :cols => row['cols'].sub(/\A\{|\}\z/, '').split(',').map { | idx | col_names[idx.to_i - 1] },
-        :refname => row['refname'],
-        :refcols => row['refcols'].sub(/\A\{|\}\z/, '').split(',').map { | idx | refcol_names[idx.to_i - 1] },
+        :ref_name => row['refname'],
+        :ref_cols => row['refcols'].sub(/\A\{|\}\z/, '').split(',').map { | idx | refcol_names[idx.to_i - 1] },
       }
       h[name][:refs] << new_ref
       h
@@ -95,7 +167,32 @@ AND pg_constraint.contype = 'f'
     tuples
   end
 
-  def self.constraints(conn, tablename = nil)
+  # Return a collection enumerating the constraints in a table or database.
+  #
+  # ==== Usage
+  #   constraints = Gadget.constraints(conn)
+  #   constraints_in_table = Gadget.constraints(conn, 'tablename')
+  #
+  # ==== Parameters
+  # * +conn+ - a +PG::Connection+ to the database
+  # * +tablename - if given, return constraints only for the named table
+  #
+  # ==== Returns
+  # * a Hash:
+  #   table name::  a Hash:
+  #     +:constraints+::  an Array of Hashes:
+  #       +:name+::   the name of the constraint
+  #       +:kind+::   the kind of the constraint:
+  #         * +check+
+  #         * +exclusion+
+  #         * +foreign key+
+  #         * +primary key+
+  #         * +trigger+
+  #         * +unique+
+  def self.constraints(conn, *args)
+    _ = args.extract_options!
+    tablename = args.shift
+
     sql = <<-END_OF_SQL
 SELECT pg_constraint.conname AS name,
        pg_constraint.contype AS constrainttype,
@@ -140,24 +237,61 @@ WHERE t.schemaname = 'public'
     tuples
   end
 
-  def self.dependencies(conn)
+  # Return a collection enumerating the dependencies between tables in a database.
+  # A table +a+ is considered to be dependent on a table +b+ if +a+ has a foreign key constraint
+  # that refers to +b+.
+  #
+  # ==== Usage
+  #   dependencies = Gadget.dependencies(conn)
+  #
+  # ==== Parameters
+  # * +conn+ - a +PG::Connection+ to the database
+  #
+  # ==== Returns
+  # * a Hash:
+  #   table name::  an Array of table names
+  def self.dependencies(conn, *args)
+    _ = args.extract_options!
+
     tables = self.tables(conn)
     foreign_keys = self.foreign_keys(conn)
-    dependencies = tables.reduce({}) do | h, (tablename, _) |
+    tables.reduce({}) do | h, (tablename, _) |
       h[tablename] = []
       refs = foreign_keys[tablename]
       unless refs.nil?
-        refs[:refs].each { | ref | h[tablename] << ref[:refname] }
+        refs[:refs].each { | ref | h[tablename] << ref[:ref_name] }
       end
       h
     end
   end
 
-  def self.tables_in_dependency_order(conn)
+  # Return a collection enumerating the tables in a database in dependency order.
+  # If a table +a+ is dependent on a table +b+, then +a+ will appear _after_ +b+ in the collection.
+  #
+  # ==== Usage
+  #   dependencies = Gadget.dependencies(conn)
+  #
+  # ==== Parameters
+  # * +conn+ - a +PG::Connection+ to the database
+  #
+  # ==== Returns
+  # * a Hash:
+  #   table name::  an Array of table names
+  def self.tables_in_dependency_order(conn, *args)
+    _ = args.extract_options!
     self.dependencies(conn).reduce(TsortableHash.new) { | h, (k, v) | h[k] = v; h }.tsort
   end
 
-  def self.dependency_graph(conn)
+  # Print dot (Graphviz data format) describing the dependency graph for a database to stdout.
+  #
+  # ==== Usage
+  #   Gadget.dependency_graph(conn)
+  #
+  # ==== Parameters
+  # * +conn+ - a +PG::Connection+ to the database
+  def self.dependency_graph(conn, *args)
+    _ = args.extract_options!
+
     puts "digraph dependencies {"
     self.dependencies(conn).each do | tablename, deps |
       if deps.empty?
@@ -169,7 +303,22 @@ WHERE t.schemaname = 'public'
     puts "}"
   end
 
-  def self.functions(conn)
+  # Return a collection enumerating the functions in a database.
+  #
+  # ==== Usage
+  #   functions = Gadget.functions(conn)
+  #
+  # ==== Parameters
+  # * +conn+ - a +PG::Connection+ to the database
+  #
+  # ==== Returns
+  # * a Hash:
+  #   function name::  a Hash:
+  #     +:oid+::        the function's OID
+  #     +:arg_types+::  the type IDs for the arguments to the function
+  def self.functions(conn, *args)
+    _ = args.extract_options!
+
     rs = conn.exec(<<-END_OF_SQL)
 SELECT p.oid, p.proname, p.proargtypes
 FROM pg_catalog.pg_proc p
@@ -188,7 +337,21 @@ WHERE n.nspname = 'public'
     tuples
   end
 
-  def self.sequences(conn)
+  # Return a collection enumerating the sequences in a database.
+  #
+  # ==== Usage
+  #   sequences = Gadget.sequences(conn)
+  #
+  # ==== Parameters
+  # * +conn+ - a +PG::Connection+ to the database
+  #
+  # ==== Returns
+  # * a Hash:
+  #   sequence name::  a Hash:
+  #     +:oid+::  the sequence's OID
+  def self.sequences(conn, *args)
+    _ = args.extract_options!
+
     sql = <<-END_OF_SQL
 SELECT c.oid, c.relname
 FROM pg_catalog.pg_class c
@@ -207,8 +370,25 @@ AND n.nspname = 'public'
     tuples
   end
 
-  def self.triggers(conn)
-    rs = conn.exec(<<-END_OF_SQL)
+  # Return a collection enumerating the triggers in a database.
+  #
+  # ==== Usage
+  #   triggers = Gadget.triggers(conn)
+  #
+  # ==== Parameters
+  # * +conn+ - a +PG::Connection+ to the database
+  #
+  # ==== Returns
+  # * a Hash:
+  #   trigger name::  a Hash:
+  #     +:oid+::            the trigger's OID
+  #     +:table_name+::     the table on which the trigger is defined
+  #     +:function_name+::  the name of the trigger's function
+  def self.triggers(conn, *args)
+    _ = args.extract_options!
+    tablename = args.shift
+
+    sql = <<-END_OF_SQL
 SELECT tg.oid, tg.tgname, t.tablename, p.proname
 FROM pg_catalog.pg_trigger tg
 INNER JOIN pg_catalog.pg_class c ON tg.tgrelid = c.oid
@@ -216,12 +396,17 @@ INNER JOIN pg_catalog.pg_tables t ON c.relname = t.tablename
 INNER JOIN pg_catalog.pg_proc p ON tg.tgfoid = p.oid
 WHERE tg.tgconstrrelid = 0
     END_OF_SQL
-
+    if tablename.nil?
+      rs = conn.exec(sql)
+    else
+      sql += " AND t.tablename = $1"
+      rs = conn.exec_params(sql, [ tablename ])
+    end
     tuples = rs.reduce({}) do | h, row |
       h[row['tgname']] = {
         :oid => row['oid'].to_i,
-        :tablename => row['tablename'],
-        :functionname => row['proname'],
+        :table_name => row['tablename'],
+        :function_name => row['proname'],
       }
       h
     end
@@ -229,7 +414,21 @@ WHERE tg.tgconstrrelid = 0
     tuples
   end
 
-  def self.types(conn)
+  # Return a collection enumerating the types in a database.
+  #
+  # ==== Usage
+  #   types = Gadget.types(conn)
+  #
+  # ==== Parameters
+  # * +conn+ - a +PG::Connection+ to the database
+  #
+  # ==== Returns
+  # * a Hash:
+  #   type name::  a Hash:
+  #     +:oid+::  the type's OID
+  def self.types(conn, *args)
+    _ = args.extract_options!
+
     rs = conn.exec(<<-END_OF_SQL)
 SELECT t.oid, t.typname
 FROM pg_catalog.pg_type t

data/lib/gadget/version.rb

@@ -1,3 +1,3 @@
 module Gadget
-  VERSION = "0.5.4"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gadget
 version: !ruby/object:Gem::Version
-  version: 0.5.4
+  version: 0.6.0
 platform: ruby
 authors:
 - Craig S. Cottingham
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-25 00:00:00.000000000 Z
+date: 2014-03-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pg