pg 0.15.1 → 1.2.3

data/lib/pg/binary_decoder.rb

@@ -0,0 +1,23 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+module PG
+	module BinaryDecoder
+		# Convenience classes for timezone options
+		class TimestampUtc < Timestamp
+			def initialize(params={})
+				super(params.merge(flags: PG::Coder::TIMESTAMP_DB_UTC | PG::Coder::TIMESTAMP_APP_UTC))
+			end
+		end
+		class TimestampUtcToLocal < Timestamp
+			def initialize(params={})
+				super(params.merge(flags: PG::Coder::TIMESTAMP_DB_UTC | PG::Coder::TIMESTAMP_APP_LOCAL))
+			end
+		end
+		class TimestampLocal < Timestamp
+			def initialize(params={})
+				super(params.merge(flags: PG::Coder::TIMESTAMP_DB_LOCAL | PG::Coder::TIMESTAMP_APP_LOCAL))
+			end
+		end
+	end
+end # module PG

data/lib/pg/coder.rb

@@ -0,0 +1,104 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+module PG
+
+	class Coder
+
+		module BinaryFormatting
+			Params = { format: 1 }
+			def initialize( params={} )
+				super(params.merge(Params))
+			end
+		end
+
+
+		# Create a new coder object based on the attribute Hash.
+		def initialize(params={})
+			params.each do |key, val|
+				send("#{key}=", val)
+			end
+		end
+
+		def dup
+			self.class.new(to_h)
+		end
+
+		# Returns coder attributes as Hash.
+		def to_h
+			{
+				oid: oid,
+				format: format,
+				flags: flags,
+				name: name,
+			}
+		end
+
+		def ==(v)
+			self.class == v.class && to_h == v.to_h
+		end
+
+		def marshal_dump
+			Marshal.dump(to_h)
+		end
+
+		def marshal_load(str)
+			initialize Marshal.load(str)
+		end
+
+		def inspect
+			str = self.to_s
+			oid_str = " oid=#{oid}" unless oid==0
+			format_str = " format=#{format}" unless format==0
+			name_str = " #{name.inspect}" if name
+			str[-1,0] = "#{name_str} #{oid_str}#{format_str}"
+			str
+		end
+
+		def inspect_short
+			str = case format
+				when 0 then "T"
+				when 1 then "B"
+				else format.to_s
+			end
+			str += "E" if respond_to?(:encode)
+			str += "D" if respond_to?(:decode)
+
+			"#{name || self.class.name}:#{str}"
+		end
+	end
+
+	class CompositeCoder < Coder
+		def to_h
+			super.merge!({
+				elements_type: elements_type,
+				needs_quotation: needs_quotation?,
+				delimiter: delimiter,
+			})
+		end
+
+		def inspect
+			str = super
+			str[-1,0] = " elements_type=#{elements_type.inspect} #{needs_quotation? ? 'needs' : 'no'} quotation"
+			str
+		end
+	end
+
+	class CopyCoder < Coder
+		def to_h
+			super.merge!({
+				type_map: type_map,
+				delimiter: delimiter,
+				null_string: null_string,
+			})
+		end
+	end
+
+	class RecordCoder < Coder
+		def to_h
+			super.merge!({
+				type_map: type_map,
+			})
+		end
+	end
+end # module PG

data/lib/pg/connection.rb

@@ -1,6 +1,8 @@
-#!/usr/bin/env ruby
+# -*- ruby -*-
+# frozen_string_literal: true
 
 require 'pg' unless defined?( PG )
+require 'uri'
 
 # The PostgreSQL connection class. The interface for this class is based on
 # {libpq}[http://www.postgresql.org/docs/9.2/interactive/libpq.html], the C
@@ -34,53 +36,256 @@ class PG::Connection
 	def self::parse_connect_args( *args )
 		return '' if args.empty?
 
-		# This will be swapped soon for code that makes options like those required for
-		# PQconnectdbParams()/PQconnectStartParams(). For now, stick to an options string for
-		# PQconnectdb()/PQconnectStart().
+		hash_arg = args.last.is_a?( Hash ) ? args.pop : {}
+		option_string = ''
+		options = {}
 
 		# Parameter 'fallback_application_name' was introduced in PostgreSQL 9.0
 		# together with PQescapeLiteral().
