sequel-pg-comment 1.0.0

data/lib/sequel/extensions/pg_comment/create_table_generator_methods.rb

@@ -0,0 +1,159 @@
+#:nodoc:
+# Enhancements to the standard schema modification methods in a
+# block-form `create_table` method, to support setting comments via the
+# `:comment` option.
+#
+module Sequel::Extension::PgComment::CreateTableGeneratorMethods
+	# An array of all the comments that this generator has seen fit to
+	# create.
+	#
+	# @return [Array<SqlGenerator>]
+	#
+	attr_reader :comments
+
+	include Sequel::Extension::PgComment
+
+	# Enhanced version of the `column` table definition method, which
+	# supports setting a comment on the column.
+	#
+	# @option [String] :comment The comment to set on the column that is
+	#   being defined.
+	#
+	def column(*args)
+		super
+
+		if args.last.is_a?(Hash) && args.last[:comment]
+			comments << SqlGenerator.create(:column, args.first, args.last[:comment])
+		end
+	end
+
+	# Enhanced version of the `primary_key` table definition method, which
+	# supports setting a comment on either the column or constraint.
+	#
+	# If the primary key is composite (`name` is an array), then the comment
+	# will be placed on the index.  Otherwise, the comment will be set
+	# on the column itself.
+	#
+	# @option [String] :comment The comment to set on the column or
+	#   index that is being defined.
+	#
+	def primary_key(name, *args)
+		if args.last.is_a?(Hash) && args.last[:comment] and !name.is_a? Array
+			# The composite primary key case will be handled by the
+			# `composite_primary_key` method, so we don't have to deal with it
+			# here.
+			comments << SqlGenerator.create(:column, name, args.last[:comment])
+		end
+				
+		super
+	end
+
+	# Enhanced version of the `composite_primary_key` table definition method,
+	# which supports setting a comment on the primary key index.
+	#
+	# @option [String] :comment The comment to set on the primary key index.
+	#
+	def composite_primary_key(columns, *args)
+		if args.last.is_a?(Hash) and args.last[:comment]
+			if args.last[:name]
+				comments << SqlGenerator.create(
+				              :index,
+				              args.last[:name],
+				              args.last[:comment]
+				            )
+			else
+				comments << PrefixSqlGenerator.new(:index, :_pkey, args.last[:comment])
+			end
+		end
+
+		super
+	end
+
+	# Enhanced version of the `composite_foreign_key` table definition method,
+	# which supports setting a comment on the FK constraint.
+	#
+	# @option [String] :comment The comment to set on the foreign key constraint.
+	#
+	def composite_foreign_key(columns, opts)
+		if opts.is_a?(Hash) and opts[:comment] and opts[:table]
+			if opts[:name]
+				comments << SqlGenerator.create(
+				              :constraint,
+				              opts[:name],
+				              opts[:comment]
+				            )
+			else
+				comments << SqlGenerator.create(
+				              :constraint,
+				              "#{opts[:table]}_#{columns.first}_fkey".to_sym,
+				              opts[:comment]
+				            )
+			end
+		end
+
+		super
+	end
+
+	# Enhanced version of the `index` table definition method,
+	# which supports setting a comment on the index.
+	#
+	# @option [String] :comment The comment to set on the index that is being
+	#   defined.
+	#
+	def index(columns, opts = OPTS)
+		if opts[:comment]
+			if opts[:name]
+				comments << SqlGenerator.create(:index, opts[:name], opts[:comment])
+			else
+				comments << PrefixSqlGenerator.new(
+				              :index,
+				              ("_" + [columns].flatten.map(&:to_s).join('_') + "_index").to_sym,
+				              opts[:comment]
+				            )
+			end
+		end
+		
+		super
+	end
+
+	# Enhanced version of the `unique` table definition method,
+	# which supports setting a comment on the unique index.
+	#
+	# @option [String] :comment The comment to set on the index that will be
+	#   defined.
+	#
+	def unique(columns, opts = OPTS)
+		if opts[:comment]
+			if opts[:name]
+				comments << SqlGenerator.create(:index, opts[:name], opts[:comment])
+			else
+				comments << PrefixSqlGenerator.new(
+				              :index,
+				              ("_" + [columns].flatten.map(&:to_s).join('_') + "_key").to_sym,
+				              opts[:comment]
+				            )
+			end
+		end
+		
+		super
+	end
+
+	# Enhanced version of the `constraint` table definition method,
+	# which supports setting a comment on the constraint.
+	#
+	# @option [String] :comment The comment to set on the constraint that is
+	#   being defined.
+	#
+	def constraint(name, *args, &block)
+		opts = name.is_a?(Hash) ? name : (args.last.is_a?(Hash) ? args.last : {})
+		
+		if opts[:comment]
+			if name
+				comments << SqlGenerator.create(:constraint, name, opts[:comment])
+			else
+				raise RuntimeError,
+				      "Setting comments on unnamed or check constraints is not supported"
+			end
+		end
+	end
+end

