pg 1.5.9 → 1.7.0

data/lib/pg/connection.rb

@@ -2,7 +2,6 @@
 # frozen_string_literal: true
 
 require 'pg' unless defined?( PG )
-require 'io/wait' unless ::IO.public_instance_methods(false).include?(:wait_readable) # for ruby < 3.0
 require 'socket'
 
 # The PostgreSQL connection class. The interface for this class is based on
@@ -13,7 +12,7 @@ require 'socket'
 # For example, to send query to the database on the localhost:
 #
 #    require 'pg'
-#    conn = PG::Connection.open(:dbname => 'test')
+#    conn = PG::Connection.open(dbname: 'test')
 #    res = conn.exec_params('SELECT $1 AS a, $2 AS b, $3 AS c', [1, 2, nil])
 #    # Equivalent to:
 #    #  res  = conn.exec('SELECT 1 AS a, 2 AS b, NULL AS c')
@@ -306,22 +305,19 @@ class PG::Connection
 	# and a +COMMIT+ at the end of the block, or
 	# +ROLLBACK+ if any exception occurs.
 	def transaction
-		rollback = false
 		exec "BEGIN"
 		yield(self)
-	rescue PG::RollbackTransaction
-		rollback = true
-		cancel if transaction_status == PG::PQTRANS_ACTIVE
-		block
-		exec "ROLLBACK"
-	rescue Exception
-		rollback = true
-		cancel if transaction_status == PG::PQTRANS_ACTIVE
-		block
-		exec "ROLLBACK"
+	rescue PG::RollbackTransaction => error
+	rescue Exception => error
 		raise
 	ensure
-		exec "COMMIT" unless rollback
+		if error || Thread.current.status == "aborting"
+			cancel if transaction_status == PG::PQTRANS_ACTIVE
+			block
+			exec("ROLLBACK")
+		else
+			exec("COMMIT")
+		end
 	end
 
 	### Returns an array of Hashes with connection defaults. See ::conndefaults
@@ -356,21 +352,18 @@ class PG::Connection
 		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
+	# 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
 
@@ -539,34 +532,50 @@ class PG::Connection
 	end
 	alias async_put_copy_end put_copy_end
 
-	if method_defined? :sync_encrypt_password
+	if method_defined? :send_pipeline_sync
 		# 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
+		#    conn.pipeline_sync
+		#
+		# Marks a synchronization point in a pipeline by sending a sync message and flushing the send buffer.
+		# This serves as the delimiter of an implicit transaction and an error recovery point.
+		#
+		# See enter_pipeline_mode
+		#
+		# Raises PG::Error if the connection is not in pipeline mode or sending a sync message failed.
+		#
+		# Available since PostgreSQL-14
+		def pipeline_sync(*args)
+			send_pipeline_sync(*args)
+			flush
+		end
+		alias async_pipeline_sync pipeline_sync
 	end
 
+	# 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.
+	#
+	# 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
+
 	# call-seq:
 	#   conn.reset()
 	#
@@ -576,7 +585,9 @@ class PG::Connection
 		# Use connection options from PG::Connection.new to reconnect with the same options but with renewed DNS resolution.
 		# Use conninfo_hash as a fallback when connect_start was used to create the connection object.
 		iopts = @iopts_for_reset || conninfo_hash.compact
-		if iopts[:host] && !iopts[:host].empty? && PG.library_version >= 100000
+		if	iopts[:host] && !iopts[:host].empty? &&
+				iopts[:port] && !iopts[:port].empty? &&
+				PG.library_version >= 100000
 			iopts = self.class.send(:resolve_hosts, iopts)
 		end
 		conninfo = self.class.parse_connect_args( iopts );
@@ -586,128 +597,283 @@ class PG::Connection
 	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
