pg 0.18.4 → 1.2.3

data/ext/pg_type_map.c

@@ -1,6 +1,6 @@
 /*
  * pg_column_map.c - PG::ColumnMap class extension
- * $Id: pg_type_map.c,v fcf731d3dff7 2015/09/08 12:25:06 jfali $
+ * $Id$
  *
  */
 
@@ -11,46 +11,53 @@ VALUE rb_mDefaultTypeMappable;
 static ID s_id_fit_to_query;
 static ID s_id_fit_to_result;
 
+NORETURN( VALUE
+pg_typemap_fit_to_result( VALUE self, VALUE result ));
+NORETURN( VALUE
+pg_typemap_fit_to_query( VALUE self, VALUE params ));
+NORETURN( int
+pg_typemap_fit_to_copy_get( VALUE self ));
+NORETURN( VALUE
+pg_typemap_result_value( t_typemap *p_typemap, VALUE result, int tuple, int field ));
+NORETURN( t_pg_coder *
+pg_typemap_typecast_query_param( t_typemap *p_typemap, VALUE param_value, int field ));
+NORETURN( VALUE
+pg_typemap_typecast_copy_get( t_typemap *p_typemap, VALUE field_str, int fieldno, int format, int enc_idx ));
+
 VALUE
 pg_typemap_fit_to_result( VALUE self, VALUE result )
 {
 	rb_raise( rb_eNotImpError, "type map %s is not suitable to map result values", rb_obj_classname(self) );
-	return Qnil;
 }
 
 VALUE
 pg_typemap_fit_to_query( VALUE self, VALUE params )
 {
 	rb_raise( rb_eNotImpError, "type map %s is not suitable to map query params", rb_obj_classname(self) );
-	return Qnil;
 }
 
 int
 pg_typemap_fit_to_copy_get( VALUE self )
 {
 	rb_raise( rb_eNotImpError, "type map %s is not suitable to map get_copy_data results", rb_obj_classname(self) );
-	return Qnil;
 }
 
 VALUE
 pg_typemap_result_value( t_typemap *p_typemap, VALUE result, int tuple, int field )
 {
 	rb_raise( rb_eNotImpError, "type map is not suitable to map result values" );
-	return Qnil;
 }
 
 t_pg_coder *
 pg_typemap_typecast_query_param( t_typemap *p_typemap, VALUE param_value, int field )
 {
 	rb_raise( rb_eNotImpError, "type map is not suitable to map query params" );
-	return NULL;
 }
 
 VALUE
 pg_typemap_typecast_copy_get( t_typemap *p_typemap, VALUE field_str, int fieldno, int format, int enc_idx )
 {
 	rb_raise( rb_eNotImpError, "type map is not suitable to map get_copy_data results" );
-	return Qnil;
 }
 
 const struct pg_typemap_funcs pg_typemap_funcs = {

data/ext/pg_type_map_all_strings.c

@@ -1,6 +1,6 @@
 /*
  * pg_type_map_all_strings.c - PG::TypeMapAllStrings class extension
- * $Id: pg_type_map_all_strings.c,v c53f993a4254 2014/12/12 21:57:29 lars $
+ * $Id$
  *
  * This is the default typemap.
  *
@@ -33,9 +33,9 @@ pg_tmas_result_value( t_typemap *p_typemap, VALUE result, int tuple, int field )
 	len = PQgetlength( p_result->pgresult, tuple, field );
 
 	if ( 0 == PQfformat(p_result->pgresult, field) ) {
-		ret = pg_text_dec_string(NULL, val, len, tuple, field, ENCODING_GET(result));
+		ret = pg_text_dec_string(NULL, val, len, tuple, field, p_result->enc_idx);
 	} else {
-		ret = pg_bin_dec_bytea(NULL, val, len, tuple, field, ENCODING_GET(result));
+		ret = pg_bin_dec_bytea(NULL, val, len, tuple, field, p_result->enc_idx);
 	}
 
 	return ret;
@@ -99,7 +99,7 @@ init_pg_type_map_all_strings()
 	 * This type map casts all values received from the database server to Strings
 	 * and sends all values to the server after conversion to String by +#to_s+ .
 	 * That means, it is hard coded to PG::TextEncoder::String for value encoding
-	 * and to PG::TextDecoder::String for text format respectivly PG::BinaryDecoder::Bytea
+	 * and to PG::TextDecoder::String for text format respectively PG::BinaryDecoder::Bytea
 	 * for binary format received from the server.
 	 *
 	 * It is suitable for type casting query bind parameters, result values and

data/ext/pg_type_map_by_class.c

@@ -1,6 +1,6 @@
 /*
  * pg_type_map_by_class.c - PG::TypeMapByClass class extension
- * $Id: pg_type_map_by_class.c,v eeb8a82c5328 2014/11/10 19:34:02 lars $
+ * $Id$
  *
  * This type map can be used to select value encoders based on the class
  * of the given value to be send.
@@ -28,7 +28,7 @@ typedef struct {
  * We use 8 Bits of the klass object id as index to a 256 entry cache.
  * This avoids full lookups in most cases.
  */
-#define CACHE_LOOKUP(this, klass) ( &this->cache_row[(klass >> 8) & 0xff] )
+#define CACHE_LOOKUP(this, klass) ( &this->cache_row[(((unsigned long)klass) >> 8) & 0xff] )
 
 
 static t_pg_coder *
@@ -66,7 +66,7 @@ pg_tmbk_lookup_klass(t_tmbk *this, VALUE klass, VALUE param_value)
 			Data_Get_Struct(obj, t_pg_coder, p_coder);
 		}else{
 			if( RB_TYPE_P(obj, T_SYMBOL) ){
-				/* A Proc object (or something that responds to #call). */
+				/* A Symbol: Call the method with this name. */
 				obj = rb_funcall(this->self, SYM2ID(obj), 1, param_value);
 			}else{
 				/* A Proc object (or something that responds to #call). */
@@ -126,7 +126,11 @@ pg_tmbk_mark( t_tmbk *this )
 {
 	rb_gc_mark(this->typemap.default_typemap);
 	rb_gc_mark(this->klass_to_coder);
-	/* All coders are in the Hash, so no need to mark the cache. */
+	rb_gc_mark(this->self);
+	/* Clear the cache, to be safe from changes of klass VALUE by GC.compact.
+	 * TODO: Move cache clearing to compactation callback provided by Ruby-2.7+.
+	 */
+	memset(&this->cache_row, 0, sizeof(this->cache_row));
 }
 
 static VALUE
@@ -235,5 +239,6 @@ init_pg_type_map_by_class()
 	rb_define_method( rb_cTypeMapByClass, "[]=", pg_tmbk_aset, 2 );
 	rb_define_method( rb_cTypeMapByClass, "[]", pg_tmbk_aref, 1 );
 	rb_define_method( rb_cTypeMapByClass, "coders", pg_tmbk_coders, 0 );
+	/* rb_mDefaultTypeMappable = rb_define_module_under( rb_cTypeMap, "DefaultTypeMappable"); */
 	rb_include_module( rb_cTypeMapByClass, rb_mDefaultTypeMappable );
 }

data/ext/pg_type_map_by_column.c

@@ -1,6 +1,6 @@
 /*
  * pg_column_map.c - PG::ColumnMap class extension
- * $Id: pg_type_map_by_column.c,v fcf731d3dff7 2015/09/08 12:25:06 jfali $
+ * $Id$
  *
  */
 
@@ -99,11 +99,11 @@ pg_tmbc_result_value( t_typemap *p_typemap, VALUE result, int tuple, int field )
 		int len = PQgetlength( p_result->pgresult, tuple, field );
 
 		if( p_coder->dec_func ){
-			return p_coder->dec_func(p_coder, val, len, tuple, field, ENCODING_GET(result));
+			return p_coder->dec_func(p_coder, val, len, tuple, field, p_result->enc_idx);
 		} else {
 			t_pg_coder_dec_func dec_func;
 			dec_func = pg_coder_dec_func( p_coder, PQfformat(p_result->pgresult, field) );
-			return dec_func(p_coder, val, len, tuple, field, ENCODING_GET(result));
+			return dec_func(p_coder, val, len, tuple, field, p_result->enc_idx);
 		}
 	}
 
