pg 0.18.2 → 1.4.5

data/README.rdoc

@@ -1,15 +1,17 @@
 = 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
+clog :: link:/History.rdoc
+
+{<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.3 and later}[http://www.postgresql.org/support/versioning/].
 
 A small example usage:
 
@@ -21,26 +23,38 @@ 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')
+        row.values_at('pid', 'usename', 'query')
     end
   end
 
 == 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://github.com/ged/ruby-pg/actions/workflows/source-gem.yml/badge.svg?branch=master" alt="Build Status Github Actions" />}[https://github.com/ged/ruby-pg/actions/workflows/source-gem.yml]
+{<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]
+{<img src="https://app.travis-ci.com/larskanis/ruby-pg.svg?branch=master" alt="Build Status" />}[https://app.travis-ci.com/larskanis/ruby-pg]
 
 == Requirements
 
-* Ruby 1.9.3-p392, or 2.0.0-p0.
-* PostgreSQL 8.4.x or later (with headers, -dev packages, etc).
+* Ruby 2.4 or newer
+* PostgreSQL 9.3.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,6 +77,10 @@ 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
 
@@ -100,6 +118,30 @@ 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.
@@ -109,20 +151,51 @@ 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:
+After checking out the source, install all dependencies:
 
-    $ rake newb
+    $ bundle install
 
-This task will install any missing dependencies, run the tests/specs, and
-generate the API documentation.
+Cleanup extension files, packaging files, test databases:
+
+    $ rake clean
+
+Compile extension:
+
+    $ rake compile
+
+Run tests/specs with PostgreSQL tools like `initdb` in the path:
+
+    $ PATH=$PATH:/usr/lib/postgresql/14/bin rake test
+
+Or run a specific test with the line number:
+
+    $ PATH=$PATH:/usr/lib/postgresql/14/bin rspec -Ilib -fd spec/pg/connection_spec.rb:455
+
+Generate the API documentation:
+
+    $ rake docs
+
+Make sure, that all bugs and new features are verified by tests.
 
 The current maintainers are Michael Granger <ged@FaerieMUD.org> and
 Lars Kanis <lars@greiz-reinsdorf.de>.
@@ -130,7 +203,7 @@ Lars Kanis <lars@greiz-reinsdorf.de>.
 
 == Copying
 
-Copyright (c) 1997-2015 by the authors.
+Copyright (c) 1997-2022 by the authors.
 
 * Jeff Davis <ruby-pg@j-davis.com>
 * Guy Decoux (ts) <decoux@moulon.inra.fr>
@@ -142,7 +215,7 @@ Copyright (c) 1997-2015 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
@@ -158,4 +231,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,22 +1,13 @@
-#!/usr/bin/env rake
+# -*- rake -*-
 
 require 'rbconfig'
 require 'pathname'
 require 'tmpdir'
-
-begin
-	require 'rake/extensiontask'
-rescue LoadError
-	abort "This Rakefile requires rake-compiler (gem install rake-compiler)"
-end
-
-begin
-	require 'hoe'
-rescue LoadError
-	abort "This Rakefile requires hoe (gem install hoe)"
-end
-
+require 'rake/extensiontask'
 require 'rake/clean'
+require 'rspec/core/rake_task'
+require 'bundler'
+require 'bundler/gem_helper'
 
 # Build directory constants
 BASEDIR = Pathname( __FILE__ ).dirname
@@ -25,102 +16,38 @@ LIBDIR  = BASEDIR + 'lib'
 EXTDIR  = BASEDIR + 'ext'
 PKGDIR  = BASEDIR + 'pkg'
 TMPDIR  = BASEDIR + 'tmp'
+TESTDIR = BASEDIR + "tmp_test_*"
 
 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( TESTDIR.to_s )
 CLEAN.include( PKGDIR.to_s, TMPDIR.to_s )
-
-# Set up Hoe plugins
-Hoe.plugin :mercurial
-Hoe.plugin :signing
-Hoe.plugin :deveiate
-Hoe.plugin :bundler
-
-Hoe.plugins.delete :rubyforge
-Hoe.plugins.delete :compiler
+CLEAN.include "lib/*/libpq.dll"
+CLEAN.include "lib/pg_ext.*"
+CLEAN.include "lib/pg/postgresql_lib_path.rb"
 
 load 'Rakefile.cross'
 
-
-# Hoe specification
-$hoespec = Hoe.spec 'pg' do
-	self.readme_file = 'README.rdoc'
-	self.history_file = 'History.rdoc'
-	self.extra_rdoc_files = Rake::FileList[ '*.rdoc' ]
-	self.extra_rdoc_files.include( 'POSTGRES', 'LICENSE' )
-	self.extra_rdoc_files.include( 'ext/*.c' )
-	self.license :BSD
-
-	self.developer 'Michael Granger', 'ged@FaerieMUD.org'
-	self.developer 'Lars Kanis', 'lars@greiz-reinsdorf.de'
-
-	self.dependency 'rake-compiler', '~> 0.9', :developer
-	self.dependency 'hoe', '~> 3.12', :developer
-	self.dependency 'hoe-deveiate', '~> 0.6', :developer
-	self.dependency 'hoe-bundler', '~> 1.0', :developer
-	self.dependency 'rspec', '~> 3.0', :developer
-
-	self.spec_extras[:licenses] = ['BSD', 'Ruby', 'GPL']
-	self.spec_extras[:extensions] = [ 'ext/extconf.rb' ]
-
-	self.require_ruby_version( '>= 1.9.3' )
-
-	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
-
-ENV['VERSION'] ||= $hoespec.spec.version.to_s
-
-# Tests should pass before checking in
-task 'hg:precheckin' => [ :check_history, :check_manifest, :spec ]
-
-# Support for 'rvm specs'
-task :specs => :spec
-
-# Compile before testing
-task :spec => :compile
-
-# gem-testers support
-task :test do
-	# rake-compiler always wants to copy the compiled extension into lib/, but
-	# we don't want testers to have to re-compile, especially since that
-	# often fails because they can't (and shouldn't have to) write to tmp/ in
-	# 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[ :spec ].execute
-end
+Bundler::GemHelper.install_tasks
+$gem_spec = Bundler.load_gemspec(GEMSPEC)
 
 desc "Turn on warnings and debugging in the build."
 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'
-	ext.gem_spec       = $hoespec.spec
+	ext.gem_spec       = $gem_spec
 	ext.ext_dir        = 'ext'
 	ext.lib_dir        = 'lib'
 	ext.source_pattern = "*.{c,h}"
 	ext.cross_compile  = true
-	ext.cross_platform = CrossLibraries.map &:for_platform
+	ext.cross_platform = CrossLibraries.map(&:for_platform)
 
 	ext.cross_config_options += CrossLibraries.map do |lib|
 		{
@@ -136,52 +63,40 @@ Rake::ExtensionTask.new do |ext|
 
 	# Add libpq.dll to windows binary gemspec
 	ext.cross_compiling do |spec|
-		# mingw32-platform strings differ (RUBY_PLATFORM=i386-mingw32 vs. x86-mingw32 for rubygems)
-		spec.files << "lib/#{spec.platform.to_s.gsub(/^x86-/, "i386-")}/libpq.dll"
+		spec.files << "lib/#{spec.platform}/libpq.dll"
 	end
 end
 
+RSpec::Core::RakeTask.new(:spec).rspec_opts = "--profile -cfdoc"
+task :test => :spec
 
-# Make the ChangeLog update if the repo has changed since it was last built
-file '.hg/branch' do
-	warn "WARNING: You need the Mercurial repo to update the ChangeLog"
-end
-file 'ChangeLog' do |task|
-	if File.exist?('.hg/branch')
-		$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 )
-		end
-	else
-		touch 'ChangeLog'
-	end
-end
+# Use the fivefish formatter for docs generated from development checkout
+require 'rdoc/task'
 
-# Rebuild the ChangeLog immediately before release
-task :prerelease => 'ChangeLog'
+RDoc::Task.new( 'docs' ) do |rdoc|
+	rdoc.main = "README.rdoc"
+	rdoc.rdoc_files.include( "*.rdoc", "lib/**/*.rb", 'ext/**/*.{c,h}' )
+	rdoc.generator = :fivefish
+	rdoc.title = "PG: The Ruby PostgreSQL Driver"
+	rdoc.rdoc_dir = 'doc'
+end
 
+desc "Build the source gem #{$gem_spec.full_name}.gem into the pkg directory"
+task :gem => :build
 
-desc "Stop any Postmaster instances that remain after testing."
-task :cleanup_testing_dbs do
-    require 'spec/lib/helpers'
-    PgTestingHelpers.stop_existing_postmasters()
-    Rake::Task[:clean].invoke
+task :clobber do
+	puts "Stop any Postmaster instances that remain after testing."
+	require_relative 'spec/helpers'
+	PG::TestingHelpers.stop_existing_postmasters()
 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=HEAD"
+	URL_ERRORCODES_TXT = "http://git.postgresql.org/gitweb/?p=postgresql.git;a=blob_plain;f=src/backend/utils/errcodes.txt;hb=refs/tags/REL_15_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}"
-end
 
-file 'ext/errorcodes.def' => ['ext/errorcodes.rb', 'ext/errorcodes.txt'] do
 	ruby 'ext/errorcodes.rb', 'ext/errorcodes.txt', 'ext/errorcodes.def'
 end
 
@@ -189,18 +104,3 @@ 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.version = "#{spec.version}.pre#{Time.now.strftime("%Y%m%d%H%M%S")}"
-	File.open( task.name, 'w' ) do |fh|
-		fh.write( spec.to_ruby )
-	end
-end
-
-CLOBBER.include( GEMSPEC.to_s )
-task :default => :gemspec
-