+	if defined?(PG::CancelConnection)
+		# PostgreSQL-17+
+
+		def sync_cancel
+			cancon = PG::CancelConnection.new(self)
+			cancon.sync_cancel
+		rescue PG::Error => err
+			err.to_s
+		end
+
+		# 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.
+		#
+		# On PostgreSQL-17+ client library the class PG::CancelConnection is used.
+		# On older client library a pure ruby implementation is used.
+		def cancel
+			cancon = PG::CancelConnection.new(self)
+			cancon.async_cancel
+		rescue PG::Error => err
+			err.to_s
+		end
+
+	else
+
+		# PostgreSQL < 17
+
+		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
+			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
-			begin
-				cl.read_nonblock(1)
-			rescue IO::WaitReadable, Errno::EINTR
-				cl.wait_readable
-				retry
-			rescue EOFError
+
+			cl.close
+			nil
+		rescue SystemCallError => err
+			err.to_s
+		end
+	end
+	alias async_cancel cancel
+
+	PLACEHOLDER_RE = /
+		'(?:''|[^'])*'                                             | # string literal
+		"(?:""|[^"])*"                                             | # quoted identifier
+		--[^\n]*                                                   | # line comment
+		\/\*.*?\*\/                                                | # block comment
+		\$\$.*?\$\$                                                | # dollar-quoted string. E.g. $$ $1 $$
+		\$(?<__dq_tag>[A-Za-z_][A-Za-z_0-9]*)\$.*?\$\k<__dq_tag>\$ | # named dollar-quoted string. E.g. $foo$ $1 $foo$
+		(?<placeholder>\$(?:[1-9]\d*))                               # placeholder we are interested in
+	/mx
+	private_constant :PLACEHOLDER_RE
+	SAFE_TYPE_NAME_PART_RE = /\A[A-Za-z_][A-Za-z0-9_$]*\z/
+	private_constant :SAFE_TYPE_NAME_PART_RE
+
+	private def quote_type_name(name)
+		name = name.to_s.dup
+		array_suffix = name.slice!(/(?:\[\])+\z/) || ""
+		name = name.split(".", -1).map do |part|
+			SAFE_TYPE_NAME_PART_RE.match?(part) ? part : quote_ident(part)
+		end.join(".")
+		name + array_suffix
+	end
+
+	# Compiles your prepared SQL statement and the given positional arguments into plain SQL string.
+	#
+	# The resulting SQL string can be used with +conn.exec+ like the prepared SQL statement and parameters with +conn.exec_params+.
+	# +conn.exec_params+ is usually preferred because it's faster and safer.
+	# +embed_params+ is intended for debugging messages with positional parameters.
+	# It avoids manual insertion for later inspection in +psql+ or so.
+	#
+	# When using PG::Connection#exec_params, it's possible to set the numeric database type OID of a parameter by either a hash with +:type+ key, or by PG::Coder#oid .
+	# +embed_params+ casts the parameter the same way, but needs the name of the type instead its OID.
+	# That name must be provided by either a +:typename+ key in addition to the +:type+ OID or by PG::Coder#name in addition to PG::Coder#oid.
+	#
+	# Only text parameter format can be embedded into SQL text.
+	# Binary data ( <tt>:format => 1</tt> or PG::Coder#format == 1 ) raises an ArgumentError.
+	# However the common pattern of sending BYTEA (OID 17) data as format 1, which avoids escapting large blobs, is recognized and probably escaped into the SQL result string.
+	#
+	# Example:
+	# 	conn.embed_params('SELECT $1 AS a, $2 AS b, $3 AS c', [1, 2, {value: "\0", type: 17, format: 1}])
+	# 	=> "SELECT '1' AS a, '2' AS b, '\\x00'::bytea AS c"
+	def embed_params(sql, params, type_map: type_map_for_queries)
+		return sql if params.empty?
+
+		oid_to_typecast = proc do |oid, tname, errtext|
+			if oid && oid > 0
+				if tname.to_s.empty?
+					raise(ArgumentError, "Database type name of OID #{oid.inspect} missing#{errtext}")
+				else
+					"::#{quote_type_name(tname)}"
+				end
 			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
+		end
+
+		encoders = type_map.query_param_encoders(params)
+		params = encoders.map.with_index do |enc, i|
+			value = params[i]
+			case value
+			when NilClass
+				'NULL'
+			when PG::BasicTypeMapForQueries::BinaryData
+				"'#{ escape_bytea(value) }'"
+			else
+				if enc
+					raise ArgumentError, "binary encoded parameter from #{enc.inspect} cannot be inserted into SQL text" if enc.format != 0
+					"'#{escape(enc.encode(value))}'#{oid_to_typecast[enc.oid, enc.name, " - please set name of encoder #{enc.inspect}"]}"
+				elsif Hash === value
+					typename = value[:format] == 1 && value[:type] == 17 ?
+						"::bytea" : oid_to_typecast[value[:type], value[:typename], " - please set parameter key :typename"]
+
+					case value[:value]
+					when NilClass
+						"NULL#{typename}"
+					else
+						if value[:format] == 1
+							raise ArgumentError, "binary encoded parameter with OID #{value[:type].inspect} cannot be inserted into SQL text" if value[:type] && value[:type] != 17
+							"'#{escape_bytea(value[:value].to_s)}'#{typename}"
+						else
+							"'#{escape(value[:value].to_s)}'#{typename}"
+						end
+					end
 				else
