pg 1.3.0.rc1 → 1.3.0

data/ext/pg_record_coder.c

@@ -134,7 +134,7 @@ pg_recordcoder_type_map_get(VALUE self)
  *   tm = PG::TypeMapByColumn.new([PG::TextEncoder::Float.new]*2)
  *   # Use this type map to encode the record:
  *   PG::TextEncoder::Record.new(type_map: tm).encode([1,2])
- *   # => "(\"1.0000000000000000E+00\",\"2.0000000000000000E+00\")"
+ *   # => "(\"1.0\",\"2.0\")"
  *
  * Records can also be encoded and decoded directly to and from the database.
  * This avoids intermediate string allocations and is very fast.

data/lib/pg/basic_type_registry.rb

@@ -162,7 +162,7 @@ class PG::BasicTypeRegistry
 
 	include Checker
 
-  def initialize
+	def initialize
 		# The key of these hashs maps to the `typname` column from the table pg_type.
 		@coders_by_name = []
 	end

data/lib/pg/connection.rb

@@ -7,7 +7,7 @@ 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.
 #
@@ -21,6 +21,13 @@ require 'socket'
 #
 # 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.
@@ -364,14 +371,44 @@ class PG::Connection
 		end
 	end
 
-	alias sync_get_result get_result
-	def async_get_result(*args)
+	# 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(*args)
 		block
 		sync_get_result
 	end
+	alias async_get_result get_result
 
-	alias sync_get_copy_data get_copy_data
-	def async_get_copy_data(async=false, decoder=nil)
+	# 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
@@ -382,56 +419,143 @@ class PG::Connection
 			return res
 		end
 	end
+	alias async_get_copy_data get_copy_data
 
-	# In async_api=false mode all send calls run directly on libpq.
-	# Blocking vs. nonblocking state can be changed in libpq.
-	alias sync_setnonblocking setnonblocking
 
 	# In async_api=true mode (default) all send calls run nonblocking.
 	# The difference is that setnonblocking(true) disables automatic handling of would-block cases.
-	def async_setnonblocking(enabled)
+	# 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()
-	alias sync_isnonblocking isnonblocking
-	def async_isnonblocking
+
+	# 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
 
-	alias sync_put_copy_data put_copy_data
-	def async_put_copy_data(buffer, encoder=nil)
+	# 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)
 		until sync_put_copy_data(buffer, encoder)
 			flush
 		end
 		flush
 	end
-	alias sync_put_copy_end put_copy_end
-	def async_put_copy_end(*args)
+	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
 		flush
 	end
+	alias async_put_copy_end put_copy_end
 
-	if method_defined? :encrypt_password
-		alias sync_encrypt_password encrypt_password
-		def async_encrypt_password( password, username, algorithm=nil )
+	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
 
-	alias sync_reset reset
-	def async_reset
+	# 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)
 	end
+	alias async_reset reset
 
-	alias sync_cancel cancel
-	def async_cancel
+	# 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")
@@ -484,6 +608,7 @@ class PG::Connection
 	rescue SystemCallError => err
 		err.to_s
 	end
+	alias async_cancel cancel
 
 	private def async_connect_or_reset(poll_meth)
 		# Now grab a reference to the underlying socket so we know when the connection is established
@@ -520,19 +645,90 @@ class PG::Connection
 	end
 
 	class << self
-		alias sync_connect new
-
-		def async_connect(*args, **kwargs)
-			conn = PG::Connection.connect_start(*args, **kwargs ) or
+		# 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, **kwargs)
+			conn = self.connect_start(*args, **kwargs ) or
 				raise(PG::Error, "Unable to create a new connection")
 
 			raise(PG::ConnectionBad, conn.error_message) if conn.status == PG::CONNECTION_BAD
 
 			conn.send(:async_connect_or_reset, :connect_poll)
 		end
+		alias async_connect new
+		alias connect new
+		alias open new
+		alias setdb new
+		alias setdblogin new
 
-		alias sync_ping ping
-		def async_ping(*args)
+		# 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.
@@ -541,9 +737,14 @@ class PG::Connection
 				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],
 		}
 
@@ -586,6 +787,22 @@ class PG::Connection
 			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)|
@@ -599,6 +816,5 @@ class PG::Connection
 		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/version.rb

@@ -1,4 +1,4 @@
 module PG
 	# Library version
-	VERSION = '1.3.0.rc1'
+	VERSION = '1.3.0'
 end

data/lib/pg.rb

@@ -63,8 +63,8 @@ module PG
 
 
 	### Convenience alias for PG::Connection.new.
-	def self::connect( *args )
-		return PG::Connection.new( *args )
+	def self::connect( *args, **kwargs )
+		return PG::Connection.new( *args, **kwargs )
 	end
 
 

metadata

@@ -1,34 +1,40 @@
 --- !ruby/object:Gem::Specification
 name: pg
 version: !ruby/object:Gem::Version
-  version: 1.3.0.rc1
+  version: 1.3.0
 platform: ruby
 authors:
 - Michael Granger
 - Lars Kanis
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain:
 - |
   -----BEGIN CERTIFICATE-----
-  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
+  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
+  btEP+7EplFuoiMfd
   -----END CERTIFICATE-----
-date: 2021-12-27 00:00:00.000000000 Z
+date: 2022-01-23 00:00:00.000000000 Z
 dependencies: []
 description: Pg is the Ruby interface to the PostgreSQL RDBMS. It works with PostgreSQL
   9.3 and later.
@@ -152,7 +158,7 @@ metadata:
   source_code_uri: https://github.com/ged/ruby-pg
   changelog_uri: https://github.com/ged/ruby-pg/blob/master/History.rdoc
   documentation_uri: http://deveiate.org/code/pg
-post_install_message: 
+post_install_message:
 rdoc_options:
 - "--main"
 - README.rdoc
@@ -165,12 +171,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
-rubygems_version: 3.2.15
-signing_key: 
+rubygems_version: 3.2.22
+signing_key:
 specification_version: 4
 summary: Pg is the Ruby interface to the PostgreSQL RDBMS
 test_files: []