pg 0.15.1 → 1.2.3

data/README-Windows.rdoc

@@ -2,9 +2,9 @@
 
 In order to build this extension on MS Windows you will need a couple things.
 
-First, a compiler. For the one click installer this means you should either
-use VC++ 6.0 or the compiler that comes with cygwin or mingw if you're
-building on that platform.
+First, a compiler. For the one click installer this means you should use
+the DevKit or the compiler that comes with cygwin if you're building on that
+platform.
 
 If you've built Ruby yourself, you should use the same compiler to build
 this library that you used to build Ruby.
@@ -29,39 +29,28 @@ Adjust your path accordingly. BE SURE TO USE THE SHORT PATH NAMES! If you
 try to use a path with spaces in it, the nmake.exe program will choke.
 
 
-== Cross compiling for mswin32
+== Building binary 'pg' gems for MS Windows
 
-Using rake-compiler a cross compiled pg gem can be build on a Linux or MacOS X
-host for the win32 platform. The generated gem is statically linked against
-libpq and libssl. OpenSSL and PostgreSQL are downloaded and compiled from the
-sources. There are no runtime dependencies to any but the standard Windows
-DLLs.
+Binary gems for windows can be built on Linux, OS-X and even on Windows
+with the help of docker. This is how regular windows gems are built for
+rubygems.org .
 
