pg 0.12.0 → 0.16.0

data/lib/pg/connection.rb

@@ -0,0 +1,86 @@
+#!/usr/bin/env ruby
+
+require 'pg' unless defined?( PG )
+
+# 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
+# application programmer's interface to PostgreSQL. Some familiarity with libpq
+# is recommended, but not necessary.
+#
+# For example, to send query to the database on the localhost:
+#
+#    require 'pg'
+#    conn = PG::Connection.open(:dbname => 'test')
+#    res = conn.exec_params('SELECT $1 AS a, $2 AS b, $3 AS c', [1, 2, nil])
+#    # Equivalent to:
+#    #  res  = conn.exec('SELECT 1 AS a, 2 AS b, NULL AS c')
+#
+# See the PG::Result class for information on working with the results of a query.
+#
+class PG::Connection
+
+	# The order the options are passed to the ::connect method.
+	CONNECT_ARGUMENT_ORDER = %w[host port options tty dbname user password]
+
+
+	### Quote the given +value+ for use in a connection-parameter string.
+	def self::quote_connstr( value )
+		return "'" + value.to_s.gsub( /[\\']/ ) {|m| '\\' + m } + "'"
+	end
+
+
+	### Parse the connection +args+ into a connection-parameter string. See PG::Connection.new
+	### for valid arguments.
+	def self::parse_connect_args( *args )
+		return '' if args.empty?
+
+		# This will be swapped soon for code that makes options like those required for
+		# PQconnectdbParams()/PQconnectStartParams(). For now, stick to an options string for
+		# PQconnectdb()/PQconnectStart().
+
+		# Parameter 'fallback_application_name' was introduced in PostgreSQL 9.0
+		# together with PQescapeLiteral().
+		if PG::Connection.instance_methods.find{|m| m.to_sym == :escape_literal }
+			appname = $0.sub(/^(.{30}).{4,}(.{30})$/){ $1+"..."+$2 }
+			appname = PG::Connection.quote_connstr( appname )
+			connopts = ["fallback_application_name=#{appname}"]
+		else
+			connopts = []
+		end
+
+		# Handle an options hash first
+		if args.last.is_a?( Hash )
+			opthash = args.pop
+			opthash.each do |key, val|
+				connopts.push( "%s=%s" % [key, PG::Connection.quote_connstr(val)] )
+			end
+		end
+
+		# Option string style
+		if args.length == 1 && args.first.to_s.index( '=' )
+			connopts.unshift( args.first )
+
+		# Append positional parameters
+		else
+			args.each_with_index do |val, i|
+				next unless val # Skip nil placeholders
+
+				key = CONNECT_ARGUMENT_ORDER[ i ] or
+					raise ArgumentError, "Extra positional parameter %d: %p" % [ i+1, val ]
+				connopts.push( "%s=%s" % [key, PG::Connection.quote_connstr(val.to_s)] )
+			end
+		end
+
+		return connopts.join(' ')
+	end
+
+
+	# Backward-compatibility aliases for stuff that's moved into PG.
+	class << self
+		define_method( :isthreadsafe, &PG.method(:isthreadsafe) )
+	end
+end # class PG::Connection
+
+# Backward-compatible alias
+PGconn = PG::Connection
+

data/lib/pg/constants.rb

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+
+require 'pg' unless defined?( PG )
+
+
+module PG::Constants
+
+	# Most of these are defined in the extension.
+
+end # module PG::Constants
+

data/lib/pg/exceptions.rb

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+
+require 'pg' unless defined?( PG )
+
+
+module PG
+
+	class Error < StandardError; end
+
+end # module PG
+

data/lib/pg/result.rb

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+
+require 'pg' unless defined?( PG )
+
+
+class PG::Result
+
+	### Returns all tuples as an array of arrays
+	def values
+		return enum_for(:each_row).to_a
+	end
+
+end # class PG::Result
+
+# Backward-compatible alias
+PGresult = PG::Result

data/lib/pg.rb

@@ -14,56 +14,39 @@ rescue LoadError
 
 end
 
-#--
-# The PG connection class.
-class PGconn
 
-	# The order the options are passed to the ::connect method.
-	CONNECT_ARGUMENT_ORDER = %w[host port options tty dbname user password]
+# The top-level PG namespace.
+module PG
 
+	# Library version
+	VERSION = '0.16.0'
 
-	### Quote the given +value+ for use in a connection-parameter string.
-	def self::quote_connstr( value )
-		return "'" + value.to_s.gsub( /[\\']/ ) {|m| '\\' + m } + "'"
+	# VCS revision
+	REVISION = %q$Revision: 4e0606f5f5aa $
+
+
+	### Get the PG library version. If +include_buildnum+ is +true+, include the build ID.
+	def self::version_string( include_buildnum=false )
+		vstring = "%s %s" % [ self.name, VERSION ]
+		vstring << " (build %s)" % [ REVISION[/: ([[:xdigit:]]+)/, 1] || '0' ] if include_buildnum
+		return vstring
 	end
 
 
-	### Parse the connection +args+ into a connection-parameter string. See PGconn.new
-	### for valid arguments.
-	def self::parse_connect_args( *args )
-		return '' if args.empty?
-
-		# This will be swapped soon for code that makes options like those required for
-		# PQconnectdbParams()/PQconnectStartParams(). For now, stick to an options string for
-		# PQconnectdb()/PQconnectStart().
-		connopts = []
-
-		# Handle an options hash first
-		if args.last.is_a?( Hash )
-			opthash = args.pop 
-			opthash.each do |key, val|
-				connopts.push( "%s=%s" % [key, PGconn.quote_connstr(val)] )
-			end
-		end
-
-		# Option string style
-		if args.length == 1 && args.first.to_s.index( '=' )
-			connopts.unshift( args.first )
-
-		# Append positional parameters
-		else
-			args.each_with_index do |val, i|
-				next unless val # Skip nil placeholders
-
-				key = CONNECT_ARGUMENT_ORDER[ i ] or
-					raise ArgumentError, "Extra positional parameter %d: %p" % [ i+1, val ]
-				connopts.push( "%s=%s" % [key, PGconn.quote_connstr(val.to_s)] )
-			end
-		end
-
-		return connopts.join(' ')
+	### Convenience alias for PG::Connection.new.
+	def self::connect( *args )
+		return PG::Connection.new( *args )
 	end
 
-end # class PGconn
 
+	require 'pg/exceptions'
+	require 'pg/constants'
+	require 'pg/connection'
+	require 'pg/result'
+
+end # module PG
+
+
+# Backward-compatible aliase
+PGError = PG::Error
 

data/sample/array_insert.rb

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+
+require 'pg'
+
+c = PG.connect( dbname: 'test' )
+
+# this one works:
+c.exec( "DROP TABLE IF EXISTS foo" )
+c.exec( "CREATE TABLE foo (strings character varying[]);" )
+
+# But using a prepared statement works:
+c.set_error_verbosity( PG::PQERRORS_VERBOSE )
+c.prepare( 'stmt', "INSERT INTO foo VALUES ($1);" )
+
+# This won't work
+#c.exec_prepared( 'stmt', ["ARRAY['this','that']"] )
+
+# but this will:
+c.exec_prepared( 'stmt', ["{'this','that'}"] )
+

data/sample/async_api.rb

@@ -4,20 +4,14 @@ require 'pg'
 
 # This is a example of how to use the asynchronous API to query the
 # server without blocking other threads. It's intentionally low-level;
-# if you hooked up the PGconn#socket to some kind of reactor, you
+# if you hooked up the PG::Connection#socket to some kind of reactor, you
 # could make this much nicer.
 
 TIMEOUT = 5.0 # seconds to wait for an async operation to complete
-CONN_OPTS = {
-	:host     => 'localhost',
-	:dbname   => 'test',
-	:user     => 'jrandom',
-	:password => 'banks!stealUR$',
-}
 
 # Print 'x' continuously to demonstrate that other threads aren't
 # blocked while waiting for the connection, for the query to be sent,
-# for results, etc. You might want to sleep inside the loop or 
+# for results, etc. You might want to sleep inside the loop or
 # comment this out entirely for cleaner output.
 progress_thread = Thread.new { loop { print 'x' } }
 
@@ -28,29 +22,30 @@ end
 
 # Start the connection
 output_progress "Starting connection..."
-conn = PGconn.connect_start( CONN_OPTS ) or abort "Unable to create a new connection!"
+conn = PG::Connection.connect_start( :dbname => 'test' ) or
+	abort "Unable to create a new connection!"
 abort "Connection failed: %s" % [ conn.error_message ] if
-	conn.status == PGconn::CONNECTION_BAD
+	conn.status == PG::CONNECTION_BAD
 
 # Now grab a reference to the underlying socket so we know when the
 # connection is established
-socket = IO.for_fd( conn.socket )
+socket = conn.socket_io
 
 # Track the progress of the connection, waiting for the socket to become readable/writable
 # before polling it
-poll_status = PGconn::PGRES_POLLING_WRITING
-until poll_status == PGconn::PGRES_POLLING_OK ||
-	  poll_status == PGconn::PGRES_POLLING_FAILED
+poll_status = PG::PGRES_POLLING_WRITING
+until poll_status == PG::PGRES_POLLING_OK ||
+	  poll_status == PG::PGRES_POLLING_FAILED
 
 	# If the socket needs to read, wait 'til it becomes readable to poll again
 	case poll_status
-	when PGconn::PGRES_POLLING_READING
+	when PG::PGRES_POLLING_READING
 		output_progress "  waiting for socket to become readable"
 		select( [socket], nil, nil, TIMEOUT ) or
 			raise "Asynchronous connection timed out!"
 
 	# ...and the same for when the socket needs to write
-	when PGconn::PGRES_POLLING_WRITING
+	when PG::PGRES_POLLING_WRITING
 		output_progress "  waiting for socket to become writable"
 		select( nil, [socket], nil, TIMEOUT ) or
 			raise "Asynchronous connection timed out!"
@@ -58,25 +53,27 @@ until poll_status == PGconn::PGRES_POLLING_OK ||
 
 	# Output a status message about the progress
 	case conn.status
-	when PGconn::CONNECTION_STARTED
+	when PG::CONNECTION_STARTED
 		output_progress "  waiting for connection to be made."
-	when PGconn::CONNECTION_MADE
+	when PG::CONNECTION_MADE
 		output_progress "  connection OK; waiting to send."
-	when PGconn::CONNECTION_AWAITING_RESPONSE
+	when PG::CONNECTION_AWAITING_RESPONSE
 		output_progress "  waiting for a response from the server."
-	when PGconn::CONNECTION_AUTH_OK
+	when PG::CONNECTION_AUTH_OK
 		output_progress "  received authentication; waiting for backend start-up to finish."
-	when PGconn::CONNECTION_SSL_STARTUP
+	when PG::CONNECTION_SSL_STARTUP
 		output_progress "  negotiating SSL encryption."
-	when PGconn::CONNECTION_SETENV
+	when PG::CONNECTION_SETENV
 		output_progress "  negotiating environment-driven parameter settings."
+	when PG::CONNECTION_NEEDED
+		output_progress "  internal state: connect() needed."
 	end
 
 	# Check to see if it's finished or failed yet
 	poll_status = conn.connect_poll
 end
 
-abort "Connect failed: %s" % [ conn.error_message ] unless conn.status == PGconn::CONNECTION_OK
+abort "Connect failed: %s" % [ conn.error_message ] unless conn.status == PG::CONNECTION_OK
 
 output_progress "Sending query"
 conn.send_query( "SELECT * FROM pg_stat_activity" )
@@ -85,7 +82,7 @@ conn.send_query( "SELECT * FROM pg_stat_activity" )
 loop do
 	output_progress "  waiting for a response"
 
-	# Buffer any incoming data on the socket until a full result is ready. 
+	# Buffer any incoming data on the socket until a full result is ready.
 	conn.consume_input
 	while conn.is_busy
 		select( [socket], nil, nil, TIMEOUT ) or

data/sample/async_copyto.rb

@@ -6,10 +6,10 @@ require 'stringio'
 # Using COPY asynchronously
 
 $stderr.puts "Opening database connection ..."
-conn = PGconn.connect( :dbname => 'test' )
+conn = PG.connect( :dbname => 'test' )
 conn.setnonblocking( true )
 
-socket = IO.for_fd( conn.socket )
+socket = conn.socket_io
 
 $stderr.puts "Running COPY command ..."
 buf = ''

data/sample/async_mixed.rb

@@ -0,0 +1,56 @@
+#!/usr/bin/env ruby
+
+require 'pg'
+
+$stdout.sync = true
+
+# This is a example of how to mix and match synchronous and async APIs. In this case,
+# the connection to the server is made syncrhonously, and then queries are
+# asynchronous.
+
+TIMEOUT = 5.0 # seconds to wait for an async operation to complete
+CONN_OPTS = {
+	:host     => 'localhost',
+	:dbname   => 'test',
+}
+
+# Output progress messages
+def output_progress( msg )
+	puts ">>> #{msg}\n"
+end
+
+# Start the (synchronous) connection
+output_progress "Starting connection..."
+conn = PG.connect( CONN_OPTS ) or abort "Unable to create a new connection!"
+
+abort "Connect failed: %s" % [ conn.error_message ] unless conn.status == PG::CONNECTION_OK
+
+# Now grab a reference to the underlying socket to select() on while the query is running
+socket = conn.socket_io
+
+# Send the (asynchronous) query
+output_progress "Sending query"
+conn.send_query( "SELECT * FROM pg_stat_activity" )
+
+# Fetch results until there aren't any more
+loop do
+	output_progress "  waiting for a response"
+
+	# Buffer any incoming data on the socket until a full result is ready.
+	conn.consume_input
+	while conn.is_busy
+		output_progress "  waiting for data to be available on %p..." % [ socket ]
+		select( [socket], nil, nil, TIMEOUT ) or
+			raise "Timeout waiting for query response."
+		conn.consume_input
+	end
+
+	# Fetch the next result. If there isn't one, the query is finished
+	result = conn.get_result or break
+
+	output_progress "Query result:\n%p\n" % [ result.values ]
+end
+
+output_progress "Done."
+conn.finish
+

data/sample/check_conn.rb

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+# vim: set nosta noet ts=4 sw=4:
+# encoding: utf-8
+
+require 'pg'
+
+# This is a minimal example of a function that can test an existing PG::Connection and
+# reset it if necessary.
+
+def check_connection( conn )
+	begin
+		conn.exec( "SELECT 1" )
+	rescue PG::Error => err
+		$stderr.puts "%p while testing connection: %s" % [ err.class, err.message ]
+		conn.reset
+	end
+end
+
+conn = PG.connect( dbname: 'test' )
+check_connection( conn )
+

data/sample/copyfrom.rb

@@ -4,7 +4,7 @@ require 'pg'
 require 'stringio'
 
 $stderr.puts "Opening database connection ..."
-conn = PGconn.connect( :dbname => 'test' )
+conn = PG.connect( :dbname => 'test' )
 
 conn.exec( <<END_SQL )
 DROP TABLE IF EXISTS logs;

data/sample/copyto.rb

@@ -6,7 +6,7 @@ require 'stringio'
 # An example of how to stream data to your local host from the database as CSV.
 
 $stderr.puts "Opening database connection ..."
-conn = PGconn.connect( :dbname => 'test' )
+conn = PG.connect( :dbname => 'test' )
 
 $stderr.puts "Running COPY command ..."
 buf = ''

data/sample/cursor.rb

@@ -6,9 +6,9 @@ require 'pg'
 # the cursor portion of testlibpq.c from src/test/examples.
 
 $stderr.puts "Opening database connection ..."
-conn = PGconn.connect( :dbname => 'test' )
+conn = PG.connect( :dbname => 'test' )
 
-# 
+#
 conn.transaction do
     conn.exec( "DECLARE myportal CURSOR FOR select * from pg_database" )
     res = conn.exec( "FETCH ALL IN myportal" )

data/sample/disk_usage_report.rb

@@ -0,0 +1,186 @@
+#!/usr/bin/env ruby
+# vim: set noet nosta sw=4 ts=4 :
+#
+# Quickly dump size information for a given database.
+# Top twenty objects, and size per schema.
+#
+# Mahlon E. Smith <mahlon@martini.nu>
+#
+# Based on work by Jeff Davis <ruby@j-davis.com>.
+#
+
+
+begin
+	require 'ostruct'
+	require 'optparse'
+	require 'etc'
+	require 'pg'
+
+rescue LoadError # 1.8 support
+	unless Object.const_defined?( :Gem )
+		require 'rubygems'
+		retry
+	end
+	raise
+end
+
+SCRIPT_VERSION = %q$Id: disk_usage_report.rb,v 76ebae01c937 2013/03/26 17:50:02 ged $
+
+
+### Gather data and output it to $stdout.
+###
+def report( opts )
+	db = PG.connect(
+		:dbname   => opts.database,
+		:host     => opts.host,
+		:port     => opts.port,
+		:user     => opts.user,
+		:password => opts.pass,
+		:sslmode  => 'prefer'
+	)
+
+	# -----------------------------------------
+
+	db_info = db.exec %Q{
+		SELECT
+			count(oid) AS num_relations,
+			pg_size_pretty(pg_database_size('#{opts.database}')) AS dbsize
+		FROM
+			pg_class
+	}
+
+	puts '=' * 70
+	puts "Disk usage information for %s: (%d relations, %s total)" % [
+		opts.database,
+		db_info[0]['num_relations'],
+		db_info[0]['dbsize']
+	]
+	puts '=' * 70
+
+	# -----------------------------------------
+
+	top_twenty = db.exec %q{
+		SELECT
+			relname AS name,
+			relkind AS kind,
+			pg_size_pretty(pg_relation_size(pg_class.oid)) AS size
+		FROM
+			pg_class
+		ORDER BY
+			pg_relation_size(pg_class.oid) DESC
+		LIMIT 20
+	}
+
+	puts 'Top twenty objects by size:'
+	puts '-' * 70
+	top_twenty.each do |row|
+		type = case row['kind']
+			   when 'i'; 'index'
+			   when 't'; 'toast'
+			   when 'r'; 'table'
+			   when 'S'; 'sequence'
+			   else;     '???'
+			   end
+
+		puts "%40s %10s (%s)" % [ row['name'], row['size'], type ]
+	end
+	puts '-' * 70
+
+	# -----------------------------------------
+
+	schema_sizes = db.exec %q{
+		SELECT
+			table_schema,
+			pg_size_pretty( CAST( SUM(pg_total_relation_size(table_schema || '.' || table_name)) AS bigint)) AS size
+		FROM
+			information_schema.tables
+		GROUP BY
+			table_schema
+		ORDER BY
+			CAST( SUM(pg_total_relation_size(table_schema || '.' || table_name)) AS bigint ) DESC
+	}
+
+
+	puts 'Size per schema:'
+	puts '-' * 70
+	schema_sizes.each do |row|
+		puts "%20s %10s" % [ row['table_schema'], row['size'] ]
+	end
+	puts '-' * 70
+	puts
+
+	db.finish
+end
+
+
+### Parse command line arguments.  Return a struct of global options.
+###
+def parse_args( args )
+	options          = OpenStruct.new
+	options.database = Etc.getpwuid( Process.uid ).name
+	options.host     = '127.0.0.1'
+	options.port     = 5432
+	options.user     = Etc.getpwuid( Process.uid ).name
+	options.sslmode  = 'prefer'
+	options.interval = 5
+
+	opts = OptionParser.new do |opts|
+		opts.banner = "Usage: #{$0} [options]"
+
+		opts.separator ''
+		opts.separator 'Connection options:'
+
+		opts.on( '-d', '--database DBNAME',
+				"specify the database to connect to (default: \"#{options.database}\")" ) do |db|
+			options.database = db
+		end
+
+		opts.on( '-h', '--host HOSTNAME', 'database server host' ) do |host|
+			options.host = host
+		end
+
+		opts.on( '-p', '--port PORT', Integer,
+				"database server port (default: \"#{options.port}\")" ) do |port|
+			options.port = port
+		end
+
+		opts.on( '-U', '--user NAME',
+				"database user name (default: \"#{options.user}\")" ) do |user|
+			options.user = user
+		end
+
+		opts.on( '-W', 'force password prompt' ) do |pw|
+			print 'Password: '
+			begin
+				system 'stty -echo'
+				options.pass = gets.chomp
+			ensure
+				system 'stty echo'
+				puts
+			end
+		end
+
+		opts.separator ''
+		opts.separator 'Other options:'
+
+		opts.on_tail( '--help', 'show this help, then exit' ) do
+			$stderr.puts opts
+			exit
+		end
+
+		opts.on_tail( '--version', 'output version information, then exit' ) do
+			puts SCRIPT_VERSION
+			exit
+		end
+	end
+
+	opts.parse!( args )
+	return options
+end
+
+
+if __FILE__ == $0
+	opts = parse_args( ARGV )
+	report( opts )
+end
+