-					cl = UNIXSocket.new(adr.unix_path)
-					cl.autoclose = false
+					"'#{escape(value.to_s)}'"
 				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
+		sql.gsub(PLACEHOLDER_RE).each do |matched|
+			placeholder = Regexp.last_match[:placeholder]
+			# Do not replace non-positional args string and pass it as is
+			next matched unless placeholder
+
+			params[placeholder[1..].to_i - 1]
+		end
 	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
+	module Pollable
+		# Track the progress of the connection, waiting for the socket to become readable/writable before polling it.
+		#
+		# Connecting to multiple hosts is done like so:
+		# - All hosts are passed to PG::Connection.connect_start
+		# - As soon as the host is tried to connect the related host is removed from the hosts list
+		# - When the polling status changes to `PG::PGRES_POLLING_OK` the connection is returned and ready to use.
+		# - When the polling status changes to `PG::PGRES_POLLING_FAILED` connecting is aborted and a PG::ConnectionBad is raised with details to all connection attempts.
+		# - When a timeout occurs, connecting is restarted with the remaining hosts.
+		#
+		# The downside is that this connects only once to hosts which are listed twice when they timeout.
+		private def polling_loop(poll_meth)
+			connect_timeout = conninfo_hash[:connect_timeout]
+			if (timeo = connect_timeout.to_i) && timeo > 0
+				host_count = (conninfo_hash[:hostaddr].to_s.empty? ? conninfo_hash[:host] : conninfo_hash[:hostaddr]).to_s.count(",") + 1
+				stop_time = timeo * host_count + Process.clock_gettime(Process::CLOCK_MONOTONIC)
+			end
+			iopts = conninfo_hash.compact
+			connection_errors = []
+			poll_status = PG::PGRES_POLLING_WRITING
 
-		if (timeo = conninfo_hash[:connect_timeout].to_i) && timeo > 0
-			host_count = conninfo_hash[:host].to_s.count(",") + 1
-			stop_time = timeo * host_count + Process.clock_gettime(Process::CLOCK_MONOTONIC)
-		end
+			until poll_status == PG::PGRES_POLLING_OK ||
+					poll_status == PG::PGRES_POLLING_FAILED
+
+				# Set single timeout to parameter "connect_timeout" but
+				# don't exceed total connection time of number-of-hosts * connect_timeout.
+				timeout = [timeo, stop_time - Process.clock_gettime(Process::CLOCK_MONOTONIC)].min if stop_time
 
-		poll_status = PG::PGRES_POLLING_WRITING
-		until poll_status == PG::PGRES_POLLING_OK ||
-				poll_status == PG::PGRES_POLLING_FAILED
+				hostcnt = remove_current_host(iopts)
 
-			# Set single timeout to parameter "connect_timeout" but
-			# don't exceed total connection time of number-of-hosts * connect_timeout.
-			timeout = [timeo, stop_time - Process.clock_gettime(Process::CLOCK_MONOTONIC)].min if stop_time
-			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+
+				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
 						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+
+					# ...and the same for when the socket needs to write
+					when PG::PGRES_POLLING_WRITING
 						# 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}"
+
+				# 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
+					connection_errors << (error_message + "timeout expired")
+					if hostcnt > 0
+						reset_start2(self.class.parse_connect_args(iopts))
+						# Restart polling with waiting for writable.
+						# Otherwise "not connected" error is raised on Windows.
+						poll_status = PG::PGRES_POLLING_WRITING
+						next
+					else
+						finish
+						raise PG::ConnectionBad.new(connection_errors.join("\n").b, connection: self)
+					end
 				end
-				raise PG::ConnectionBad.new("connection to server #{connhost} failed: timeout expired", connection: self)
+
+				# Check to see if it's finished or failed yet
+				poll_status = send( poll_meth )
 			end
 
-			# Check to see if it's finished or failed yet
-			poll_status = send( poll_meth )
+			unless status == PG::CONNECTION_OK
+				msg = error_message
+				finish
+				raise PG::ConnectionBad.new(connection_errors.map{|e| e + "\n" }.join.b + msg, connection: self)
+			end
 		end
 