@@ -292,13 +292,13 @@ init_pg_type_map_by_column()
 	 *
 	 * This type map casts values by a coder assigned per field/column.
 	 *
-	 * Each PG:TypeMapByColumn has a fixed list of either encoders or decoders,
-	 * that is defined at #new . A type map with encoders is usable for type casting
+	 * Each PG::TypeMapByColumn has a fixed list of either encoders or decoders,
+	 * that is defined at TypeMapByColumn.new . A type map with encoders is usable for type casting
 	 * query bind parameters and COPY data for PG::Connection#put_copy_data .
 	 * A type map with decoders is usable for type casting of result values and
 	 * COPY data from PG::Connection#get_copy_data .
 	 *
-	 * PG::TypeMapByColumns are in particular useful in conjunction with prepared statements,
+	 * PG::TypeMapByColumn objects are in particular useful in conjunction with prepared statements,
 	 * since they can be cached alongside with the statement handle.
 	 *
 	 * This type map strategy is also used internally by PG::TypeMapByOid, when the
@@ -308,5 +308,6 @@ init_pg_type_map_by_column()
 	rb_define_alloc_func( rb_cTypeMapByColumn, pg_tmbc_s_allocate );
 	rb_define_method( rb_cTypeMapByColumn, "initialize", pg_tmbc_init, 1 );
 	rb_define_method( rb_cTypeMapByColumn, "coders", pg_tmbc_coders, 0 );
