pg 1.0.0 → 1.1.0.pre20180730144600

data/History.rdoc

@@ -1,3 +1,54 @@
+== v2.0.0 - far from release -
+
+Removed:
+- Removed query method variants deprecated in pg-1.1.0.
+
+
+== v1.1.0 [YYYY-MM-DD] Michael Granger <ged@FaerieMUD.org>
+
+Deprecated:
+- Forwarding conn.exec to conn.exec_params is deprecated.
+- Forwarding conn.exec_params to conn.exec is deprecated.
+- Forwarding conn.async_exec to conn.async_exec_params.
+- Forwarding conn.send_query to conn.send_query_params is deprecated.
+- Forwarding conn.async_exec_params to conn.async_exec is deprecated.
+
+PG::Connection enhancements:
+- Provide PG::Connection#sync_* and PG::Connection#async_* query methods for explicit calling syncronous or asynchronous libpq API.
+- Make PG::Connection#exec and siblings switchable between sync and async API per PG::Connection.async_api= and change the default to async flavors.
+- Add async flavors of exec_params, prepare, exec_prepared, describe_prepared and describe_portal.
+  They are identical to their syncronous counterpart, but make use of PostgreSQL's async API.
+- Replace `rb_thread_fd_select()` by faster `rb_wait_for_single_fd()` in `conn.block` and `conn.async_exec` .
+- Add PG::Connection#discard_results .
+
+Result retrieval enhancements:
+- Add PG::Result#tuple_values to retrieve all field values of a row as array.
+- Add PG::Tuple, PG::Result#tuple_values and PG::Result#stream_each_tuple .
+  PG::Tuple offers a way to lazy cast result values.
+- Estimate PG::Result size allocated by libpq and notify the garbage collector about it when running on Ruby-2.4 or newer.
+- Make the estimated PG::Result size available to ObjectSpace.memsize_of(result) .
+
+Type cast enhancements:
+- Replace Ruby code by a faster C implementation of the SimpleDecoder's timestamp decode functions. github #20
+- Interpret years with up to 7 digists and BC dates by timestamp decoder.
+- Add text timestamp decoders for UTC vs. local timezone variations.
+- Add text timestamp encoders for UTC timezone.
+- Add decoders for binary timestamps: PG::BinaryDecoder::Timestamp and variations.
+- Add PG::Coder#flags accessor to allow modifications of de- respectively encoder behaviour.
+- Add a flag to raise TypeError for invalid input values to PG::TextDecoder::Array .
+- Add a text decoder for inet/cidr written in C.
+- Add a numeric decoder written in C.
+- Ensure input text is zero terminated for text format in PG::Coder#decode .
+
+Source code enhancements:
+- Fix headers and permission bits of various repository files.
+
+Bugfixes:
+- Properly decode array with prepended dimensions. #272
+  For now dimension decorations are ignored, but a correct Array is returned.
+- Array-Decoder: Avoid leaking memory when an Exception is raised while parsing. Fixes #279
+
+
 == v1.0.0 [2018-01-10] Michael Granger <ged@FaerieMUD.org>
 
 Deprecated:
@@ -7,6 +58,7 @@ Deprecated:
 Removed:
 - Remove compatibility code for Ruby < 2.0 and PostgreSQL < 9.2.
 - Remove partial compatibility with Rubinius.
+- Remove top-level constants PGconn, PGresult, and PGError.
 
 Enhancements:
 - Update error codes to PostgreSQL-10

data/README.rdoc

@@ -44,6 +44,17 @@ It usually work with earlier versions of Ruby/PostgreSQL as well, but those are
 not regularly tested.
 
 