-		unless status == PG::CONNECTION_OK
-			msg = error_message
-			finish
-			raise PG::ConnectionBad.new(msg, connection: self)
+		# Remove the host to which the connection is currently established from the option hash.
+		# Affected options are:
+		# - :host
+		# - :hostaddr
+		# - :port
+		#
+		# Return the number of remaining hosts.
+		private def remove_current_host(iopts)
+			ihosts = iopts[:host]&.split(",", -1)
+			ihostaddrs = iopts[:hostaddr]&.split(",", -1)
+			iports = iopts[:port]&.split(",", -1)
+			iports = iports * (ihosts || ihostaddrs || [1]).size if iports&.size == 1
+
+			idx = (ihosts || ihostaddrs || iports).index.with_index do |_, i|
+				(ihosts ? ihosts[i] == host : true) &&
+				(ihostaddrs && respond_to?(:hostaddr, true) ? ihostaddrs[i] == hostaddr : true) &&
+				(iports ? iports[i].to_i == port : true)
+			end
+
+			if idx
+				ihosts&.delete_at(idx)
+				ihostaddrs&.delete_at(idx)
+				iports&.delete_at(idx)
+
+				iopts.merge!(
+					host: ihosts.join(",")) if ihosts
+				iopts.merge!(
+					hostaddr: ihostaddrs.join(",")) if ihostaddrs
+				iopts.merge!(
+					port: iports.join(",")) if iports
+			end
+
+			(ihosts || ihostaddrs || iports).size
 		end
+	end
+
+	include Pollable
+
+	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
+		polling_loop(poll_meth)
 
 		# Set connection to nonblocking to handle all blocking states in ruby.
 		# That way a fiber scheduler is able to handle IO requests.
@@ -723,7 +889,7 @@ class PG::Connection
 		#    PG::Connection.new(connection_string) -> conn
 		#    PG::Connection.new(host, port, options, tty, dbname, user, password) ->  conn
 		#
-		# Create a connection to the specified server.
+		# === 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.
@@ -747,7 +913,13 @@ class PG::Connection
 		# [+password+]
 		#   login password
 		#
-		# Examples:
+		#
+		# 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.
+		#
+		# === Examples:
 		#
 		#   # Connect using all defaults
 		#   PG::Connection.new
@@ -764,10 +936,18 @@ class PG::Connection
 		#   # 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.
+		# === Specifying Multiple Hosts
+		#
+		# It is possible to specify multiple hosts to connect to, so that they are tried in the given order or optionally in random order.
+		# In the Keyword/Value format, the host, hostaddr, and port options accept comma-separated lists of values.
+		# The {details to libpq}[https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-MULTIPLE-HOSTS] describe how it works, but there are two small differences how ruby-pg handles multiple hosts:
+		# - All hosts are resolved before the first connection is tried.
+		#   This means that when +load_balance_hosts+ is set to +random+, then all resolved addresses are tried randomly in one level.
+		#   When a host resolves to more than one address, it is therefore tried more often than a host that has only one address.
+		# - When a timeout occurs due to the value of +connect_timeout+, then the given +host+, +hostaddr+ and +port+ combination is not tried a second time, even if it's specified several times.
+		#   It's still possible to do load balancing with +load_balance_hosts+ set to +random+ and to increase the number of connections a node gets, when the hostname is provided multiple times in the host string.
+		#   This is because in non-timeout cases the host is tried multiple times.
 		#
-		# Raises a PG::Error if the connection fails.
 		def new(*args)
 			conn = connect_to_hosts(*args)
 
@@ -788,7 +968,6 @@ class PG::Connection
 
 		# Resolve DNS in Ruby to avoid blocking state while connecting.
 		# Multiple comma-separated values are generated, if the hostname resolves to both IPv4 and IPv6 addresses.
-		# This requires PostgreSQL-10+, so no DNS resolving is done on earlier versions.
 		private def resolve_hosts(iopts)
 			ihosts = iopts[:host].split(",", -1)
 			iports = iopts[:port].split(",", -1)
@@ -798,16 +977,7 @@ class PG::Connection
 
 			dests = ihosts.each_with_index.flat_map do |mhost, idx|
 				unless host_is_named_pipe?(mhost)
-					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.
-						hostaddrs = Thread.new{ Addrinfo.getaddrinfo(mhost, nil, nil, :STREAM).map(&:ip_address) rescue [''] }.value
-					else
-						hostaddrs = Addrinfo.getaddrinfo(mhost, nil, nil, :STREAM).map(&:ip_address) rescue ['']
-					end
+					hostaddrs = Addrinfo.getaddrinfo(mhost, nil, nil, :STREAM).map(&:ip_address) rescue ['']
 				else
 					# No hostname to resolve (UnixSocket)
 					hostaddrs = [nil]
@@ -820,21 +990,47 @@ class PG::Connection
 				port: dests.map{|d| d[2] }.join(","))
 		end
 
+		RESOLUTION_KEYS = [:host, :hostaddr, :port].freeze
+		private_constant :RESOLUTION_KEYS
+
 		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)