+	/* rb_mDefaultTypeMappable = rb_define_module_under( rb_cTypeMap, "DefaultTypeMappable"); */
 	rb_include_module( rb_cTypeMapByColumn, rb_mDefaultTypeMappable );
 }

data/ext/pg_type_map_by_mri_type.c

@@ -1,6 +1,6 @@
 /*
  * pg_type_map_by_mri_type.c - PG::TypeMapByMriType class extension
- * $Id: pg_type_map_by_mri_type.c,v 1269b8ad77b8 2015/02/06 16:38:23 lars $
+ * $Id$
  *
  * This type map can be used to select value encoders based on the MRI-internal
  * value type code.

data/ext/pg_type_map_by_oid.c

@@ -1,6 +1,6 @@
 /*
  * pg_type_map_by_oid.c - PG::TypeMapByOid class extension
- * $Id: pg_type_map_by_oid.c,v c99d26015e3c 2014/12/12 20:58:25 lars $
+ * $Id$
  *
  */
 
@@ -110,7 +110,7 @@ pg_tmbo_result_value(t_typemap *p_typemap, VALUE result, int tuple, int field)
 		char * val = PQgetvalue( p_result->pgresult, tuple, field );
 		int len = PQgetlength( p_result->pgresult, tuple, field );
 		t_pg_coder_dec_func dec_func = pg_coder_dec_func( p_coder, format );
-		return dec_func( p_coder, val, len, tuple, field, ENCODING_GET(result) );
+		return dec_func( p_coder, val, len, tuple, field, p_result->enc_idx );
 	}
 
 	default_tm = DATA_PTR( this->typemap.default_typemap );
@@ -351,5 +351,6 @@ init_pg_type_map_by_oid()
 	rb_define_method( rb_cTypeMapByOid, "max_rows_for_online_lookup=", pg_tmbo_max_rows_for_online_lookup_set, 1 );
 	rb_define_method( rb_cTypeMapByOid, "max_rows_for_online_lookup", pg_tmbo_max_rows_for_online_lookup_get, 0 );
 	rb_define_method( rb_cTypeMapByOid, "build_column_map", pg_tmbo_build_column_map, 1 );
+	/* rb_mDefaultTypeMappable = rb_define_module_under( rb_cTypeMap, "DefaultTypeMappable"); */
 	rb_include_module( rb_cTypeMapByOid, rb_mDefaultTypeMappable );
 }

data/ext/pg_type_map_in_ruby.c

@@ -1,6 +1,6 @@
 /*
  * pg_type_map_in_ruby.c - PG::TypeMapInRuby class extension
- * $Id: pg_type_map_in_ruby.c,v 3d89d3aae4fd 2015/01/05 16:19:41 kanis $
+ * $Id$
  *
  */
 

data/ext/{util.c → pg_util.c}

@@ -1,11 +1,11 @@
 /*
- * util.c - Utils for ruby-pg
- * $Id: util.c,v 5fb9170f6a7d 2015/06/29 11:15:12 kanis $
+ * pg_util.c - Utils for ruby-pg
+ * $Id$
  *
  */
 
 #include "pg.h"