-		if PG::Connection.instance_methods.find{|m| m.to_sym == :escape_literal }
-			appname = $0.sub(/^(.{30}).{4,}(.{30})$/){ $1+"..."+$2 }
-			appname = PG::Connection.quote_connstr( appname )
-			connopts = ["fallback_application_name=#{appname}"]
-		else
-			connopts = []
+		if PG::Connection.instance_methods.find {|m| m.to_sym == :escape_literal }
+			options[:fallback_application_name] = $0.sub( /^(.{30}).{4,}(.{30})$/ ){ $1+"..."+$2 }
 		end
 
-		# Handle an options hash first
-		if args.last.is_a?( Hash )
-			opthash = args.pop
-			opthash.each do |key, val|
-				connopts.push( "%s=%s" % [key, PG::Connection.quote_connstr(val)] )
+		if args.length == 1
+			case args.first
+			when URI, /\A#{URI::ABS_URI_REF}\z/
+				uri = URI(args.first)
+				options.merge!( Hash[URI.decode_www_form( uri.query )] ) if uri.query
+			when /=/
+				# Option string style
+				option_string = args.first.to_s
+			else
+				# Positional parameters
+				options[CONNECT_ARGUMENT_ORDER.first.to_sym] = args.first
+			end
+		else
+			max = CONNECT_ARGUMENT_ORDER.length
+			raise ArgumentError,
+				"Extra positional parameter %d: %p" % [ max + 1, args[max] ] if args.length > max
+
+			CONNECT_ARGUMENT_ORDER.zip( args ) do |(k,v)|
+				options[ k.to_sym ] = v if v
 			end
 		end
 
-		# Option string style
-		if args.length == 1 && args.first.to_s.index( '=' )
-			connopts.unshift( args.first )
+		options.merge!( hash_arg )
 