+			iopts = PG::Connection.conninfo_parse(option_string).each_with_object({}) { |h, o| o[h[:keyword].to_sym] = h[:val] if h[:val] }
+
+			has_explicit_host = (!iopts[:host].to_s.empty? || !iopts[:hostaddr].to_s.empty?) && !iopts[:port].to_s.empty?
+			has_explicit_service = !iopts[:service].to_s.empty?
+
+			iopts_with_defaults = PG::Connection.conndefaults.each_with_object({}) do |h, o|
+				k = h[:keyword].to_sym
+				# Only use the host/hostname/port keys from defaults and leave user/dbname/sslmode/... for libpq, so that they are processed in the right order.
+				o[k] = h[:val] if h[:val] && RESOLUTION_KEYS.include?(k)
+			end.merge(iopts)
+
+			if PG::BUNDLED_LIBPQ_WITH_UNIXSOCKET && iopts_with_defaults[:host].to_s.empty? && iopts_with_defaults[:hostaddr].to_s.empty?
+				# Many distros patch the hardcoded default UnixSocket path in libpq to /var/run/postgresql instead of /tmp .
+				# We simply try them all.
+				iopts[:host] = "/var/run/postgresql" + # Ubuntu, Debian, Fedora, Opensuse
+					",/run/postgresql" + # Alpine, Archlinux, Gentoo
+					",/tmp" # Stock PostgreSQL
+			end
 
 			iopts_for_reset = iopts
-			if iopts[:hostaddr]
+			if iopts_with_defaults[:hostaddr]
 				# hostaddr is provided -> no need to resolve hostnames
-
-			elsif iopts[:host] && !iopts[:host].empty? && PG.library_version >= 100000
-				iopts = resolve_hosts(iopts)
+			elsif has_explicit_service && !has_explicit_host
+				# The pg_service.conf might provide host/user/port/etc.
+				# Ruby-pg cannot interpret pg_service without reading INI file and the additional LDAP stuff.
+				# So, pass params through and let libpq resolve the service, possibly blocking the Thread.scheduler.
+				# This ensures the processing order of libpq which is:
+				# connection string => service file => environment variable => compiled default
+			elsif iopts_with_defaults[:host] && !iopts_with_defaults[:host].empty?
+				# Do host resolution in Ruby to avoid blocking Thread.scheduler while DNS queries in libpq.
+				iopts_for_reset = iopts_with_defaults
+				iopts = resolve_hosts(iopts_with_defaults)
 			else
 				# No host given
 			end
-			conn = self.connect_start(iopts) or
+			conn = connect_start(iopts) or
 										raise(PG::Error, "Unable to create a new connection")
 
 			raise PG::ConnectionBad, conn.error_message if conn.status == PG::CONNECTION_BAD
@@ -897,14 +1093,29 @@ class PG::Connection
 		private_constant :REDIRECT_CLASS_METHODS
 
 		# These methods are affected by PQsetnonblocking
-		REDIRECT_SEND_METHODS = PG.make_shareable({
+		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],
-		})
+		}
 		private_constant :REDIRECT_SEND_METHODS
+		if PG::Connection.instance_methods.include? :sync_pipeline_sync
+			if PG::Connection.instance_methods.include? :send_pipeline_sync
+				# PostgreSQL-17+
+				REDIRECT_SEND_METHODS.merge!({
+					:pipeline_sync => [:async_pipeline_sync, :sync_pipeline_sync],
+				})
+			else
+				# PostgreSQL-14+
+				REDIRECT_SEND_METHODS.merge!({
+					:pipeline_sync => [:sync_pipeline_sync, :sync_pipeline_sync],
+				})
+			end
+		end
+		PG.make_shareable(REDIRECT_SEND_METHODS)
+
 		REDIRECT_METHODS = {
 			:exec => [:async_exec, :sync_exec],
 			:query => [:async_exec, :sync_exec],
@@ -921,12 +1132,14 @@ class PG::Connection
 			: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],
+			:encrypt_password => [:async_encrypt_password, :sync_encrypt_password],
 		}
 		private_constant :REDIRECT_METHODS
-
-		if PG::Connection.instance_methods.include? :async_encrypt_password
+		if PG::Connection.instance_methods.include? :async_close_prepared
+			# PostgreSQL-17+
 			REDIRECT_METHODS.merge!({
-				:encrypt_password => [:async_encrypt_password, :sync_encrypt_password],
+				:close_prepared => [:async_close_prepared, :sync_close_prepared],
+				:close_portal => [:async_close_portal, :sync_close_portal],
 			})
 		end
 		PG.make_shareable(REDIRECT_METHODS)