data/lib/sequel/extensions/pg_comment/database_methods.rb

@@ -0,0 +1,175 @@
+# Support for setting and retrieving comments on all object types
+# in a PostgreSQL database.
+#
+module Sequel::Extension::PgComment::DatabaseMethods
+	# Set the comment for a database object.
+	#
+	# @param type [#to_s] The type of object that you wish to comment on.
+	#   This can either be a string or symbol.  Any object type that PgSQL
+	#   knows about should be fair game.  The current list of object types
+	#   that this plugin knows about (and hence will accept) is listed in
+	#   the {Sequel::Extension::PgComment::OBJECT_TYPES} array.
+	#
+	# @param id [#to_s] The name of the object that you wish to comment on.
+	#   For most types of object, this should be the literal name of the
+	#   object.  However, for columns in a table or view, you should separate
+	#   the table/view name from the column name with a double underscore
+	#   (ie `__`).  This is the standard Sequel convention for such things.
+	#
+	# @param comment [String] The comment you wish to set for the database
+	#   object.
+	#
+	# @see {Sequel::Extension::PgComment.normalise_comment} for details on
+	#   how the comment string is interpreted.
+	#
+	def comment_on(type, id, comment)
+		gen = begin
+			Sequel::Extension::PgComment::SqlGenerator.create(type, id, comment)
+		rescue ArgumentError
+			raise ArgumentError,
+					"Invalid object type: #{type.inspect}"
+		end
+
+		execute(gen.generate)
+	end
+
+	# Retrieve the comment for a database object.
+	#
+	# @param object [#to_s] The name of the database object to retrieve.  For
+	#   most objects, this should be the literal name of the object. 
+	#   However, for columns on tables and views, the name of the table/view
+	#   should be a separated from the name of the column by a double
+	#   underscore (ie `__`).
+	#
+	# @return [String, NilClass] The comment on the object, or `nil` if no
+	#   comment has been defined for the object.
+	#
+	def comment_for(object)
+		object = object.to_s
+
+		if object.index("__")
+			tbl, col = object.split("__", 2)
+
+			execute("SELECT col_description(c.oid, a.attnum) " +
+					  "FROM pg_class c JOIN pg_attribute a " +
+					  "ON (c.oid=a.attrelid) " +
+					  "WHERE c.relname=#{literal(tbl)} " +
+					  "AND a.attname=#{literal(col)}"
+					 )
+		else
+			execute("SELECT obj_description(#{literal(object.to_s)}::regclass, 'pg_class')")
+		end
+	end
+
+	# An enhanced form of the standard `create_table` method, which supports
+	# setting a comment in the `create_table` call when the `:comment` option
+	# is provided.
+	#
+	# @option [String] :comment The comment to set on the newly-created table.
+	#
+	# @see [Sequel::Database#create_table](http://sequel.jeremyevans.net/rdoc/classes/Sequel/Database.html#method-i-create_table)
+	#
+	def create_table(*args)
+		super
+
+		if args.last.is_a?(Hash) && args.last[:comment]
+			comment_on(:table, args.first, args.last[:comment])
+		end
+	end
+
+	#:nodoc:
+	# Enhanced version to support setting comments on objects created in a
+	# block-form `create_table` statement.
+	#
+	def create_table_generator(&block)
+		super do
+			extend Sequel::Extension::PgComment::CreateTableGeneratorMethods
+			@comments = []
+			instance_eval(&block) if block
+		end
+	end
+
+	#:nodoc:
+	# Enhanced version to support setting comments on objects created in a
+	# block-form `create_table` statement.
+	#
+	# If you're wondering why we override the
+	# create_table_indexes_from_generator method, rather than
+	# create_table_from_generator, it's because the indexes method runs last,
+	# and we can only create our comments after the objects we're commenting
+	# on have been created.  We *could* set some comments in
+	# create_table_from_generator, and then set index comments in
+	# create_table_indexes_from_generator, but why override two methods when
+	# you can just override one to get the same net result?
+	#
+	def create_table_indexes_from_generator(name, generator, options)
+		super
+
+		generator.comments.each do |sql_gen|
+			if sql_gen.respond_to? :table_name
+				sql_gen.table_name = name
+			end
+
+			execute(sql_gen.generate)
+		end
+	end
+
+	#:nodoc:
+	# Enhanced version to support setting comments on objects created in a
+	# block-form `alter_table` statement.
+	#
+	def alter_table_generator(&block)
+		super do
+			extend Sequel::Extension::PgComment::AlterTableGeneratorMethods
+			@comments = []
+			instance_eval(&block) if block
+		end
+	end
+
+	#:nodoc:
+	# Enhanced version to support setting comments on objects created in a
+	# block-form `alter_table` statement.
+	#
+	def apply_alter_table_generator(name, generator)
+		super
+
+		generator.comments.each do |sql_gen|
+			if sql_gen.respond_to?(:table_name=)
+				sql_gen.table_name = name
+			end
+
+			execute(sql_gen.generate)
+		end
+	end
+
+	# An enhanced form of the standard `create_view` method, which supports
+	# setting a comment in the `create_view` call when the `:comment` option
+	# is provided.
+	#
+	# @option [String] :comment The comment to set on the newly-created view.
+	#
+	# @see [Sequel::Database#create_view](http://sequel.jeremyevans.net/rdoc/classes/Sequel/Database.html#method-i-create_view)
+	#
+	def create_view(*args)
+		super
+
+		if args.last.is_a?(Hash) && args.last[:comment]
+			comment_on(:view, args.first, args.last[:comment])
+		end
+	end
+
+	private
+
+	# Quote an object name, handling the double underscore convention
+	# for separating a column name from its containing object.
+	#
+	def quote_comment_identifier(id)
+		id = id.to_s
+		if id.index("__")
+			tbl, col = id.split("__", 2)
+			quote_identifier(tbl) + "." + quote_identifier(col)
+		else
+			quote_identifier(id)
+		end
+	end
+end