-		# Append positional parameters
+		if uri
+			uri.host     = nil if options[:host]
+			uri.port     = nil if options[:port]
+			uri.user     = nil if options[:user]
+			uri.password = nil if options[:password]
+			uri.path     = '' if options[:dbname]
+			uri.query    = URI.encode_www_form( options )
+			return uri.to_s.sub( /^#{uri.scheme}:(?!\/\/)/, "#{uri.scheme}://" )
 		else
-			args.each_with_index do |val, i|
-				next unless val # Skip nil placeholders
+			option_string += ' ' unless option_string.empty? && options.empty?
+			return option_string + options.map { |k,v| "#{k}=#{quote_connstr(v)}" }.join( ' ' )
+		end
+	end
+
+
+	#  call-seq:
+	#     conn.copy_data( sql [, coder] ) {|sql_result| ... } -> PG::Result
+	#
+	# Execute a copy process for transfering data to or from the server.
+	#
+	# This issues the SQL COPY command via #exec. The response to this
+	# (if there is no error in the command) is a PG::Result object that
+	# is passed to the block, bearing a status code of PGRES_COPY_OUT or
+	# PGRES_COPY_IN (depending on the specified copy direction).
+	# The application should then use #put_copy_data or #get_copy_data
+	# to receive or transmit data rows and should return from the block
+	# when finished.
+	#
+	# #copy_data returns another PG::Result object when the data transfer
+	# is complete. An exception is raised if some problem was encountered,
+	# so it isn't required to make use of any of them.
+	# At this point further SQL commands can be issued via #exec.
+	# (It is not possible to execute other SQL commands using the same
+	# connection while the COPY operation is in progress.)
+	#
+	# This method ensures, that the copy process is properly terminated
+	# in case of client side or server side failures. Therefore, in case
+	# of blocking mode of operation, #copy_data is preferred to raw calls
+	# of #put_copy_data, #get_copy_data and #put_copy_end.
+	#
+	# _coder_ can be a PG::Coder derivation
+	# (typically PG::TextEncoder::CopyRow or PG::TextDecoder::CopyRow).
+	# This enables encoding of data fields given to #put_copy_data
+	# or decoding of fields received by #get_copy_data.
+	#
+	# Example with CSV input format:
+	#   conn.exec "create table my_table (a text,b text,c text,d text)"
+	#   conn.copy_data "COPY my_table FROM STDIN CSV" do
+	#     conn.put_copy_data "some,data,to,copy\n"
+	#     conn.put_copy_data "more,data,to,copy\n"
+	#   end
+	# This creates +my_table+ and inserts two CSV rows.
+	#
+	# The same with text format encoder PG::TextEncoder::CopyRow
+	# and Array input:
+	#   enco = PG::TextEncoder::CopyRow.new
+	#   conn.copy_data "COPY my_table FROM STDIN", enco do
+	#     conn.put_copy_data ['some', 'data', 'to', 'copy']
+	#     conn.put_copy_data ['more', 'data', 'to', 'copy']
+	#   end
+	#
+	# Example with CSV output format:
+	#   conn.copy_data "COPY my_table TO STDOUT CSV" do
+	#     while row=conn.get_copy_data
+	#       p row
+	#     end
+	#   end
+	# This prints all rows of +my_table+ to stdout:
+	#   "some,data,to,copy\n"
+	#   "more,data,to,copy\n"
+	#
+	# The same with text format decoder PG::TextDecoder::CopyRow
+	# and Array output:
+	#   deco = PG::TextDecoder::CopyRow.new
+	#   conn.copy_data "COPY my_table TO STDOUT", deco do
+	#     while row=conn.get_copy_data
+	#       p row
+	#     end
+	#   end
+	# This receives all rows of +my_table+ as ruby array:
+	#   ["some", "data", "to", "copy"]
+	#   ["more", "data", "to", "copy"]
 
-				key = CONNECT_ARGUMENT_ORDER[ i ] or
-					raise ArgumentError, "Extra positional parameter %d: %p" % [ i+1, val ]
-				connopts.push( "%s=%s" % [key, PG::Connection.quote_connstr(val.to_s)] )
+	def copy_data( sql, coder=nil )
+		res = exec( sql )
+
+		case res.result_status
+		when PGRES_COPY_IN
+			begin
+				if coder
+					old_coder = self.encoder_for_put_copy_data
+					self.encoder_for_put_copy_data = coder
+				end
+				yield res
+			rescue Exception => err
+				errmsg = "%s while copy data: %s" % [ err.class.name, err.message ]
+				put_copy_end( errmsg )
+				get_result
+				raise
+			else
+				put_copy_end
+				get_last_result
+			ensure
+				self.encoder_for_put_copy_data = old_coder if coder
 			end
-		end
 
-		return connopts.join(' ')
-	end
+		when PGRES_COPY_OUT
+			begin
+				if coder
+					old_coder = self.decoder_for_get_copy_data
+					self.decoder_for_get_copy_data = coder
+				end
+				yield res
+			rescue Exception => err
+				cancel
+				while get_copy_data
+				end
+				while get_result
+				end
+				raise
+			else
+				res = get_last_result
+				if !res || res.result_status != PGRES_COMMAND_OK
+					while get_copy_data
+					end
+					while get_result
+					end
+					raise PG::NotAllCopyDataRetrieved, "Not all COPY data retrieved"
+				end
+				res
+			ensure
+				self.decoder_for_get_copy_data = old_coder if coder
+			end
 
+		else
+			raise ArgumentError, "SQL command is no COPY statement: #{sql}"
+		end
+	end
 
 	# Backward-compatibility aliases for stuff that's moved into PG.
 	class << self
 		define_method( :isthreadsafe, &PG.method(:isthreadsafe) )
 	end
-end # class PG::Connection
 
-# Backward-compatible alias
-PGconn = PG::Connection
 
+	### Returns an array of Hashes with connection defaults. See ::conndefaults
+	### for details.
+	def conndefaults
+		return self.class.conndefaults
+	end
+
+	### Return the Postgres connection defaults structure as a Hash keyed by option
+	### keyword (as a Symbol).
+	###
+	### See also #conndefaults
+	def self.conndefaults_hash
+		return self.conndefaults.each_with_object({}) do |info, hash|
+			hash[ info[:keyword].to_sym ] = info[:val]
+		end
+	end
+
+	### Returns a Hash with connection defaults. See ::conndefaults_hash
+	### for details.
+	def conndefaults_hash
+		return self.class.conndefaults_hash
+	end
+
+	# Method 'conninfo' was introduced in PostgreSQL 9.3.
+	if self.instance_methods.find{|m| m.to_sym == :conninfo }
+
+		### Return the Postgres connection info structure as a Hash keyed by option
+		### keyword (as a Symbol).
+		###
+		### See also #conninfo
+		def conninfo_hash
+			return self.conninfo.each_with_object({}) do |info, hash|
+				hash[ info[:keyword].to_sym ] = info[:val]
+			end
+		end
+	end
+
+	# Method 'ssl_attribute' was introduced in PostgreSQL 9.5.
+	if self.instance_methods.find{|m| m.to_sym == :ssl_attribute }
+		# call-seq:
+		#   conn.ssl_attributes -> Hash<String,String>
+		#
+		# Returns SSL-related information about the connection as key/value pairs
+		#
+		# The available attributes varies depending on the SSL library being used,
+		# and the type of connection.
+		#
+		# See also #ssl_attribute
+		def ssl_attributes
+			ssl_attribute_names.each.with_object({}) do |n,h|
+				h[n] = ssl_attribute(n)
+			end
+		end
+	end
+
+	REDIRECT_METHODS = {
+		:exec => [:async_exec, :sync_exec],
+		:query => [:async_exec, :sync_exec],
+		:exec_params => [:async_exec_params, :sync_exec_params],
+		:prepare => [:async_prepare, :sync_prepare],
+		:exec_prepared => [:async_exec_prepared, :sync_exec_prepared],
+		:describe_portal => [:async_describe_portal, :sync_describe_portal],
+		:describe_prepared => [:async_describe_prepared, :sync_describe_prepared],
+	}
+
+	def self.async_api=(enable)
+		REDIRECT_METHODS.each do |ali, (async, sync)|
+			remove_method(ali) if method_defined?(ali)
+			alias_method( ali, enable ? async : sync )
+		end
+	end
+
+	# pg-1.1.0+ defaults to libpq's async API for query related blocking methods
+	self.async_api = true
+end # class PG::Connection

data/lib/pg/constants.rb

@@ -1,4 +1,5 @@
-#!/usr/bin/env ruby
+# -*- ruby -*-
+# frozen_string_literal: true
 
 require 'pg' unless defined?( PG )
 

data/lib/pg/exceptions.rb

@@ -1,4 +1,5 @@
-#!/usr/bin/env ruby
+# -*- ruby -*-
+# frozen_string_literal: true
 
 require 'pg' unless defined?( PG )
 

data/lib/pg/result.rb

@@ -1,16 +1,43 @@
-#!/usr/bin/env ruby
+# -*- ruby -*-
+# frozen_string_literal: true
 
 require 'pg' unless defined?( PG )
 
 
 class PG::Result
 
-	### Returns all tuples as an array of arrays
-	def values
-		return enum_for(:each_row).to_a
+	# Apply a type map for all value retrieving methods.
+	#
+	# +type_map+: a PG::TypeMap instance.
+	#
+	# This method is equal to #type_map= , but returns self, so that calls can be chained.
+	#
+	# See also PG::BasicTypeMapForResults
+	def map_types!(type_map)
+		self.type_map = type_map
+		return self
+	end
+
+	# Set the data type for all field name returning methods.
+	#
+	# +type+: a Symbol defining the field name type.
+	#
+	# This method is equal to #field_name_type= , but returns self, so that calls can be chained.
+	def field_names_as(type)
+		self.field_name_type = type
+		return self
+	end
+
+	### Return a String representation of the object suitable for debugging.
+	def inspect
+		str = self.to_s
+		str[-1,0] = if cleared?
+			" cleared"
+		else
+			" status=#{res_status(result_status)} ntuples=#{ntuples} nfields=#{nfields} cmd_tuples=#{cmd_tuples}"
+		end
+		return str
 	end
 
 end # class PG::Result
 
-# Backward-compatible alias
-PGresult = PG::Result