+== Versioning
+
+We tag and release gems according to the {Semantic Versioning}[http://semver.org/] principle.
+
+As a result of this policy, you can (and should) specify a dependency on this gem using the {Pessimistic Version Constraint}[http://guides.rubygems.org/patterns/#pessimistic-version-constraint] with two digits of precision.
+
+For example:
+
+  spec.add_dependency 'pg', '~> 1.0'
+
+
 == How To Install
 
 Install via RubyGems:

data/Rakefile

@@ -1,4 +1,4 @@
-#!/usr/bin/env rake
+# -*- rake -*-
 
 require 'rbconfig'
 require 'pathname'

data/Rakefile.cross

@@ -1,4 +1,4 @@
-#!/usr/bin/env rake
+# -*- rake -*-
 
 require 'uri'
 require 'tempfile'

data/ext/errorcodes.rb

@@ -1,4 +1,4 @@
-#!/usr/bin/env ruby
+# -*- ruby -*-
 
 def camelize(lower_case_and_underscored_word)
 	lower_case_and_underscored_word.to_s.gsub(/\/(.?)/) { "::" + $1.upcase }.gsub(/(^|_)(.)/) { $2.upcase }

data/ext/extconf.rb

@@ -76,6 +76,8 @@ have_func 'PQsetSingleRowMode' or
 have_func 'PQconninfo'
 have_func 'PQsslAttribute'
 have_func 'PQencryptPasswordConn'
+have_func 'timegm'
+have_func 'rb_gc_adjust_memory_usage'
 
 have_const 'PG_DIAG_TABLE_NAME', 'libpq-fe.h'
 

data/ext/pg.c

@@ -1,6 +1,6 @@
 /*
  * pg.c - Toplevel extension
- * $Id: pg.c,v 1f0926bfa9a5 2018/01/04 18:14:32 lars $
+ * $Id$
  *
  * Author/s:
  *
@@ -143,7 +143,7 @@ pg_find_or_create_johab(void)
 
 	enc_index = rb_define_dummy_encoding(aliases[0]);
 	for (i = 1; i < sizeof(aliases)/sizeof(aliases[0]); ++i) {
-		rb_encdb_alias(aliases[i], aliases[0]);
+		rb_enc_alias(aliases[i], aliases[0]);
 	}
 	return rb_enc_from_index(enc_index);
 }
@@ -630,5 +630,6 @@ Init_pg_ext()
 	init_pg_binary_encoder();
 	init_pg_binary_decoder();
 	init_pg_copycoder();
+	init_pg_tuple();
 }
 

data/ext/pg.h

@@ -22,7 +22,7 @@
 #include "ruby/encoding.h"
 
 /* exported by ruby-1.9.3+ but not declared */
-extern int rb_encdb_alias(const char *, const char *);
+extern int rb_enc_alias(const char *, const char *);
 
 #define PG_ENCODING_SET_NOCHECK(obj,i) \
 	do { \
@@ -77,6 +77,10 @@ typedef long suseconds_t;
 	#define PG_MAX_COLUMNS 4000
 #endif
 
+#ifndef RARRAY_AREF
+#define RARRAY_AREF(a, i) (RARRAY_PTR(a)[i])
+#endif
+
 /* The data behind each PG::Connection object */
 typedef struct {
 	PGconn *pgconn;
@@ -100,6 +104,11 @@ typedef struct {
 	/* Kind of PG::Coder object for casting COPY rows to ruby values */
 	VALUE decoder_for_get_copy_data;
 
+	/* The connection socket, used for rb_wait_for_single_fd() */
+	int socket;
+
+	/* enable/disable guessing size of PGresult's allocated memory */
+	int guess_result_memsize;
 } t_pg_connection;
 
 typedef struct pg_coder t_pg_coder;
@@ -130,9 +139,15 @@ typedef struct {
 	 */
 	int nfields;
 
+	/* Size of PGresult as published to ruby memory management. */
+	ssize_t result_size;
+
 	/* Prefilled tuple Hash with fnames[] as keys. */
 	VALUE tuple_hash;
 
+	/* Hash with fnames[] to field number mapping. */
+	VALUE field_map;
+
 	/* List of field names as frozen String objects.
 	 * Only valid if nfields != -1
 	 */
@@ -141,7 +156,7 @@ typedef struct {
 
 
 typedef int (* t_pg_coder_enc_func)(t_pg_coder *, VALUE, char *, VALUE *, int);
-typedef VALUE (* t_pg_coder_dec_func)(t_pg_coder *, char *, int, int, int, int);
+typedef VALUE (* t_pg_coder_dec_func)(t_pg_coder *, const char *, int, int, int, int);
 typedef VALUE (* t_pg_fit_to_result)(VALUE, VALUE);
 typedef VALUE (* t_pg_fit_to_query)(VALUE, VALUE);
 typedef int (* t_pg_fit_to_copy_get)(VALUE);
@@ -149,12 +164,23 @@ typedef VALUE (* t_pg_typecast_result)(t_typemap *, VALUE, int, int);
 typedef t_pg_coder *(* t_pg_typecast_query_param)(t_typemap *, VALUE, int);
 typedef VALUE (* t_pg_typecast_copy_get)( t_typemap *, VALUE, int, int, int );
 
+#define PG_CODER_TIMESTAMP_DB_UTC 0x0
+#define PG_CODER_TIMESTAMP_DB_LOCAL 0x1
+#define PG_CODER_TIMESTAMP_APP_UTC 0x0
+#define PG_CODER_TIMESTAMP_APP_LOCAL 0x2
+#define PG_CODER_FORMAT_ERROR_MASK 0xc
+#define PG_CODER_FORMAT_ERROR_TO_RAISE 0x4
+#define PG_CODER_FORMAT_ERROR_TO_STRING 0x8
+#define PG_CODER_FORMAT_ERROR_TO_PARTIAL 0xc
+
 struct pg_coder {
 	t_pg_coder_enc_func enc_func;
 	t_pg_coder_dec_func dec_func;
 	VALUE coder_obj;
 	Oid oid;
 	int format;
+	/* OR-ed values out of PG_CODER_* */
+	int flags;
 };
 
 typedef struct {
@@ -253,9 +279,10 @@ void init_pg_text_encoder                              _(( void ));
 void init_pg_text_decoder                              _(( void ));
 void init_pg_binary_encoder                            _(( void ));
 void init_pg_binary_decoder                            _(( void ));
+void init_pg_tuple                                     _(( void ));
 VALUE lookup_error_class                               _(( const char * ));
-VALUE pg_bin_dec_bytea                                 _(( t_pg_coder*, char *, int, int, int, int ));
-VALUE pg_text_dec_string                               _(( t_pg_coder*, char *, int, int, int, int ));
+VALUE pg_bin_dec_bytea                                 _(( t_pg_coder*, const char *, int, int, int, int ));
+VALUE pg_text_dec_string                               _(( t_pg_coder*, const char *, int, int, int, int ));
 int pg_coder_enc_to_s                                  _(( t_pg_coder*, VALUE, char *, VALUE *, int));
 int pg_text_enc_identifier                             _(( t_pg_coder*, VALUE, char *, VALUE *, int));
 t_pg_coder_enc_func pg_coder_enc_func                  _(( t_pg_coder* ));
@@ -298,6 +325,7 @@ VALUE pg_new_result_autoclear                          _(( PGresult *, VALUE ));
 PGresult* pgresult_get                                 _(( VALUE ));
 VALUE pg_result_check                                  _(( VALUE ));
 VALUE pg_result_clear                                  _(( VALUE ));
+VALUE pg_tuple_new                                     _(( VALUE, int ));
 
 /*
  * Fetch the data pointer for the result object
@@ -305,7 +333,7 @@ VALUE pg_result_clear                                  _(( VALUE ));
 static inline t_pg_result *
 pgresult_get_this( VALUE self )
 {
-	t_pg_result *this = DATA_PTR(self);
+	t_pg_result *this = RTYPEDDATA_DATA(self);
 
 	if( this == NULL )
 		rb_raise(rb_ePGerror, "result has been cleared");

data/ext/pg_binary_decoder.c

@@ -1,9 +1,10 @@
 /*
  * pg_column_map.c - PG::ColumnMap class extension
- * $Id: pg_binary_decoder.c,v fcf731d3dff7 2015/09/08 12:25:06 jfali $
+ * $Id$
  *
  */
 
+#include "ruby/version.h"
 #include "pg.h"
 #include "util.h"
 #ifdef HAVE_INTTYPES_H
@@ -21,7 +22,7 @@ VALUE rb_mPG_BinaryDecoder;
  *
  */
 static VALUE
-pg_bin_dec_boolean(t_pg_coder *conv, char *val, int len, int tuple, int field, int enc_idx)
+pg_bin_dec_boolean(t_pg_coder *conv, const char *val, int len, int tuple, int field, int enc_idx)
 {
 	if (len < 1) {
 		rb_raise( rb_eTypeError, "wrong data for binary boolean converter in tuple %d field %d", tuple, field);
@@ -37,7 +38,7 @@ pg_bin_dec_boolean(t_pg_coder *conv, char *val, int len, int tuple, int field, i
  *
  */
 static VALUE
-pg_bin_dec_integer(t_pg_coder *conv, char *val, int len, int tuple, int field, int enc_idx)
+pg_bin_dec_integer(t_pg_coder *conv, const char *val, int len, int tuple, int field, int enc_idx)
 {
 	switch( len ){
 		case 2:
@@ -59,7 +60,7 @@ pg_bin_dec_integer(t_pg_coder *conv, char *val, int len, int tuple, int field, i
  *
  */
 static VALUE
-pg_bin_dec_float(t_pg_coder *conv, char *val, int len, int tuple, int field, int enc_idx)
+pg_bin_dec_float(t_pg_coder *conv, const char *val, int len, int tuple, int field, int enc_idx)
 {
 	union {
 		float f;
@@ -91,7 +92,7 @@ pg_bin_dec_float(t_pg_coder *conv, char *val, int len, int tuple, int field, int
  *
  */
 VALUE
-pg_bin_dec_bytea(t_pg_coder *conv, char *val, int len, int tuple, int field, int enc_idx)
+pg_bin_dec_bytea(t_pg_coder *conv, const char *val, int len, int tuple, int field, int enc_idx)
 {
 	VALUE ret;
 	ret = rb_tainted_str_new( val, len );
@@ -106,7 +107,7 @@ pg_bin_dec_bytea(t_pg_coder *conv, char *val, int len, int tuple, int field, int
  *
  */
 static VALUE
-pg_bin_dec_to_base64(t_pg_coder *conv, char *val, int len, int tuple, int field, int enc_idx)
+pg_bin_dec_to_base64(t_pg_coder *conv, const char *val, int len, int tuple, int field, int enc_idx)
 {
 	t_pg_composite_coder *this = (t_pg_composite_coder *)conv;
 	t_pg_coder_dec_func dec_func = pg_coder_dec_func(this->elem, this->comp.format);
@@ -130,6 +131,66 @@ pg_bin_dec_to_base64(t_pg_coder *conv, char *val, int len, int tuple, int field,
 	return out_value;
 }
 
+#define PG_INT64_MIN	(-0x7FFFFFFFFFFFFFFFL - 1)
+#define PG_INT64_MAX	0x7FFFFFFFFFFFFFFFL
+
+/*
+ * Document-class: PG::BinaryDecoder::Timestamp < PG::SimpleDecoder
+ *
+ * This is a decoder class for conversion of PostgreSQL binary timestamps
+ * to Ruby Time objects.
+ *
+ * The following flags can be used to specify timezone interpretation:
+ * * +PG::Coder::TIMESTAMP_DB_UTC+ : Interpret timestamp as UTC time (default)
+ * * +PG::Coder::TIMESTAMP_DB_LOCAL+ : Interpret timestamp as local time
+ * * +PG::Coder::TIMESTAMP_APP_UTC+ : Return timestamp as UTC time (default)
+ * * +PG::Coder::TIMESTAMP_APP_LOCAL+ : Return timestamp as local time
+ *
+ * Example:
+ *   deco = PG::BinaryDecoder::Timestamp.new(flags: PG::Coder::TIMESTAMP_DB_UTC | PG::Coder::TIMESTAMP_APP_LOCAL)
+ *   deco.decode("\0"*8)  # => 2000-01-01 01:00:00 +0100
+ */
+static VALUE
+pg_bin_dec_timestamp(t_pg_coder *conv, const char *val, int len, int tuple, int field, int enc_idx)
+{
+	int64_t timestamp;
+	struct timespec ts;
+	VALUE t;
+
+	if( len != sizeof(timestamp) ){
+		rb_raise( rb_eTypeError, "wrong data for timestamp converter in tuple %d field %d length %d", tuple, field, len);
+	}
+
+	timestamp = read_nbo64(val);
+
+	switch(timestamp){
+		case PG_INT64_MAX:
+			return rb_str_new2("infinity");
+		case PG_INT64_MIN:
+			return rb_str_new2("-infinity");
+		default:
+			/* PostgreSQL's timestamp is based on year 2000 and Ruby's time is based on 1970.
+			 * Adjust the 30 years difference. */
+			ts.tv_sec = (timestamp / 1000000) + 10957L * 24L * 3600L;
+			ts.tv_nsec = (timestamp % 1000000) * 1000;
+
+#if (RUBY_API_VERSION_MAJOR > 2 || (RUBY_API_VERSION_MAJOR == 2 && RUBY_API_VERSION_MINOR >= 3)) && defined(NEGATIVE_TIME_T)
+			/* Fast path for time conversion */
+			t = rb_time_timespec_new(&ts, conv->flags & PG_CODER_TIMESTAMP_APP_LOCAL ? INT_MAX : INT_MAX-1);
+#else
+			t = rb_funcall(rb_cTime, rb_intern("at"), 2, LL2NUM(ts.tv_sec), LL2NUM(ts.tv_nsec / 1000));
+			if( !(conv->flags & PG_CODER_TIMESTAMP_APP_LOCAL) ) {
+				t = rb_funcall(t, rb_intern("utc"), 0);
+			}
+#endif
+			if( conv->flags & PG_CODER_TIMESTAMP_DB_LOCAL ) {
+				/* interpret it as local time */
+				t = rb_funcall(t, rb_intern("-"), 1, rb_funcall(t, rb_intern("utc_offset"), 0));
+			}
+			return t;
+	}
+}
+
 /*
  * Document-class: PG::BinaryDecoder::String < PG::SimpleDecoder
  *
@@ -156,6 +217,8 @@ init_pg_binary_decoder()
 	pg_define_coder( "String", pg_text_dec_string, rb_cPG_SimpleDecoder, rb_mPG_BinaryDecoder );
 	/* dummy = rb_define_class_under( rb_mPG_BinaryDecoder, "Bytea", rb_cPG_SimpleDecoder ); */
 	pg_define_coder( "Bytea", pg_bin_dec_bytea, rb_cPG_SimpleDecoder, rb_mPG_BinaryDecoder );
+	/* dummy = rb_define_class_under( rb_mPG_BinaryDecoder, "Timestamp", rb_cPG_SimpleDecoder ); */
+	pg_define_coder( "Timestamp", pg_bin_dec_timestamp, rb_cPG_SimpleDecoder, rb_mPG_BinaryDecoder );
 
 	/* dummy = rb_define_class_under( rb_mPG_BinaryDecoder, "ToBase64", rb_cPG_CompositeDecoder ); */
 	pg_define_coder( "ToBase64", pg_bin_dec_to_base64, rb_cPG_CompositeDecoder, rb_mPG_BinaryDecoder );

data/ext/pg_binary_encoder.c

@@ -1,6 +1,6 @@
 /*
  * pg_column_map.c - PG::ColumnMap class extension
- * $Id: pg_binary_encoder.c,v e61a06f1f5ed 2015/12/25 21:14:21 lars $
+ * $Id$
  *
  */
 

data/ext/pg_coder.c

@@ -38,6 +38,7 @@ pg_coder_init_encoder( VALUE self )
 	this->coder_obj = self;
 	this->oid = 0;
 	this->format = 0;
+	this->flags = 0;
 	rb_iv_set( self, "@name", Qnil );
 }
 
@@ -56,6 +57,7 @@ pg_coder_init_decoder( VALUE self )
 	this->coder_obj = self;
 	this->oid = 0;
 	this->format = 0;
+	this->flags = 0;
 	rb_iv_set( self, "@name", Qnil );
 }
 
@@ -192,7 +194,11 @@ pg_coder_decode(int argc, VALUE *argv, VALUE self)
 	if( NIL_P(argv[0]) )
 		return Qnil;
 
-	val = StringValuePtr(argv[0]);
+	if( this->format == 0 ){
+		val = StringValueCStr(argv[0]);
+	}else{
+		val = StringValuePtr(argv[0]);
+	}
 	if( !this->dec_func ){
 		rb_raise(rb_eRuntimeError, "no decoder function defined");
 	}
@@ -265,6 +271,36 @@ pg_coder_format_get(VALUE self)
 	return INT2NUM(this->format);
 }
 
+/*
+ * call-seq:
+ *    coder.flags = Integer
+ *
+ * Set coder specific bitwise OR-ed flags.
+ * See the particular en- or decoder description for available flags.
+ *
+ * The default is +0+.
+ */
+static VALUE
+pg_coder_flags_set(VALUE self, VALUE flags)
+{
+	t_pg_coder *this = DATA_PTR(self);
+	this->flags = NUM2INT(flags);
+	return flags;
+}
+
+/*
+ * call-seq:
+ *    coder.flags -> Integer
+ *
+ * Get current bitwise OR-ed coder flags.
+ */
+static VALUE
+pg_coder_flags_get(VALUE self)
+{
+	t_pg_coder *this = DATA_PTR(self);
+	return INT2NUM(this->flags);
+}
+
 /*
  * call-seq:
  *    coder.needs_quotation = Boolean
@@ -403,14 +439,14 @@ pg_coder_enc_func(t_pg_coder *this)
 }
 
 static VALUE
-pg_text_dec_in_ruby(t_pg_coder *this, char *val, int len, int tuple, int field, int enc_idx)
+pg_text_dec_in_ruby(t_pg_coder *this, const char *val, int len, int tuple, int field, int enc_idx)
 {
 	VALUE string = pg_text_dec_string(this, val, len, tuple, field, enc_idx);
 	return rb_funcall( this->coder_obj, s_id_decode, 3, string, INT2NUM(tuple), INT2NUM(field) );
 }
 
 static VALUE
-pg_bin_dec_in_ruby(t_pg_coder *this, char *val, int len, int tuple, int field, int enc_idx)
+pg_bin_dec_in_ruby(t_pg_coder *this, const char *val, int len, int tuple, int field, int enc_idx)
 {
 	VALUE string = pg_bin_dec_bytea(this, val, len, tuple, field, enc_idx);
 	return rb_funcall( this->coder_obj, s_id_decode, 3, string, INT2NUM(tuple), INT2NUM(field) );
@@ -457,6 +493,19 @@ init_pg_coder()
 	rb_define_method( rb_cPG_Coder, "oid", pg_coder_oid_get, 0 );
 	rb_define_method( rb_cPG_Coder, "format=", pg_coder_format_set, 1 );
 	rb_define_method( rb_cPG_Coder, "format", pg_coder_format_get, 0 );
+	rb_define_method( rb_cPG_Coder, "flags=", pg_coder_flags_set, 1 );
+	rb_define_method( rb_cPG_Coder, "flags", pg_coder_flags_get, 0 );
+
+	/* define flags to be used with PG::Coder#flags= */
+	rb_define_const( rb_cPG_Coder, "TIMESTAMP_DB_UTC", INT2NUM(PG_CODER_TIMESTAMP_DB_UTC));
+	rb_define_const( rb_cPG_Coder, "TIMESTAMP_DB_LOCAL", INT2NUM(PG_CODER_TIMESTAMP_DB_LOCAL));
+	rb_define_const( rb_cPG_Coder, "TIMESTAMP_APP_UTC", INT2NUM(PG_CODER_TIMESTAMP_APP_UTC));
+	rb_define_const( rb_cPG_Coder, "TIMESTAMP_APP_LOCAL", INT2NUM(PG_CODER_TIMESTAMP_APP_LOCAL));
+	rb_define_const( rb_cPG_Coder, "FORMAT_ERROR_MASK", INT2NUM(PG_CODER_FORMAT_ERROR_MASK));
+	rb_define_const( rb_cPG_Coder, "FORMAT_ERROR_TO_RAISE", INT2NUM(PG_CODER_FORMAT_ERROR_TO_RAISE));
+	rb_define_const( rb_cPG_Coder, "FORMAT_ERROR_TO_STRING", INT2NUM(PG_CODER_FORMAT_ERROR_TO_STRING));
+	rb_define_const( rb_cPG_Coder, "FORMAT_ERROR_TO_PARTIAL", INT2NUM(PG_CODER_FORMAT_ERROR_TO_PARTIAL));
+
 	/*
 	 * Name of the coder or the corresponding data type.
 	 *