data/lib/sequel/extensions/pg_comment/dataset_methods.rb

@@ -0,0 +1,22 @@
+# Support for retrieving column comments from a PostgreSQL database
+# via a dataset.  For example:
+#
+#    DB[:foo_tbl].comment_for(:some_column)
+#
+# Will retrieve the comment for `foo_tbl.some_column`, if such a
+# column exists.
+#
+module Sequel::Extension::PgComment::DatasetMethods
+	# Retrieve the comment for the column named `col` in the "primary" table
+	# for this dataset.
+	#
+	# @param col [#to_s] The name of the column for which to retrieve the
+	#   comment.
+	#
+	# @return [String, NilClass] The comment defined for the column, or
+	#   `nil` if there is no defined comment.
+	#
+	def comment_for(col)
+		db.comment_for("#{first_source_table}__#{col}")
+	end
+end

data/lib/sequel/extensions/pg_comment/sql_generator.rb

@@ -0,0 +1,257 @@
+module Sequel::Extension::PgComment
+	#:nodoc:
+	# Generate SQL to set a comment.
+	#
+	class SqlGenerator
+		# The PostgreSQL object types which this class knows how to generate
+		# comment SQL for.
+		#
+		OBJECT_TYPES = %w{AGGREGATE
+		                  CAST
+		                  COLLATION
+		                  CONVERSION
+		                  DATABASE
+		                  DOMAIN
+								EXTENSION
+								EVENT\ TRIGGER
+								FOREIGN\ DATA\ WRAPPER
+								FOREIGN\ TABLE
+								FUNCTION
+								INDEX
+								LARGE\ OBJECT
+								MATERIALIZED\ VIEW
+								OPERATOR
+								OPERATOR\ CLASS
+								OPERATOR\ FAMILY
+								PROCEDURAL\ LANGUAGE
+								LANGUAGE
+								ROLE
+								SCHEMA
+								SEQUENCE
+								SERVER
+								TABLE
+								TABLESPACE
+								TEXT\	SEARCH\ CONFIGURATION
+								TEXT\ SEARCH\ DICTIONARY
+								TEXT\ SEARCH\ PARSER
+								TEXT\ SEARCH\ TEMPLATE
+								TYPE
+								VIEW
+							}
+		
+		# Find the correct class for a given object type, and instantiate a
+		# new one of them.
+		#
+		# @param object_type [String, Symbol] The type of object we're going
+		#   to comment on.  Strings and symbols are both fine, and any case
+		#   is fine, too.  Any underscores get turned into spaces.  Apart from
+		#   that, it needs to be the exact name that PostgreSQL uses for the given
+		#   type.
+		#
+		# @param object_name [String, Symbol] The name of the database object to
+		#   set the comment on.  A string is considered "already quoted", and hence
+		#   is not escaped any further.  A symbol is run through the usual Sequel
+		#   identifier escaping code before being unleashed on the world.
+		#
+		# @param comment [String] The comment to set.
+		#
+		# @return [SqlGenerator] Some sort of `SqlGenerator` object, or a subclass.
+		#
+		# @raise [ArgumentError] if you passed in an `object_type` that we don't
+		#   know about.
+		#
+		def self.create(object_type, object_name, comment)
+			generators.each do |gclass|
+				if gclass.handles?(object_type)
+					return gclass.new(object_type, object_name, comment)
+				end
+			end
+
+			raise ArgumentError,
+			      "Unrecognised object type #{object_type.inspect}"
+		end
+
+		# Return whether or not this class supports the specified object type.
+		#
+		# @param object_type [String, Symbol] @see {.create}
+		#
+		# @return [TrueClass, FalseClass] whether or not this class can handle
+		#   the object type you passed.
+		#
+		def self.handles?(object_type)
+			self.const_get(:OBJECT_TYPES).include?(object_type.to_s.upcase.gsub('_', ' '))
+		end
+
+		private
+
+		# Return all known `SqlGenerator` classes.
+		#
+		def self.generators
+			@generators ||= ObjectSpace.each_object(Class).select do |klass|
+				klass.ancestors.include?(self)
+			end
+		end
+
+		# We just need this so we can quote things.
+		def self.mock_db
+			@mock_db ||= Sequel.connect("mock://postgres")
+		end
+
+		public
+
+		# The canonicalised string (that is, all-uppercase, with words
+		# separated by spaces) for the object type of this SQL generator.
+		#
+		attr_reader :object_type
+		
+		# The raw (might-be-a-symbol, might-be-a-string) object name that
+		# was passed to us originally.
+		#
+		attr_reader :object_name
+		
+		# The comment.
+		attr_reader :comment
+
+		# Spawn a new SqlGenerator.
+		#
+		# @see {.create}
+		#
+		def initialize(object_type, object_name, comment)
+			@object_type = object_type.to_s.upcase.gsub('_', ' ')
+			@object_name = object_name
+			@comment     = comment
+		end
+
+		# SQL to set a comment on the object of our affection.
+		#
+		# @return [String] The SQL needed to set the comment.
+		#
+		def generate
+			quoted_object_name = case object_name
+			when Symbol
+				literal object_name
+			else
+				object_name
+			end
+				
+			"COMMENT ON #{object_type} #{quoted_object_name} IS #{literal comment.to_s}"
+		end
+
+		private
+
+		# Quote the provided database object (a symbol) or string value
+		# (a string).
+		#
+		def literal(s)
+			self.class.mock_db.literal(s)
+		end
+	end
+
+	#:nodoc:
+	# A specialised generator for object types that live "inside" a
+	# table.  Specifically, those types are columns, constraints,
+	# rules, and triggers.
+	#
+	# They get their own subclass because these object types can be
+	# manipulated inside a `create_table` or `alter_table` block, and at the
+	# time the block is evaluated, the code doesn't know the name of the
+	# table in which they are contained.  So, we just stuff what we *do* know
+	# into these generators, and then when all's done, we can go to each of
+	# these generators, say "this is your table name", and then ask for the
+	# generated SQL.
+	#
+	class TableObjectSqlGenerator < SqlGenerator
+		# The few object types that this class handles.
+		OBJECT_TYPES = %w{COLUMN CONSTRAINT RULE TRIGGER}
+
+		# The name of the object which contains the object which is the direct
+		# target of this SQL generator.  Basically, it's the table name.
+		attr_accessor :table_name
+
+		# Overridden constructor to deal with the double-underscore-separated
+		# names that we all know and love.
+		#
+		# @see {SqlGenerator#initialize}
+		#
+		def initialize(object_type, object_name, comment)
+			super
+
+			if object_name.is_a?(Symbol) and object_name.to_s.index("__")
+				@table_name, @object_name = object_name.to_s.split("__", 2).map(&:to_sym)
+			end
+		end
+
+		# Generate special SQL.
+		#
+		# @see {SqlGenerator#generate}
+		#
+		def generate
+			if table_name.nil?
+				raise ArgumentError,
+				      "Cannot generate SQL for #{object_type} #{object_name} " +
+				        "without a table_name"
+			end
+
+			qualified_object_name = case object_type
+			when "COLUMN"
+				"#{maybe_escape table_name}.#{maybe_escape object_name}"
+			when "CONSTRAINT", "RULE", "TRIGGER"
+				"#{maybe_escape object_name} ON #{maybe_escape table_name}"
+			end
+			
+			"COMMENT ON #{object_type} #{qualified_object_name} IS #{literal comment}"
+		end
+
+		private
+		
+		# Handle with the vagaries of having both strings and symbols as
+		# possible names -- we escape symbols, but leave strings to their own
+		# devices.
+		#
+		def maybe_escape(s)
+			Symbol === s ? literal(s) : s
+		end
+	end
+
+	#:nodoc:
+	# This is an annoying corner-case generator -- it doesn't handle any
+	# types by default, but it will handle any *other* type where the name of
+	# a table needs to be prefixed by a name.  The only known use case for
+	# this at present is "implicit" (that is, automatically generated by the
+	# database) constraints and indexes that get prefixed by the table name,
+	# and which are generated at a time when the calling code doesn't know the
+	# name of the table that it is generating SQL for.
+	#
+	class PrefixSqlGenerator < SqlGenerator
+		# This class doesn't handle any object types directly, and must be
+		# instantiated directly when needed
+		OBJECT_TYPES = %w{}
+
+		# The name of the table which should be prefixed to the object name
+		# that was specified when this instance was created.
+		#
+		attr_accessor :table_name
+
+		# Generate super-dooper special SQL.
+		#
+		# @see {SqlGenerator#generate}
+		#
+		def generate
+			if table_name.nil?
+				raise ArgumentError,
+				      "Cannot generate SQL for #{object_type} #{object_name} " +
+				        "without a table_name"
+			end
+
+			prefixed_object_name = "#{table_name}#{object_name}"
+			
+			if Symbol === table_name || Symbol === object_name
+				prefixed_object_name = prefixed_object_name.to_sym
+			end
+
+			g = SqlGenerator.create(object_type, prefixed_object_name, comment)
+			g.table_name = table_name if g.respond_to? :table_name
+			g.generate
+		end
+	end
+end