-#include "util.h"
+#include "pg_util.h"
 
 static const char base64_encode_table[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
 
@@ -15,19 +15,19 @@ static const char base64_encode_table[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijk
  * in-place (with _out_ == _in_).
  */
 void
-base64_encode( char *out, char *in, int len)
+base64_encode( char *out, const char *in, int len)
 {
-	unsigned char *in_ptr = (unsigned char *)in + len;
+	const unsigned char *in_ptr = (const unsigned char *)in + len;
 	char *out_ptr = out + BASE64_ENCODED_SIZE(len);
 	int part_len = len % 3;
 
 	if( part_len > 0 ){
-		long byte2 = part_len > 2 ? *--in_ptr : 0;
+		long byte2 = 0;
 		long byte1 = part_len > 1 ? *--in_ptr : 0;
 		long byte0 = *--in_ptr;
 		long triple = (byte0 << 16) + (byte1 << 8) + byte2;
 
-		*--out_ptr = part_len > 2 ? base64_encode_table[(triple >> 0 * 6) & 0x3F] : '=';
+		*--out_ptr = '=';
 		*--out_ptr = part_len > 1 ? base64_encode_table[(triple >> 1 * 6) & 0x3F] : '=';
 		*--out_ptr = base64_encode_table[(triple >> 2 * 6) & 0x3F];
 		*--out_ptr = base64_encode_table[(triple >> 3 * 6) & 0x3F];
@@ -72,12 +72,12 @@ static const unsigned char base64_decode_table[] =
  * It is possible to decode a string in-place (with _out_ == _in_).
  */
 int
-base64_decode( char *out, char *in, unsigned int len)
+base64_decode( char *out, const char *in, unsigned int len)
 {
 	unsigned char a, b, c, d;
-	unsigned char *in_ptr = (unsigned char *)in;
+	const unsigned char *in_ptr = (const unsigned char *)in;
 	unsigned char *out_ptr = (unsigned char *)out;
-	unsigned char *iend_ptr = (unsigned char *)in + len;
+	const unsigned char *iend_ptr = (unsigned char *)in + len;
 
 	for(;;){
 		if( in_ptr+3 < iend_ptr &&

data/ext/{util.h → pg_util.h}

@@ -57,8 +57,8 @@
 #define BASE64_ENCODED_SIZE(strlen) (((strlen) + 2) / 3 * 4)
 #define BASE64_DECODED_SIZE(base64len) (((base64len) + 3) / 4 * 3)
 
-void base64_encode( char *out, char *in, int len);
-int base64_decode( char *out, char *in, unsigned int len);
+void base64_encode( char *out, const char *in, int len);
+int base64_decode( char *out, const char *in, unsigned int len);
 
 int rbpg_strncasecmp(const char *s1, const char *s2, size_t n);
 

data/lib/pg.rb

@@ -1,4 +1,5 @@
-#!/usr/bin/env ruby
+# -*- ruby -*-
+# frozen_string_literal: true
 
 begin
 	require 'pg_ext'
@@ -8,11 +9,23 @@ rescue LoadError
 		major_minor = RUBY_VERSION[ /^(\d+\.\d+)/ ] or
 			raise "Oops, can't extract the major/minor version from #{RUBY_VERSION.dump}"
 
-		# Set the PATH environment variable, so that libpq.dll can be found.
-		old_path = ENV['PATH']
-		ENV['PATH'] = "#{File.expand_path("../#{RUBY_PLATFORM}", __FILE__)};#{old_path}"
-		require "#{major_minor}/pg_ext"
-		ENV['PATH'] = old_path
+		add_dll_path = proc do |path, &block|
+			begin
+				require 'ruby_installer/runtime'
+				RubyInstaller::Runtime.add_dll_directory(path, &block)
+			rescue LoadError
+				old_path = ENV['PATH']
+				ENV['PATH'] = "#{path};#{old_path}"
+				block.call
+				ENV['PATH'] = old_path
+			end
+		end
+
+		# Temporary add this directory for DLL search, so that libpq.dll can be found.
+		# mingw32-platform strings differ (RUBY_PLATFORM=i386-mingw32 vs. x86-mingw32 for rubygems)
+		add_dll_path.call(File.join(__dir__, RUBY_PLATFORM.gsub(/^i386-/, "x86-"))) do
+			require "#{major_minor}/pg_ext"
+		end
 	else
 		raise
 	end
@@ -24,10 +37,10 @@ end
 module PG
 
 	# Library version
-	VERSION = '0.18.4'
+	VERSION = '1.2.3'
 
 	# VCS revision
-	REVISION = %q$Revision: da42b972b5ab $
+	REVISION = %q$Revision: 6f611e78845a $
 
 	class NotAllCopyDataRetrieved < PG::Error
 	end
@@ -49,16 +62,13 @@ module PG
 	require 'pg/exceptions'
 	require 'pg/constants'
 	require 'pg/coder'
+	require 'pg/binary_decoder'
 	require 'pg/text_encoder'
 	require 'pg/text_decoder'
 	require 'pg/basic_type_mapping'
 	require 'pg/type_map_by_column'
 	require 'pg/connection'
 	require 'pg/result'
+	require 'pg/tuple'
 
 end # module PG
-
-
-# Backward-compatible aliase
-PGError = PG::Error
-

data/lib/pg/basic_type_mapping.rb

@@ -1,7 +1,28 @@
-#!/usr/bin/env ruby
+# -*- ruby -*-
+# frozen_string_literal: true
 
 require 'pg' unless defined?( PG )
 
+# This module defines the mapping between OID and encoder/decoder classes for PG::BasicTypeMapForResults, PG::BasicTypeMapForQueries and PG::BasicTypeMapBasedOnResult.
+#
+# Additional types can be added like so:
+#
+#   require 'pg'
+#   require 'ipaddr'
+#
+#   class InetDecoder < PG::SimpleDecoder
+#     def decode(string, tuple=nil, field=nil)
+#       IPAddr.new(string)
+#     end
+#   end
+#   class InetEncoder < PG::SimpleEncoder
+#     def encode(ip_addr)
+#       ip_addr.to_s
+#     end
+#   end
+#
+#   # 0 if for text format, can also be 1 for binary
+#   PG::BasicTypeRegistry.register_type(0, 'inet', InetEncoder, InetDecoder)
 module PG::BasicTypeRegistry
 	# An instance of this class stores the coders that should be used for a given wire format (text or binary)
 	# and type cast direction (encoder or decoder).
@@ -97,13 +118,13 @@ module PG::BasicTypeRegistry
 	def build_coder_maps(connection)
 		if supports_ranges?(connection)
 			result = connection.exec <<-SQL
-				SELECT t.oid, t.typname, t.typelem, t.typdelim, t.typinput, r.rngsubtype
+				SELECT t.oid, t.typname::text, t.typelem, t.typdelim, t.typinput::text, r.rngsubtype
 				FROM pg_type as t
 				LEFT JOIN pg_range as r ON oid = rngtypid
 			SQL
 		else
 			result = connection.exec <<-SQL
-				SELECT t.oid, t.typname, t.typelem, t.typdelim, t.typinput
+				SELECT t.oid, t.typname::text, t.typelem, t.typdelim, t.typinput::text
 				FROM pg_type as t
 			SQL
 		end
@@ -134,19 +155,38 @@ module PG::BasicTypeRegistry
 	# objects as values.
 	CODERS_BY_NAME = []
 
-	# Register an OID type named +name+ with a typecasting encoder and decoder object in
-	# +type+.  +name+ should correspond to the `typname` column in
-	# the `pg_type` table.
+	public
+
+	# Register an encoder or decoder instance for casting a PostgreSQL type.
+	#
+	# Coder#name must correspond to the +typname+ column in the +pg_type+ table.
+	# Coder#format can be 0 for text format and 1 for binary.
+	def self.register_coder(coder)
+		h = CODERS_BY_NAME[coder.format] ||= { encoder: {}, decoder: {} }
+		name = coder.name || raise(ArgumentError, "name of #{coder.inspect} must be defined")
+		h[:encoder][name] = coder if coder.respond_to?(:encode)
+		h[:decoder][name] = coder if coder.respond_to?(:decode)
+	end
+
+	# Register the given +encoder_class+ and/or +decoder_class+ for casting a PostgreSQL type.
+	#
+	# +name+ must correspond to the +typname+ column in the +pg_type+ table.
+	# +format+ can be 0 for text format and 1 for binary.
 	def self.register_type(format, name, encoder_class, decoder_class)
-		CODERS_BY_NAME[format] ||= { encoder: {}, decoder: {} }
-		CODERS_BY_NAME[format][:encoder][name] = encoder_class.new(name: name, format: format) if encoder_class
-		CODERS_BY_NAME[format][:decoder][name] = decoder_class.new(name: name, format: format) if decoder_class
+		register_coder(encoder_class.new(name: name, format: format)) if encoder_class
+		register_coder(decoder_class.new(name: name, format: format)) if decoder_class
 	end
 
 	# Alias the +old+ type to the +new+ type.
 	def self.alias_type(format, new, old)
-		CODERS_BY_NAME[format][:encoder][new] = CODERS_BY_NAME[format][:encoder][old]
-		CODERS_BY_NAME[format][:decoder][new] = CODERS_BY_NAME[format][:decoder][old]
+		[:encoder, :decoder].each do |ende|
+			enc = CODERS_BY_NAME[format][ende][old]
+			if enc
+				CODERS_BY_NAME[format][ende][new] = enc
+			else
+				CODERS_BY_NAME[format][ende].delete(new)
+			end
+		end
 	end
 
 	register_type 0, 'int2', PG::TextEncoder::Integer, PG::TextDecoder::Integer
@@ -154,7 +194,7 @@ module PG::BasicTypeRegistry
 	alias_type    0, 'int8', 'int2'
 	alias_type    0, 'oid',  'int2'
 
-	# register_type 0, 'numeric', OID::Decimal.new
+	register_type 0, 'numeric', PG::TextEncoder::Numeric, PG::TextDecoder::Numeric
 	register_type 0, 'text', PG::TextEncoder::String, PG::TextDecoder::String
 	alias_type 0, 'varchar', 'text'
 	alias_type 0, 'char', 'text'
@@ -188,12 +228,13 @@ module PG::BasicTypeRegistry
 	# register_type 'polygon', OID::Text.new
 	# register_type 'circle', OID::Text.new
 	# register_type 'hstore', OID::Hstore.new
-	# register_type 'json', OID::Json.new
+	register_type 0, 'json', PG::TextEncoder::JSON, PG::TextDecoder::JSON
+	alias_type    0, 'jsonb',  'json'
 	# register_type 'citext', OID::Text.new
 	# register_type 'ltree', OID::Text.new
 	#
-	# register_type 'cidr', OID::Cidr.new
-	# alias_type 'inet', 'cidr'
+	register_type 0, 'inet', PG::TextEncoder::Inet, PG::TextDecoder::Inet
+	alias_type 0, 'cidr', 'inet'
 
 
 
@@ -212,12 +253,14 @@ module PG::BasicTypeRegistry
 	register_type 1, 'bool', PG::BinaryEncoder::Boolean, PG::BinaryDecoder::Boolean
 	register_type 1, 'float4', nil, PG::BinaryDecoder::Float
 	register_type 1, 'float8', nil, PG::BinaryDecoder::Float
+	register_type 1, 'timestamp', nil, PG::BinaryDecoder::TimestampUtc
+	register_type 1, 'timestamptz', nil, PG::BinaryDecoder::TimestampUtcToLocal
 end
 
 # Simple set of rules for type casting common PostgreSQL types to Ruby.
 #
 # OIDs of supported type casts are not hard-coded in the sources, but are retrieved from the
-# PostgreSQL's pg_type table in PG::BasicTypeMapForResults.new .
+# PostgreSQL's +pg_type+ table in PG::BasicTypeMapForResults.new .
 #
 # Result values are type casted based on the type OID of the given result column.
 #
@@ -226,18 +269,38 @@ end
 #
 # Example:
 #   conn = PG::Connection.new
-#   # Assign a default ruleset for type casts of input and output values.
-#   conn.type_mapping = PG::BasicTypeMapping.new(conn)
+#   # Assign a default ruleset for type casts of output values.
+#   conn.type_map_for_results = PG::BasicTypeMapForResults.new(conn)
 #   # Execute a query.
 #   res = conn.exec_params( "SELECT $1::INT", ['5'] )
 #   # Retrieve and cast the result value. Value format is 0 (text) and OID is 20. Therefore typecasting
 #   # is done by PG::TextDecoder::Integer internally for all value retrieval methods.
 #   res.values  # => [[5]]
 #
-# PG::TypeMapByOid#fit_to_result(result, false) can be used to generate
+# PG::TypeMapByOid#build_column_map(result) can be used to generate
 # a result independent PG::TypeMapByColumn type map, which can subsequently be used
-# to cast #get_copy_data fields. See also PG::BasicTypeMapBasedOnResult .
+# to cast #get_copy_data fields:
+#
+# For the following table:
+#   conn.exec( "CREATE TABLE copytable AS VALUES('a', 123, '{5,4,3}'::INT[])" )
+#
+#   # Retrieve table OIDs per empty result set.
+#   res = conn.exec( "SELECT * FROM copytable LIMIT 0" )
+#   # Build a type map for common database to ruby type decoders.
+#   btm = PG::BasicTypeMapForResults.new(conn)
+#   # Build a PG::TypeMapByColumn with decoders suitable for copytable.
+#   tm = btm.build_column_map( res )
+#   row_decoder = PG::TextDecoder::CopyRow.new type_map: tm
 #
+#   conn.copy_data( "COPY copytable TO STDOUT", row_decoder ) do |res|
+#     while row=conn.get_copy_data
+#       p row
+#     end
+#   end
+# This prints the rows with type casted columns:
+#   ["a", 123, [5, 4, 3]]
+#
+# See also PG::BasicTypeMapBasedOnResult for the encoder direction and PG::BasicTypeRegistry for the definition of additional types.
 class PG::BasicTypeMapForResults < PG::TypeMapByOid
 	include PG::BasicTypeRegistry
 
@@ -251,7 +314,7 @@ class PG::BasicTypeMapForResults < PG::TypeMapByOid
 			format = result.fformat(field)
 			oid = result.ftype(field)
 			unless @already_warned[format][oid]
-				STDERR.puts "Warning: no type cast defined for type #{@typenames_by_oid[format][oid].inspect} with oid #{oid}. Please cast this type explicitly to TEXT to be safe for future changes."
+				$stderr.puts "Warning: no type cast defined for type #{@typenames_by_oid[format][oid].inspect} with oid #{oid}. Please cast this type explicitly to TEXT to be safe for future changes."
 				 @already_warned[format][oid] = true
 			end
 			super
@@ -275,7 +338,7 @@ end
 # to PostgreSQL.
 #
 # OIDs of supported type casts are not hard-coded in the sources, but are retrieved from the
-# PostgreSQL's pg_type table in PG::BasicTypeMapBasedOnResult.new .
+# PostgreSQL's +pg_type+ table in PG::BasicTypeMapBasedOnResult.new .
 #
 # This class works equal to PG::BasicTypeMapForResults, but does not define decoders for
 # the given result OIDs, but encoders. So it can be used to type cast field values based on
@@ -290,12 +353,17 @@ end
 #
 #   # Retrieve table OIDs per empty result set.
 #   res = conn.exec( "SELECT * FROM copytable LIMIT 0" )
-#   tm = basic_type_mapping.build_column_map( res )
+#   # Build a type map for common ruby to database type encoders.
+#   btm = PG::BasicTypeMapBasedOnResult.new(conn)
+#   # Build a PG::TypeMapByColumn with encoders suitable for copytable.
+#   tm = btm.build_column_map( res )
 #   row_encoder = PG::TextEncoder::CopyRow.new type_map: tm
 #
 #   conn.copy_data( "COPY copytable FROM STDIN", row_encoder ) do |res|
 #     conn.put_copy_data ['a', 123, [5,4,3]]
 #   end
+# This inserts a single row into copytable with type casts from ruby to
+# database types.
 class PG::BasicTypeMapBasedOnResult < PG::TypeMapByOid
 	include PG::BasicTypeRegistry
 
@@ -314,31 +382,65 @@ end
 # OIDs of supported type casts are not hard-coded in the sources, but are retrieved from the
 # PostgreSQL's pg_type table in PG::BasicTypeMapForQueries.new .
 #
-# Query params are type casted based on the MRI internal type of the given value.
+# Query params are type casted based on the class of the given value.
 #
 # Higher level libraries will most likely not make use of this class, but use their
-# own set of rules to choose suitable encoders and decoders.
+# own derivation of PG::TypeMapByClass or another set of rules to choose suitable
+# encoders and decoders for the values to be sent.
 #
 # Example:
 #   conn = PG::Connection.new
 #   # Assign a default ruleset for type casts of input and output values.
-#   conn.type_mapping_for_queries = PG::BasicTypeMapForQueries.new(conn)
+#   conn.type_map_for_queries = PG::BasicTypeMapForQueries.new(conn)
 #   # Execute a query. The Integer param value is typecasted internally by PG::BinaryEncoder::Int8.
-#   # The format of the parameter is set to 1 (binary) and the OID of this parameter is set to 20 (int8).
+#   # The format of the parameter is set to 0 (text) and the OID of this parameter is set to 20 (int8).
 #   res = conn.exec_params( "SELECT $1", [5] )
 class PG::BasicTypeMapForQueries < PG::TypeMapByClass
 	include PG::BasicTypeRegistry
 
 	def initialize(connection)
 		@coder_maps = build_coder_maps(connection)
-
-		populate_encoder_list
 		@array_encoders_by_klass = array_encoders_by_klass
-		@anyarray_encoder = coder_by_name(0, :encoder, '_any')
+		@encode_array_as = :array
+		init_encoders
+	end
+
+	# Change the mechanism that is used to encode ruby array values
+	#
+	# Possible values:
+	# * +:array+ : Encode the ruby array as a PostgreSQL array.
+	#   The array element type is inferred from the class of the first array element. This is the default.
+	# * +:json+ : Encode the ruby array as a JSON document.
+	# * +:record+ : Encode the ruby array as a composite type row.
+	# * <code>"_type"</code> : Encode the ruby array as a particular PostgreSQL type.
+	#   All PostgreSQL array types are supported.
+	#   If there's an encoder registered for the elements +type+, it will be used.
+	#   Otherwise a string conversion (by +value.to_s+) is done.
+	def encode_array_as=(pg_type)
+		case pg_type
+			when :array
+			when :json
+			when :record
+			when /\A_/
+			else
+				raise ArgumentError, "invalid pg_type #{pg_type.inspect}"
+		end
+
+		@encode_array_as = pg_type
+
+		init_encoders
 	end
 
+	attr_reader :encode_array_as
+
 	private
 
+	def init_encoders
+		coders.each { |kl, c| self[kl] = nil } # Clear type map
+		populate_encoder_list
+		@textarray_encoder = coder_by_name(0, :encoder, '_text')
+	end
+
 	def coder_by_name(format, direction, name)
 		check_format_and_direction(format, direction)
 		@coder_maps[format][direction].coder_by_name(name)
@@ -356,7 +458,19 @@ class PG::BasicTypeMapForQueries < PG::TypeMapByClass
 				end
 				self[klass] = coder
 			else
-				self[klass] = selector
+
+				case @encode_array_as
+					when :array
+						self[klass] = selector
+					when :json
+						self[klass] = PG::TextEncoder::JSON.new
+					when :record
+						self[klass] = PG::TextEncoder::Record.new type_map: self
+					when /\A_/
+						self[klass] = coder_by_name(0, :encoder, @encode_array_as) || raise(ArgumentError, "unknown array type #{@encode_array_as.inspect}")
+					else
+						raise ArgumentError, "invalid pg_type #{@encode_array_as.inspect}"
+				end
 			end
 		end
 	end
@@ -375,7 +489,7 @@ class PG::BasicTypeMapForQueries < PG::TypeMapByClass
 		end
 		@array_encoders_by_klass[elem.class] ||
 				elem.class.ancestors.lazy.map{|ancestor| @array_encoders_by_klass[ancestor] }.find{|a| a } ||
-				@anyarray_encoder
+				@textarray_encoder
 	end
 
 	DEFAULT_TYPE_MAP = {
@@ -385,6 +499,12 @@ class PG::BasicTypeMapForQueries < PG::TypeMapByClass
 		# to unnecessary type conversions on server side.
 		Integer => [0, 'int8'],
 		Float => [0, 'float8'],
+		BigDecimal => [0, 'numeric'],
+		Time => [0, 'timestamptz'],
+		# We use text format and no type OID for IPAddr, because setting the OID can lead
+		# to unnecessary inet/cidr conversions on the server side.
+		IPAddr => [0, 'inet'],
+		Hash => [0, 'json'],
 		Array => :get_array_type,
 	}
 
@@ -394,6 +514,9 @@ class PG::BasicTypeMapForQueries < PG::TypeMapByClass
 		Integer => [0, '_int8'],
 		String => [0, '_text'],
 		Float => [0, '_float8'],
+		BigDecimal => [0, '_numeric'],
+		Time => [0, '_timestamptz'],
+		IPAddr => [0, '_inet'],
 	}
 
 end