pg 0.18.4 → 1.4.3

data/lib/pg/connection.rb

@@ -1,10 +1,13 @@
-#!/usr/bin/env ruby
+# -*- ruby -*-
+# frozen_string_literal: true
 
 require 'pg' unless defined?( PG )
 require 'uri'
+require 'io/wait'
+require 'socket'
 
 # 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
+# {libpq}[http://www.postgresql.org/docs/current/libpq.html], the C
 # application programmer's interface to PostgreSQL. Some familiarity with libpq
 # is recommended, but not necessary.
 #
@@ -18,76 +21,82 @@ require 'uri'
 #
 # See the PG::Result class for information on working with the results of a query.
 #
+# Many methods of this class have three variants kind of:
+# 1. #exec - the base method which is an alias to #async_exec .
+#    This is the method that should be used in general.
+# 2. #async_exec - the async aware version of the method, implemented by libpq's async API.
+# 3. #sync_exec - the method version that is implemented by blocking function(s) of libpq.
+#
+# Sync and async version of the method can be switched by Connection.async_api= , however it is not recommended to change the default.
 class PG::Connection
 
 	# The order the options are passed to the ::connect method.
 	CONNECT_ARGUMENT_ORDER = %w[host port options tty dbname user password]
 
 
-	### Quote the given +value+ for use in a connection-parameter string.
-	def self::quote_connstr( value )
+	### Quote a single +value+ for use in a connection-parameter string.
+	def self.quote_connstr( value )
 		return "'" + value.to_s.gsub( /[\\']/ ) {|m| '\\' + m } + "'"
 	end
 
+	# Convert Hash options to connection String
+	#
+	# Values are properly quoted and escaped.
+	def self.connect_hash_to_string( hash )
+		hash.map { |k,v| "#{k}=#{quote_connstr(v)}" }.join( ' ' )
+	end
 
-	### Parse the connection +args+ into a connection-parameter string. See PG::Connection.new
-	### for valid arguments.
-	def self::parse_connect_args( *args )
-		return '' if args.empty?
-
-		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 }
-			options[:fallback_application_name] = $0.sub( /^(.{30}).{4,}(.{30})$/ ){ $1+"..."+$2 }
-		end
+	# Parse the connection +args+ into a connection-parameter string.
+	# See PG::Connection.new for valid arguments.
+	#
+	# It accepts:
+	# * an option String kind of "host=name port=5432"
+	# * an option Hash kind of {host: "name", port: 5432}
+	# * URI string
+	# * URI object
+	# * positional arguments
+	#
+	# The method adds the option "fallback_application_name" if it isn't already set.
+	# It returns a connection string with "key=value" pairs.
+	def self.parse_connect_args( *args )
+		hash_arg = args.last.is_a?( Hash ) ? args.pop.transform_keys(&:to_sym) : {}
+		iopts = {}
 
 		if args.length == 1
 			case args.first
-			when URI, URI.regexp
-				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
+			when URI, /=/, /:\/\//
+				# Option or URL string style
+				conn_string = args.first.to_s
+				iopts = PG::Connection.conninfo_parse(conn_string).each_with_object({}){|h, o| o[h[:keyword].to_sym] = h[:val] if h[:val] }
 			else
-				# Positional parameters
-				options[CONNECT_ARGUMENT_ORDER.first.to_sym] = args.first
+				# Positional parameters (only host given)
+				iopts[CONNECT_ARGUMENT_ORDER.first.to_sym] = args.first
 			end
 		else
+			# Positional parameters with host and more
 			max = CONNECT_ARGUMENT_ORDER.length
 			raise ArgumentError,
-				"Extra positional parameter %d: %p" % [ max + 1, args[max] ] if args.length > max
+					"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
+				iopts[ k.to_sym ] = v if v
 			end
+			iopts.delete(:tty) # ignore obsolete tty parameter
 		end
 
-		options.merge!( hash_arg )
+		iopts.merge!( hash_arg )
 
-		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
-			option_string += ' ' unless option_string.empty? && options.empty?
-			return option_string + options.map { |k,v| "#{k}=#{quote_connstr(v)}" }.join( ' ' )
+		if !iopts[:fallback_application_name]
+			iopts[:fallback_application_name] = $0.sub( /^(.{30}).{4,}(.{30})$/ ){ $1+"..."+$2 }
 		end
-	end
 
+		return connect_hash_to_string(iopts)
+	end
 
 	#  call-seq:
-	#     conn.copy_data( sql ) {|sql_result| ... } -> PG::Result
+	#     conn.copy_data( sql [, coder] ) {|sql_result| ... } -> PG::Result
 	#
-	# Execute a copy process for transfering data to or from the server.
+	# Execute a copy process for transferring 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
@@ -109,13 +118,26 @@ class PG::Connection
 	# 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,e text)"
+	#   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,csv,data,to,copy\n"
-	#     conn.put_copy_data "more,csv,data,to,copy\n"
+	#     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
-	# This creates +my_table+ and inserts two rows.
 	#
 	# Example with CSV output format:
 	#   conn.copy_data "COPY my_table TO STDOUT CSV" do
@@ -124,9 +146,23 @@ class PG::Connection
 	#     end
 	#   end
 	# This prints all rows of +my_table+ to stdout:
-	#   "some,csv,data,to,copy\n"
-	#   "more,csv,data,to,copy\n"
+	#   "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"]
+
 	def copy_data( sql, coder=nil )
+		raise PG::NotInBlockingMode.new("copy_data can not be used in nonblocking mode", connection: self) if nonblocking?
 		res = exec( sql )
 
 		case res.result_status
@@ -158,19 +194,23 @@ class PG::Connection
 				yield res
 			rescue Exception => err
 				cancel
-				while get_copy_data
+				begin
+					while get_copy_data
+					end
+				rescue PG::Error
+					# Ignore error in cleanup to avoid losing original exception
 				end
 				while get_result
 				end
-				raise
+				raise err
 			else
 				res = get_last_result
-				if res.result_status != PGRES_COMMAND_OK
+				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"
+					raise PG::NotAllCopyDataRetrieved.new("Not all COPY data retrieved", connection: self)
 				end
 				res
 			ensure
@@ -187,6 +227,26 @@ class PG::Connection
 		define_method( :isthreadsafe, &PG.method(:isthreadsafe) )
 	end
 
+	#
+	# call-seq:
+	#    conn.transaction { |conn| ... } -> result of the block
+	#
+	# Executes a +BEGIN+ at the start of the block,
+	# and a +COMMIT+ at the end of the block, or
+	# +ROLLBACK+ if any exception occurs.
+	def transaction
+		rollback = false
+		exec "BEGIN"
+		yield(self)
+	rescue Exception
+		rollback = true
+		cancel if transaction_status == PG::PQTRANS_ACTIVE
+		block
+		exec "ROLLBACK"
+		raise
+	ensure
+		exec "COMMIT" unless rollback
+	end
 
 	### Returns an array of Hashes with connection defaults. See ::conndefaults
 	### for details.
@@ -210,22 +270,620 @@ class PG::Connection
 		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
 
-		### 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]
+	# 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
 
-end # class PG::Connection
+	# call-seq:
+	#    conn.get_result() -> PG::Result
+	#    conn.get_result() {|pg_result| block }
+	#
+	# Blocks waiting for the next result from a call to
+	# #send_query (or another asynchronous command), and returns
+	# it. Returns +nil+ if no more results are available.
+	#
+	# Note: call this function repeatedly until it returns +nil+, or else
+	# you will not be able to issue further commands.
+	#
+	# If the optional code block is given, it will be passed <i>result</i> as an argument,
+	# and the PG::Result object will  automatically be cleared when the block terminates.
+	# In this instance, <code>conn.exec</code> returns the value of the block.
+	def get_result
+		block
+		sync_get_result
+	end
+	alias async_get_result get_result
 
-# Backward-compatible alias
-PGconn = PG::Connection
+	# call-seq:
+	#    conn.get_copy_data( [ nonblock = false [, decoder = nil ]] ) -> Object
+	#
+	# Return one row of data, +nil+
+	# if the copy is done, or +false+ if the call would
+	# block (only possible if _nonblock_ is true).
+	#
+	# If _decoder_ is not set or +nil+, data is returned as binary string.
+	#
+	# If _decoder_ is set to a PG::Coder derivation, the return type depends on this decoder.
+	# PG::TextDecoder::CopyRow decodes the received data fields from one row of PostgreSQL's
+	# COPY text format to an Array of Strings.
+	# Optionally the decoder can type cast the single fields to various Ruby types in one step,
+	# if PG::TextDecoder::CopyRow#type_map is set accordingly.
+	#
+	# See also #copy_data.
+	#
+	def get_copy_data(async=false, decoder=nil)
+		if async
+			return sync_get_copy_data(async, decoder)
+		else
+			while (res=sync_get_copy_data(true, decoder)) == false
+				socket_io.wait_readable
+				consume_input
+			end
+			return res
+		end
+	end
+	alias async_get_copy_data get_copy_data
+
+
+	# In async_api=true mode (default) all send calls run nonblocking.
+	# The difference is that setnonblocking(true) disables automatic handling of would-block cases.
+	# In async_api=false mode all send calls run directly on libpq.
+	# Blocking vs. nonblocking state can be changed in libpq.
+
+	# call-seq:
+	#    conn.setnonblocking(Boolean) -> nil
+	#
+	# Sets the nonblocking status of the connection.
+	# In the blocking state, calls to #send_query
+	# will block until the message is sent to the server,
+	# but will not wait for the query results.
+	# In the nonblocking state, calls to #send_query
+	# will return an error if the socket is not ready for
+	# writing.
+	# Note: This function does not affect #exec, because
+	# that function doesn't return until the server has
+	# processed the query and returned the results.
+	#
+	# Returns +nil+.
+	def setnonblocking(enabled)
+		singleton_class.async_send_api = !enabled
+		self.flush_data = !enabled
+		sync_setnonblocking(true)
+	end
+	alias async_setnonblocking setnonblocking
+
+	# sync/async isnonblocking methods are switched by async_setnonblocking()
+
+	# call-seq:
+	#    conn.isnonblocking() -> Boolean
+	#
+	# Returns the blocking status of the database connection.
+	# Returns +true+ if the connection is set to nonblocking mode and +false+ if blocking.
+	def isnonblocking
+		false
+	end
+	alias async_isnonblocking isnonblocking
+	alias nonblocking? isnonblocking
 
+	# call-seq:
+	#    conn.put_copy_data( buffer [, encoder] ) -> Boolean
+	#
+	# Transmits _buffer_ as copy data to the server.
+	# Returns true if the data was sent, false if it was
+	# not sent (false is only possible if the connection
+	# is in nonblocking mode, and this command would block).
+	#
+	# _encoder_ can be a PG::Coder derivation (typically PG::TextEncoder::CopyRow).
+	# This encodes the data fields given as _buffer_ from an Array of Strings to
+	# PostgreSQL's COPY text format inclusive proper escaping. Optionally
+	# the encoder can type cast the fields from various Ruby types in one step,
+	# if PG::TextEncoder::CopyRow#type_map is set accordingly.
+	#
+	# Raises an exception if an error occurs.
+	#
+	# See also #copy_data.
+	#
+	def put_copy_data(buffer, encoder=nil)
+		# sync_put_copy_data does a non-blocking attept to flush data.
+		until res=sync_put_copy_data(buffer, encoder)
+			# It didn't flush immediately and allocation of more buffering memory failed.
+			# Wait for all data sent by doing a blocking flush.
+			res = flush
+		end
+
+		# And do a blocking flush every 100 calls.
+		# This is to avoid memory bloat, when sending the data is slower than calls to put_copy_data happen.
+		if (@calls_to_put_copy_data += 1) > 100
+			@calls_to_put_copy_data = 0
+			res = flush
+		end
+		res
+	end
+	alias async_put_copy_data put_copy_data
+
+	# call-seq:
+	#    conn.put_copy_end( [ error_message ] ) -> Boolean
+	#
+	# Sends end-of-data indication to the server.
+	#
+	# _error_message_ is an optional parameter, and if set,
+	# forces the COPY command to fail with the string
+	# _error_message_.
+	#
+	# Returns true if the end-of-data was sent, #false* if it was
+	# not sent (*false* is only possible if the connection
+	# is in nonblocking mode, and this command would block).
+	def put_copy_end(*args)
+		until sync_put_copy_end(*args)
+			flush
+		end
+		@calls_to_put_copy_data = 0
+		flush
+	end
+	alias async_put_copy_end put_copy_end
+
+	if method_defined? :sync_encrypt_password
+		# call-seq:
+		#    conn.encrypt_password( password, username, algorithm=nil ) -> String
+		#
+		# This function is intended to be used by client applications that wish to send commands like <tt>ALTER USER joe PASSWORD 'pwd'</tt>.
+		# It is good practice not to send the original cleartext password in such a command, because it might be exposed in command logs, activity displays, and so on.
+		# Instead, use this function to convert the password to encrypted form before it is sent.
+		#
+		# The +password+ and +username+ arguments are the cleartext password, and the SQL name of the user it is for.
+		# +algorithm+ specifies the encryption algorithm to use to encrypt the password.
+		# Currently supported algorithms are +md5+ and +scram-sha-256+ (+on+ and +off+ are also accepted as aliases for +md5+, for compatibility with older server versions).
+		# Note that support for +scram-sha-256+ was introduced in PostgreSQL version 10, and will not work correctly with older server versions.
+		# If algorithm is omitted or +nil+, this function will query the server for the current value of the +password_encryption+ setting.
+		# That can block, and will fail if the current transaction is aborted, or if the connection is busy executing another query.
+		# If you wish to use the default algorithm for the server but want to avoid blocking, query +password_encryption+ yourself before calling #encrypt_password, and pass that value as the algorithm.
+		#
+		# Return value is the encrypted password.
+		# The caller can assume the string doesn't contain any special characters that would require escaping.
+		#
+		# Available since PostgreSQL-10.
+		# See also corresponding {libpq function}[https://www.postgresql.org/docs/current/libpq-misc.html#LIBPQ-PQENCRYPTPASSWORDCONN].
+		def encrypt_password( password, username, algorithm=nil )
+			algorithm ||= exec("SHOW password_encryption").getvalue(0,0)
+			sync_encrypt_password(password, username, algorithm)
+		end
+		alias async_encrypt_password encrypt_password
+	end
+
+	# call-seq:
+	#   conn.reset()
+	#
+	# Resets the backend connection. This method closes the
+	# backend connection and tries to re-connect.
+	def reset
+		reset_start
+		async_connect_or_reset(:reset_poll)
+		self
+	end
+	alias async_reset reset
+
+	# call-seq:
+	#    conn.cancel() -> String
+	#
+	# Requests cancellation of the command currently being
+	# processed.
+	#
+	# Returns +nil+ on success, or a string containing the
+	# error message if a failure occurs.
+	def cancel
+		be_pid = backend_pid
+		be_key = backend_key
+		cancel_request = [0x10, 1234, 5678, be_pid, be_key].pack("NnnNN")
+
+		if Fiber.respond_to?(:scheduler) && Fiber.scheduler && RUBY_PLATFORM =~ /mingw|mswin/
+			# Ruby's nonblocking IO is not really supported on Windows.
+			# We work around by using threads and explicit calls to wait_readable/wait_writable.
+			cl = Thread.new(socket_io.remote_address) { |ra| ra.connect }.value
+			begin
+				cl.write_nonblock(cancel_request)
+			rescue IO::WaitReadable, Errno::EINTR
+				cl.wait_writable
+				retry
+			end
+			begin
+				cl.read_nonblock(1)
+			rescue IO::WaitReadable, Errno::EINTR
+				cl.wait_readable
+				retry
+			rescue EOFError
+			end
+		elsif RUBY_ENGINE == 'truffleruby'
+			begin
+				cl = socket_io.remote_address.connect
+			rescue NotImplementedError
+				# Workaround for truffleruby < 21.3.0
+				cl2 = Socket.for_fd(socket_io.fileno)
+				cl2.autoclose = false
+				adr = cl2.remote_address
+				if adr.ip?
+					cl = TCPSocket.new(adr.ip_address, adr.ip_port)
+					cl.autoclose = false
+				else
+					cl = UNIXSocket.new(adr.unix_path)
+					cl.autoclose = false
+				end
+			end
+			cl.write(cancel_request)
+			cl.read(1)
+		else
+			cl = socket_io.remote_address.connect
+			# Send CANCEL_REQUEST_CODE and parameters
+			cl.write(cancel_request)
+			# Wait for the postmaster to close the connection, which indicates that it's processed the request.
+			cl.read(1)
+		end
+
+		cl.close
+		nil
+	rescue SystemCallError => err
+		err.to_s
+	end
+	alias async_cancel cancel
+
+	private def async_connect_or_reset(poll_meth)
+		# Track the progress of the connection, waiting for the socket to become readable/writable before polling it
+
+		if (timeo = conninfo_hash[:connect_timeout].to_i) && timeo > 0
+			# Lowest timeout is 2 seconds - like in libpq
+			timeo = [timeo, 2].max
+			stop_time = timeo + Process.clock_gettime(Process::CLOCK_MONOTONIC)
+		end
+
+		poll_status = PG::PGRES_POLLING_WRITING
+		until poll_status == PG::PGRES_POLLING_OK ||
+				poll_status == PG::PGRES_POLLING_FAILED
+
+			timeout = stop_time&.-(Process.clock_gettime(Process::CLOCK_MONOTONIC))
+			event = if !timeout || timeout >= 0
+				# If the socket needs to read, wait 'til it becomes readable to poll again
+				case poll_status
+				when PG::PGRES_POLLING_READING
+					if defined?(IO::READABLE) # ruby-3.0+
+						socket_io.wait(IO::READABLE | IO::PRIORITY, timeout)
+					else
+						IO.select([socket_io], nil, [socket_io], timeout)
+					end
+
+				# ...and the same for when the socket needs to write
+				when PG::PGRES_POLLING_WRITING
+					if defined?(IO::WRITABLE) # ruby-3.0+
+						# Use wait instead of wait_readable, since connection errors are delivered as
+						# exceptional/priority events on Windows.
+						socket_io.wait(IO::WRITABLE | IO::PRIORITY, timeout)
+					else
+						# io#wait on ruby-2.x doesn't wait for priority, so fallback to IO.select
+						IO.select(nil, [socket_io], [socket_io], timeout)
+					end
+				end
+			end
+			# connection to server at "localhost" (127.0.0.1), port 5433 failed: timeout expired (PG::ConnectionBad)
+			# connection to server on socket "/var/run/postgresql/.s.PGSQL.5433" failed: No such file or directory
+			unless event
+				if self.class.send(:host_is_named_pipe?, host)
+					connhost = "on socket \"#{host}\""
+				elsif respond_to?(:hostaddr)
+					connhost = "at \"#{host}\" (#{hostaddr}), port #{port}"
+				else
+					connhost = "at \"#{host}\", port #{port}"
+				end
+				raise PG::ConnectionBad.new("connection to server #{connhost} failed: timeout expired", connection: self)
+			end
+
+			# Check to see if it's finished or failed yet
+			poll_status = send( poll_meth )
+			@last_status = status unless [PG::CONNECTION_BAD, PG::CONNECTION_OK].include?(status)
+		end
+
+		unless status == PG::CONNECTION_OK
+			msg = error_message
+			finish
+			raise PG::ConnectionBad.new(msg, connection: self)
+		end
+
+		# Set connection to nonblocking to handle all blocking states in ruby.
+		# That way a fiber scheduler is able to handle IO requests.
+		sync_setnonblocking(true)
+		self.flush_data = true
+		set_default_encoding
+	end
+
+	class << self
+		# call-seq:
+		#    PG::Connection.new -> conn
+		#    PG::Connection.new(connection_hash) -> conn
+		#    PG::Connection.new(connection_string) -> conn
+		#    PG::Connection.new(host, port, options, tty, dbname, user, password) ->  conn
+		#
+		# Create a connection to the specified server.
+		#
+		# +connection_hash+ must be a ruby Hash with connection parameters.
+		# See the {list of valid parameters}[https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS] in the PostgreSQL documentation.
+		#
+		# There are two accepted formats for +connection_string+: plain <code>keyword = value</code> strings and URIs.
+		# See the documentation of {connection strings}[https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING].
+		#
+		# The positional parameter form has the same functionality except that the missing parameters will always take on default values. The parameters are:
+		# [+host+]
+		#   server hostname
+		# [+port+]
+		#   server port number
+		# [+options+]
+		#   backend options
+		# [+tty+]
+		#   (ignored in all versions of PostgreSQL)
+		# [+dbname+]
+		#   connecting database name
+		# [+user+]
+		#   login user name
+		# [+password+]
+		#   login password
+		#
+		# Examples:
+		#
+		#   # Connect using all defaults
+		#   PG::Connection.new
+		#
+		#   # As a Hash
+		#   PG::Connection.new( dbname: 'test', port: 5432 )
+		#
+		#   # As a String
+		#   PG::Connection.new( "dbname=test port=5432" )
+		#
+		#   # As an Array
+		#   PG::Connection.new( nil, 5432, nil, nil, 'test', nil, nil )
+		#
+		#   # As an URI
+		#   PG::Connection.new( "postgresql://user:pass@pgsql.example.com:5432/testdb?sslmode=require" )
+		#
+		# If the Ruby default internal encoding is set (i.e., <code>Encoding.default_internal != nil</code>), the
+		# connection will have its +client_encoding+ set accordingly.
+		#
+		# Raises a PG::Error if the connection fails.
+		def new(*args)
+			conn = connect_to_hosts(*args)
+
+			if block_given?
+				begin
+					return yield conn
+				ensure
+					conn.finish
+				end
+			end
+			conn
+		end
+		alias async_connect new
+		alias connect new
+		alias open new
+		alias setdb new
+		alias setdblogin new
+
+		private def connect_to_hosts(*args)
+			option_string = parse_connect_args(*args)
+			iopts = PG::Connection.conninfo_parse(option_string).each_with_object({}){|h, o| o[h[:keyword].to_sym] = h[:val] if h[:val] }
+			iopts = PG::Connection.conndefaults.each_with_object({}){|h, o| o[h[:keyword].to_sym] = h[:val] if h[:val] }.merge(iopts)
+
+			errors = []
+			if iopts[:hostaddr]
+				# hostaddr is provided -> no need to resolve hostnames
+				ihostaddrs = iopts[:hostaddr].split(",", -1)
+
+				ihosts = iopts[:host].split(",", -1) if iopts[:host]
+				raise PG::ConnectionBad, "could not match #{ihosts.size} host names to #{ihostaddrs.size} hostaddr values" if ihosts && ihosts.size != ihostaddrs.size
+
+				iports = iopts[:port].split(",", -1)
+				iports = iports * ihostaddrs.size if iports.size == 1
+				raise PG::ConnectionBad, "could not match #{iports.size} port numbers to #{ihostaddrs.size} hosts" if iports.size != ihostaddrs.size
+
+				# Try to connect to each hostaddr with separate timeout
+				ihostaddrs.each_with_index do |ihostaddr, idx|
+					oopts = iopts.merge(hostaddr: ihostaddr, port: iports[idx])
+					oopts[:host] = ihosts[idx] if ihosts
+					c = connect_internal(oopts, errors)
+					return c if c
+				end
+			elsif iopts[:host] && !iopts[:host].empty?
+				# Resolve DNS in Ruby to avoid blocking state while connecting, when it ...
+				ihosts = iopts[:host].split(",", -1)
+
+				iports = iopts[:port].split(",", -1)
+				iports = iports * ihosts.size if iports.size == 1
+				raise PG::ConnectionBad, "could not match #{iports.size} port numbers to #{ihosts.size} hosts" if iports.size != ihosts.size
+
+				ihosts.each_with_index do |mhost, idx|
+					unless host_is_named_pipe?(mhost)
+						addrs = if Fiber.respond_to?(:scheduler) &&
+									Fiber.scheduler &&
+									RUBY_VERSION < '3.1.'
+
+							# Use a second thread to avoid blocking of the scheduler.
+							# `TCPSocket.gethostbyname` isn't fiber aware before ruby-3.1.
+							Thread.new{ Addrinfo.getaddrinfo(mhost, nil, nil, :STREAM).map(&:ip_address) rescue [''] }.value
+						else
+							Addrinfo.getaddrinfo(mhost, nil, nil, :STREAM).map(&:ip_address) rescue ['']
+						end
+
+						# Try to connect to each host with separate timeout
+						addrs.each do |addr|
+							oopts = iopts.merge(hostaddr: addr, host: mhost, port: iports[idx])
+							c = connect_internal(oopts, errors)
+							return c if c
+						end
+					else
+						# No hostname to resolve (UnixSocket)
+						oopts = iopts.merge(host: mhost, port: iports[idx])
+						c = connect_internal(oopts, errors)
+						return c if c
+					end
+				end
+			else
+				# No host given
+				return connect_internal(iopts)
+			end
+			raise PG::ConnectionBad, errors.join("\n")
+		end
+
+		private def connect_internal(opts, errors=nil)
+			begin
+				conn = self.connect_start(opts) or
+											raise(PG::Error, "Unable to create a new connection")
+
+				raise PG::ConnectionBad.new(conn.error_message, connection: self) if conn.status == PG::CONNECTION_BAD
+
+				conn.send(:async_connect_or_reset, :connect_poll)
+			rescue PG::ConnectionBad => err
+				if errors && !(conn && [PG::CONNECTION_AWAITING_RESPONSE].include?(conn.instance_variable_get(:@last_status)))
+					# Seems to be no authentication error -> try next host
+					errors << err
+					return nil
+				else
+					# Probably an authentication error
+					raise
+				end
+			end
+			conn
+		end
+
+		private def host_is_named_pipe?(host_string)
+			host_string.empty? || host_string.start_with?("/") ||  # it's UnixSocket?
+							host_string.start_with?("@") ||  # it's UnixSocket in the abstract namespace?
+							# it's a path on Windows?
+							(RUBY_PLATFORM =~ /mingw|mswin/ && host_string =~ /\A([\/\\]|\w:[\/\\])/)
+		end
+
+		# call-seq:
+		#    PG::Connection.ping(connection_hash)       -> Integer
+		#    PG::Connection.ping(connection_string)     -> Integer
+		#    PG::Connection.ping(host, port, options, tty, dbname, login, password) ->  Integer
+		#
+		# Check server status.
+		#
+		# See PG::Connection.new for a description of the parameters.
+		#
+		# Returns one of:
+		# [+PQPING_OK+]
+		#   server is accepting connections
+		# [+PQPING_REJECT+]
+		#   server is alive but rejecting connections
+		# [+PQPING_NO_RESPONSE+]
+		#   could not establish connection
+		# [+PQPING_NO_ATTEMPT+]
+		#   connection not attempted (bad params)
+		def ping(*args)
+			if Fiber.respond_to?(:scheduler) && Fiber.scheduler
+				# Run PQping in a second thread to avoid blocking of the scheduler.
+				# Unfortunately there's no nonblocking way to run ping.
+				Thread.new { sync_ping(*args) }.value
+			else
+				sync_ping(*args)
+			end
+		end
+		alias async_ping ping
+
+		REDIRECT_CLASS_METHODS = {
+			:new => [:async_connect, :sync_connect],
+			:connect => [:async_connect, :sync_connect],
+			:open => [:async_connect, :sync_connect],
+			:setdb => [:async_connect, :sync_connect],
+			:setdblogin => [:async_connect, :sync_connect],
+			:ping => [:async_ping, :sync_ping],
+		}
+
+		# These methods are affected by PQsetnonblocking
+		REDIRECT_SEND_METHODS = {
+			:isnonblocking => [:async_isnonblocking, :sync_isnonblocking],
+			:nonblocking? => [:async_isnonblocking, :sync_isnonblocking],
+			:put_copy_data => [:async_put_copy_data, :sync_put_copy_data],
+			:put_copy_end => [:async_put_copy_end, :sync_put_copy_end],
+			:flush => [:async_flush, :sync_flush],
+		}
+		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],
+			:setnonblocking => [:async_setnonblocking, :sync_setnonblocking],
+			:get_result => [:async_get_result, :sync_get_result],
+			:get_last_result => [:async_get_last_result, :sync_get_last_result],
+			:get_copy_data => [:async_get_copy_data, :sync_get_copy_data],
+			:reset => [:async_reset, :sync_reset],
+			:set_client_encoding => [:async_set_client_encoding, :sync_set_client_encoding],
+			:client_encoding= => [:async_set_client_encoding, :sync_set_client_encoding],
+			:cancel => [:async_cancel, :sync_cancel],
+		}
+
+		if PG::Connection.instance_methods.include? :async_encrypt_password
+			REDIRECT_METHODS.merge!({
+				:encrypt_password => [:async_encrypt_password, :sync_encrypt_password],
+			})
+		end
+
+		def async_send_api=(enable)
+			REDIRECT_SEND_METHODS.each do |ali, (async, sync)|
+				undef_method(ali) if method_defined?(ali)
+				alias_method( ali, enable ? async : sync )
+			end
+		end
+
+		# Switch between sync and async libpq API.
+		#
+		#   PG::Connection.async_api = true
+		# this is the default.
+		# It sets an alias from #exec to #async_exec, #reset to #async_reset and so on.
+		#
+		#   PG::Connection.async_api = false
+		# sets an alias from #exec to #sync_exec, #reset to #sync_reset and so on.
+		#
+		# pg-1.1.0+ defaults to libpq's async API for query related blocking methods.
+		# pg-1.3.0+ defaults to libpq's async API for all possibly blocking methods.
+		#
+		# _PLEASE_ _NOTE_: This method is not part of the public API and is for debug and development use only.
+		# Do not use this method in production code.
+		# Any issues with the default setting of <tt>async_api=true</tt> should be reported to the maintainers instead.
+		#
+		def async_api=(enable)
+			self.async_send_api = enable
+			REDIRECT_METHODS.each do |ali, (async, sync)|
+				remove_method(ali) if method_defined?(ali)
+				alias_method( ali, enable ? async : sync )
+			end
+			REDIRECT_CLASS_METHODS.each do |ali, (async, sync)|
+				singleton_class.remove_method(ali) if method_defined?(ali)
+				singleton_class.alias_method(ali, enable ? async : sync )
+			end
+		end
+	end
+
+	self.async_api = true
+end # class PG::Connection