-Install mingw32 using the instructions in rake-compiler's README.
-For Debian/Ubuntu it is <tt>apt-get install gcc-mingw32</tt> .
-Use ruby-1.8.7 for the following commands.
+To do this, install boot2docker {on Windows}[https://github.com/boot2docker/windows-installer/releases]
+or {on OS X}[https://github.com/boot2docker/osx-installer/releases] and make
+sure it is started. A native Docker installation is best on Linux.
 
-Download and cross compile ruby 1.8 and 1.9 for win32 with:
+Then run:
 
-	rake-compiler cross-ruby VERSION=1.8.7-p352
-	rake-compiler cross-ruby VERSION=1.9.2-p290
+	rake gem:windows
 
-Download and cross compile pg for win32:
-
-	rake cross native gem
-
-or with custom versions:
-
-	rake cross native gem RUBY_CC_VERSION=1.8.7:1.9.2 \
-	    OPENSSL_VERSION=1.0.0e POSTGRESQL_VERSION=9.1.1
-
-If everything works, there should be pg-VERSION-x86-mingw32.gem in the pkg
-directory.
+This will download a docker image suited for building windows gems, and it
+will download and build OpenSSL and PostgreSQL. Finally the gem is built
+containing binaries for all supported ruby versions.
 
 
 == Reporting Problems
 
-If you have any problems you can submit them via
-[the project's issue-tracker][bitbucket]. And submit questions, problems, or
+If you have any problems you can submit them via {the project's
+issue-tracker}[https://github.com/ged/ruby-pg/issues]. And submit questions, problems, or
 solutions, so that it can be improved.
 

data/README.ja.rdoc

@@ -1,7 +1,6 @@
 = pg
 
-home :: https://bitbucket.org/ged/ruby-pg
-mirror :: https://github.com/ged/ruby-pg
+home :: https://github.com/ged/ruby-pg
 docs :: http://deveiate.org/code/pg
 
 

data/README.rdoc

@@ -1,15 +1,16 @@
 = pg
 
-home :: https://bitbucket.org/ged/ruby-pg
-mirror :: https://github.com/ged/ruby-pg
+home :: https://github.com/ged/ruby-pg
 docs :: http://deveiate.org/code/pg
 
+{<img src="https://badges.gitter.im/Join%20Chat.svg" alt="Join the chat at https://gitter.im/ged/ruby-pg">}[https://gitter.im/ged/ruby-pg?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge]
+
 
 == Description
 
 Pg is the Ruby interface to the {PostgreSQL RDBMS}[http://www.postgresql.org/].
 
-It works with {PostgreSQL 8.4 and later}[http://www.postgresql.org/support/versioning/].
+It works with {PostgreSQL 9.2 and later}[http://www.postgresql.org/support/versioning/].
 
 A small example usage:
 
@@ -21,7 +22,7 @@ A small example usage:
   conn = PG.connect( dbname: 'sales' )
   conn.exec( "SELECT * FROM pg_stat_activity" ) do |result|
     puts "     PID | User             | Query"
-  result.each do |row|
+    result.each do |row|
       puts " %7d | %-16s | %s " %
         row.values_at('procpid', 'usename', 'current_query')
     end
@@ -29,18 +30,30 @@ A small example usage:
 
 == Build Status
 
-{<img src="https://travis-ci.org/ged/ruby-pg.png?branch=master" alt="Build Status" />}[https://travis-ci.org/ged/ruby-pg]
+{<img src="https://travis-ci.org/ged/ruby-pg.svg?branch=master" alt="Build Status Travis-CI" />}[https://travis-ci.org/ged/ruby-pg]
+{<img src="https://ci.appveyor.com/api/projects/status/gjx5axouf3b1wicp?svg=true" alt="Build Status Appveyor" />}[https://ci.appveyor.com/project/ged/ruby-pg-9j8l3]
 
 
 == Requirements
 
-* Ruby 1.9.3-p392, or 2.0.0-p0.
-* PostgreSQL 8.4.x or later (with headers, -dev packages, etc).
+* Ruby 2.2 or newer
+* PostgreSQL 9.2.x or later (with headers, -dev packages, etc).
 
-It may work with earlier versions of Ruby/PostgreSQL as well, but those are
+It usually works 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:
@@ -63,12 +76,99 @@ There's also {a Google+ group}[http://goo.gl/TFy1U] and a
 {mailing list}[http://groups.google.com/group/ruby-pg] if you get stuck, or just
 want to chat about something.
 
+If you want to install as a signed gem, the public certs of the gem signers
+can be found in {the `certs` directory}[https://github.com/ged/ruby-pg/tree/master/certs]
+of the repository.
+
+
+== Type Casts
+
+Pg can optionally type cast result values and query parameters in Ruby or
+native C code. This can speed up data transfers to and from the database,
+because String allocations are reduced and conversions in (slower) Ruby code
+can be omitted.
+
+Very basic type casting can be enabled by:
+
+    conn.type_map_for_results = PG::BasicTypeMapForResults.new conn
+    # ... this works for result value mapping:
+    conn.exec("select 1, now(), '{2,3}'::int[]").values
+        # => [[1, 2014-09-21 20:51:56 +0200, [2, 3]]]
+
+    conn.type_map_for_queries = PG::BasicTypeMapForQueries.new conn
+    # ... and this for param value mapping:
+    conn.exec_params("SELECT $1::text, $2::text, $3::text", [1, 1.23, [2,3]]).values
+        # => [["1", "1.2300000000000000E+00", "{2,3}"]]
+
+But Pg's type casting is highly customizable. That's why it's divided into
+2 layers:
+
+=== Encoders / Decoders (ext/pg_*coder.c, lib/pg/*coder.rb)
+
+This is the lower layer, containing encoding classes that convert Ruby
+objects for transmission to the DBMS and decoding classes to convert
+received data back to Ruby objects. The classes are namespaced according
+to their format and direction in PG::TextEncoder, PG::TextDecoder,
+PG::BinaryEncoder and PG::BinaryDecoder.
+
+It is possible to assign a type OID, format code (text or binary) and
+optionally a name to an encoder or decoder object. It's also possible
+to build composite types by assigning an element encoder/decoder.
+PG::Coder objects can be used to set up a PG::TypeMap or alternatively
+to convert single values to/from their string representation.
+
+The following PostgreSQL column types are supported by ruby-pg (TE = Text Encoder, TD = Text Decoder, BE = Binary Encoder, BD = Binary Decoder):
+* Integer: {TE}[rdoc-ref:PG::TextEncoder::Integer], {TD}[rdoc-ref:PG::TextDecoder::Integer], {BD}[rdoc-ref:PG::BinaryDecoder::Integer] 💡 No links? Switch to {here}[https://deveiate.org/code/pg/README_rdoc.html#label-Type+Casts] 💡
+  * BE: {Int2}[rdoc-ref:PG::BinaryEncoder::Int2], {Int4}[rdoc-ref:PG::BinaryEncoder::Int4], {Int8}[rdoc-ref:PG::BinaryEncoder::Int8]
+* Float: {TE}[rdoc-ref:PG::TextEncoder::Float], {TD}[rdoc-ref:PG::TextDecoder::Float], {BD}[rdoc-ref:PG::BinaryDecoder::Float]
+* Numeric: {TE}[rdoc-ref:PG::TextEncoder::Numeric], {TD}[rdoc-ref:PG::TextDecoder::Numeric]
+* Boolean: {TE}[rdoc-ref:PG::TextEncoder::Boolean], {TD}[rdoc-ref:PG::TextDecoder::Boolean], {BE}[rdoc-ref:PG::BinaryEncoder::Boolean], {BD}[rdoc-ref:PG::BinaryDecoder::Boolean]
+* String: {TE}[rdoc-ref:PG::TextEncoder::String], {TD}[rdoc-ref:PG::TextDecoder::String], {BE}[rdoc-ref:PG::BinaryEncoder::String], {BD}[rdoc-ref:PG::BinaryDecoder::String]
+* Bytea: {TE}[rdoc-ref:PG::TextEncoder::Bytea], {TD}[rdoc-ref:PG::TextDecoder::Bytea], {BE}[rdoc-ref:PG::BinaryEncoder::Bytea], {BD}[rdoc-ref:PG::BinaryDecoder::Bytea]
+* Base64: {TE}[rdoc-ref:PG::TextEncoder::ToBase64], {TD}[rdoc-ref:PG::TextDecoder::FromBase64], {BE}[rdoc-ref:PG::BinaryEncoder::FromBase64], {BD}[rdoc-ref:PG::BinaryDecoder::ToBase64]
+* Timestamp:
+  * TE: {local}[rdoc-ref:PG::TextEncoder::TimestampWithoutTimeZone], {UTC}[rdoc-ref:PG::TextEncoder::TimestampUtc], {with-TZ}[rdoc-ref:PG::TextEncoder::TimestampWithTimeZone]
+  * TD: {local}[rdoc-ref:PG::TextDecoder::TimestampLocal], {UTC}[rdoc-ref:PG::TextDecoder::TimestampUtc], {UTC-to-local}[rdoc-ref:PG::TextDecoder::TimestampUtcToLocal]
+  * BD: {local}[rdoc-ref:PG::BinaryDecoder::TimestampLocal], {UTC}[rdoc-ref:PG::BinaryDecoder::TimestampUtc], {UTC-to-local}[rdoc-ref:PG::BinaryDecoder::TimestampUtcToLocal]
+* Date: {TE}[rdoc-ref:PG::TextEncoder::Date], {TD}[rdoc-ref:PG::TextDecoder::Date]
+* JSON and JSONB: {TE}[rdoc-ref:PG::TextEncoder::JSON], {TD}[rdoc-ref:PG::TextDecoder::JSON]
+* Inet: {TE}[rdoc-ref:PG::TextEncoder::Inet], {TD}[rdoc-ref:PG::TextDecoder::Inet]
+* Array: {TE}[rdoc-ref:PG::TextEncoder::Array], {TD}[rdoc-ref:PG::TextDecoder::Array]
+* Composite Type (also called "Row" or "Record"): {TE}[rdoc-ref:PG::TextEncoder::Record], {TD}[rdoc-ref:PG::TextDecoder::Record]
+
+The following text formats can also be encoded although they are not used as column type:
+* COPY input and output data: {TE}[rdoc-ref:PG::TextEncoder::CopyRow], {TD}[rdoc-ref:PG::TextDecoder::CopyRow]
+* Literal for insertion into SQL string: {TE}[rdoc-ref:PG::TextEncoder::QuotedLiteral]
+* SQL-Identifier: {TE}[rdoc-ref:PG::TextEncoder::Identifier], {TD}[rdoc-ref:PG::TextDecoder::Identifier]
+
+=== PG::TypeMap and derivations (ext/pg_type_map*.c, lib/pg/type_map*.rb)
+
+A TypeMap defines which value will be converted by which encoder/decoder.
+There are different type map strategies, implemented by several derivations
+of this class. They can be chosen and configured according to the particular
+needs for type casting. The default type map is PG::TypeMapAllStrings.
+
+A type map can be assigned per connection or per query respectively per
+result set. Type maps can also be used for COPY in and out data streaming.
+See PG::Connection#copy_data .
+
+The following base type maps are available:
+* PG::TypeMapAllStrings - encodes and decodes all values to and from strings (default)
+* PG::TypeMapByClass - selects encoder based on the class of the value to be sent
+* PG::TypeMapByColumn - selects encoder and decoder by column order
+* PG::TypeMapByOid - selects decoder by PostgreSQL type OID
+* PG::TypeMapInRuby - define a custom type map in ruby
+
+The following type maps are prefilled with type mappings from the PG::BasicTypeRegistry :
+* PG::BasicTypeMapForResults - a PG::TypeMapByOid prefilled with decoders for common PostgreSQL column types
+* PG::BasicTypeMapBasedOnResult - a PG::TypeMapByOid prefilled with encoders for common PostgreSQL column types
+* PG::BasicTypeMapForQueries - a PG::TypeMapByClass prefilled with encoders for common Ruby value classes
+
 
 == Contributing
 
-To report bugs, suggest features, or check out the source with Mercurial,
-{check out the project page}[http://bitbucket.org/ged/ruby-pg]. If you prefer
-Git, there's also a {Github mirror}[https://github.com/ged/ruby-pg].
+To report bugs, suggest features, or check out the source with Git,
+{check out the project page}[https://github.com/ged/ruby-pg].
 
 After checking out the source, run:
 
@@ -83,7 +183,7 @@ Lars Kanis <lars@greiz-reinsdorf.de>.
 
 == Copying
 
-Copyright (c) 1997-2013 by the authors.
+Copyright (c) 1997-2019 by the authors.
 
 * Jeff Davis <ruby-pg@j-davis.com>
 * Guy Decoux (ts) <decoux@moulon.inra.fr>
@@ -95,7 +195,7 @@ Copyright (c) 1997-2013 by the authors.
 * Noboru Saitou <noborus@netlab.jp>
 
 You may redistribute this software under the same terms as Ruby itself; see
-http://www.ruby-lang.org/en/LICENSE.txt or the LICENSE file in the source
+https://www.ruby-lang.org/en/about/license.txt or the BSDL file in the source
 for details.
 
 Portions of the code are from the PostgreSQL project, and are distributed
@@ -111,4 +211,3 @@ to this library over the years.
 
 We are thankful to the people at the ruby-list and ruby-dev mailing lists.
 And to the people who developed PostgreSQL.
-

data/Rakefile

@@ -1,4 +1,4 @@
-#!/usr/bin/env rake
+# -*- rake -*-
 
 require 'rbconfig'
 require 'pathname'
@@ -29,15 +29,20 @@ TMPDIR  = BASEDIR + 'tmp'
 DLEXT   = RbConfig::CONFIG['DLEXT']
 EXT     = LIBDIR + "pg_ext.#{DLEXT}"
 
+GEMSPEC = 'pg.gemspec'
+
 TEST_DIRECTORY = BASEDIR + "tmp_test_specs"
 
 CLOBBER.include( TEST_DIRECTORY.to_s )
 CLEAN.include( PKGDIR.to_s, TMPDIR.to_s )
+CLEAN.include "lib/*/libpq.dll"
+CLEAN.include "lib/pg_ext.*"
 
 # Set up Hoe plugins
 Hoe.plugin :mercurial
 Hoe.plugin :signing
 Hoe.plugin :deveiate
+Hoe.plugin :bundler
 
 Hoe.plugins.delete :rubyforge
 Hoe.plugins.delete :compiler
@@ -52,24 +57,24 @@ $hoespec = Hoe.spec 'pg' do
 	self.extra_rdoc_files = Rake::FileList[ '*.rdoc' ]
 	self.extra_rdoc_files.include( 'POSTGRES', 'LICENSE' )
 	self.extra_rdoc_files.include( 'ext/*.c' )
+	self.license 'BSD-2-Clause'
 
 	self.developer 'Michael Granger', 'ged@FaerieMUD.org'
+	self.developer 'Lars Kanis', 'lars@greiz-reinsdorf.de'
 
-	self.dependency 'rake-compiler', '~> 0.8', :developer
-	self.dependency	'hoe-deveiate', '~> 0.2', :developer
+	self.dependency 'rake-compiler', '~> 1.0', :developer
+	self.dependency 'rake-compiler-dock', ['~> 1.0'], :developer
+	self.dependency 'hoe-deveiate', '~> 0.9', :developer
+	self.dependency 'hoe-bundler', '~> 1.0', :developer
+	self.dependency 'rspec', '~> 3.5', :developer
+	self.dependency 'rdoc', '~> 5.1', :developer
 
-	self.spec_extras[:licenses] = ['BSD', 'Ruby', 'GPL']
 	self.spec_extras[:extensions] = [ 'ext/extconf.rb' ]
 
-	self.require_ruby_version( '>= 1.8.7' )
+	self.require_ruby_version( '>= 2.2' )
 
 	self.hg_sign_tags = true if self.respond_to?( :hg_sign_tags= )
 	self.check_history_on_release = true if self.respond_to?( :check_history_on_release= )
-	self.spec_extras[:rdoc_options] = [
-		'-f', 'fivefish',
-		'-t', 'pg: The Ruby Interface to PostgreSQL',
-		'-m', 'README.rdoc',
-	]
 
 	self.rdoc_locations << "deveiate:/usr/local/www/public/code/#{remote_rdoc_dir}"
 end
@@ -77,7 +82,7 @@ end
 ENV['VERSION'] ||= $hoespec.spec.version.to_s
 
 # Tests should pass before checking in
-task 'hg:precheckin' => [ :check_history, :check_manifest, :spec ]
+task 'hg:precheckin' => [ :check_history, :check_manifest, :spec, :gemspec ]
 
 # Support for 'rvm specs'
 task :specs => :spec
@@ -93,7 +98,7 @@ task :test do
 	# the installed gem dir. So we clear the task rake-compiler set up
 	# to break the dependency between :spec and :compile when running under
 	# rubygems-test, and then run :spec.
-	Rake::Task[ EXT.to_s ].clear
+	Rake::Task[ EXT.to_s ].clear if File.exist?(EXT.to_s)
 	Rake::Task[ :spec ].execute
 end
 
@@ -102,8 +107,6 @@ task :maint do
 	ENV['MAINTAINER_MODE'] = 'yes'
 end
 
-ENV['RUBY_CC_VERSION'] ||= '1.8.7:1.9.2:2.0.0'
-
 # Rake-compiler task
 Rake::ExtensionTask.new do |ext|
 	ext.name           = 'pg_ext'
@@ -112,34 +115,61 @@ Rake::ExtensionTask.new do |ext|
 	ext.lib_dir        = 'lib'
 	ext.source_pattern = "*.{c,h}"
 	ext.cross_compile  = true
-	ext.cross_platform = CrossLibraries.map &:for_platform
-
-  ext.cross_config_options += CrossLibraries.map do |lib|
-    {
-      lib.for_platform => [
-        "--with-pg-include=#{lib.static_postgresql_libdir}",
-        "--with-opt-include=#{lib.static_postgresql_incdir}",
-        "--with-pg-lib=#{lib.static_postgresql_libdir}",
-        "--with-opt-lib=#{lib.static_openssl_builddir}",
-      ]
-    }
-  end
+	ext.cross_platform = CrossLibraries.map(&:for_platform)
+
+	ext.cross_config_options += CrossLibraries.map do |lib|
+		{
+			lib.for_platform => [
+				"--enable-windows-cross",
+				"--with-pg-include=#{lib.static_postgresql_incdir}",
+				"--with-pg-lib=#{lib.static_postgresql_libdir}",
+				# libpq-fe.h resides in src/interfaces/libpq/ before make install
+				"--with-opt-include=#{lib.static_postgresql_libdir}",
+			]
+		}
+	end
+
+	# Add libpq.dll to windows binary gemspec
+	ext.cross_compiling do |spec|
+		spec.files << "lib/#{spec.platform}/libpq.dll"
+	end
+end
+
+
+# Use the fivefish formatter for docs generated from development checkout
+if File.directory?( '.hg' )
+	require 'rdoc/task'
+
+	Rake::Task[ 'docs' ].clear
+	RDoc::Task.new( 'docs' ) do |rdoc|
+		rdoc.main = "README.rdoc"
+		rdoc.rdoc_files.include( "*.rdoc", "ChangeLog", "lib/**/*.rb", 'ext/**/*.{c,h}' )
+		rdoc.generator = :fivefish
+		rdoc.title = "PG: The Ruby PostgreSQL Driver"
+		rdoc.rdoc_dir = 'doc'
+	end
 end
 
 
 # Make the ChangeLog update if the repo has changed since it was last built
 file '.hg/branch' do
-	abort "You need the Mercurial repo to make packages"
+	warn "WARNING: You need the Mercurial repo to update the ChangeLog"
 end
-file 'ChangeLog' => '.hg/branch' do |task|
-	$stderr.puts "Updating the changelog..."
-	begin
-		content = make_changelog()
-	rescue NameError
-		abort "Packaging tasks require the hoe-mercurial plugin (gem install hoe-mercurial)"
-	end
-	File.open( task.name, 'w', 0644 ) do |fh|
-		fh.print( content )
+Rake::Task["ChangeLog"].clear
+file 'ChangeLog' do |task|
+	if File.exist?('.hg/branch')
+		$stderr.puts "Updating the changelog..."
+		begin
+			include Hoe::MercurialHelpers
+			content = make_changelog()
+		rescue NameError
+			abort "Packaging tasks require the hoe-mercurial plugin (gem install hoe-mercurial)"
+		end
+		File.open( task.name, 'w', 0644 ) do |fh|
+			fh.print( content )
+		end
+	else
+		touch 'ChangeLog'
 	end
 end
 
@@ -154,3 +184,34 @@ task :cleanup_testing_dbs do
     Rake::Task[:clean].invoke
 end
 
+desc "Update list of server error codes"
+task :update_error_codes do
+	URL_ERRORCODES_TXT = "http://git.postgresql.org/gitweb/?p=postgresql.git;a=blob_plain;f=src/backend/utils/errcodes.txt;hb=refs/tags/REL_12_0"
+
+	ERRORCODES_TXT = "ext/errorcodes.txt"
+	sh "wget #{URL_ERRORCODES_TXT.inspect} -O #{ERRORCODES_TXT.inspect} || curl #{URL_ERRORCODES_TXT.inspect} -o #{ERRORCODES_TXT.inspect}"
+
+	ruby 'ext/errorcodes.rb', 'ext/errorcodes.txt', 'ext/errorcodes.def'
+end
+
+file 'ext/pg_errors.c' => ['ext/errorcodes.def'] do
+	# trigger compilation of changed errorcodes.def
+	touch 'ext/pg_errors.c'
+end
+
+task :gemspec => GEMSPEC
+file GEMSPEC => __FILE__
+task GEMSPEC do |task|
+	spec = $hoespec.spec
+	spec.files.delete( '.gemtest' )
+	spec.signing_key = nil
+	spec.version = "#{spec.version.bump}.0.pre#{Time.now.strftime("%Y%m%d%H%M%S")}"
+	spec.cert_chain = [ 'certs/ged.pem' ]
+	File.open( task.name, 'w' ) do |fh|
+		fh.write( spec.to_ruby )
+	end
+end
+
+CLOBBER.include( '*.gemspec' )
+task :default => :gemspec
+