pg 0.12.2 → 0.13.0.pre298

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.13.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: b2cd37832d02 $
+
+
+	### 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/lib/pg/connection.rb

@@ -0,0 +1,58 @@
+#!/usr/bin/env ruby
+
+require 'pg' unless defined?( PG )
+
+# The PG connection class.
+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().
+		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, 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
+
+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,11 @@
+#!/usr/bin/env ruby
+
+require 'pg' unless defined?( PG )
+
+
+class PG::Result
+	
+end # class PG::Result
+
+# Backward-compatible alias
+PGresult = PG::Result

data/misc/openssl-pg-segfault.rb

@@ -8,7 +8,7 @@ SOCKHOST = 'it-trac.laika.com'
 # Load pg first, so the libssl.so that libpq is linked against is loaded.
 require 'pg'
 $stderr.puts "connecting to postgres://#{PGHOST}/#{PGDB}"
-conn = PGconn.connect( PGHOST, :dbname => PGDB )
+conn = PG.connect( PGHOST, :dbname => PGDB )
 
 # Now load OpenSSL, which might be linked against a different libssl.
 require 'socket'

data/sample/async_api.rb

@@ -4,16 +4,10 @@ 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,
@@ -28,9 +22,10 @@ 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
@@ -38,19 +33,19 @@ socket = IO.for_fd( conn.socket )
 
 # 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,17 +53,17 @@ 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."
 	end
 
@@ -76,7 +71,7 @@ until poll_status == PGconn::PGRES_POLLING_OK ||
 	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" )

data/sample/async_copyto.rb

@@ -6,7 +6,7 @@ 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 )

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 = IO.for_fd( conn.socket )
+
+# 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/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,7 +6,7 @@ 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

data/sample/losample.rb

@@ -5,7 +5,7 @@ require 'pg'
 SAMPLE_WRITE_DATA = 'some sample data'
 SAMPLE_EXPORT_NAME = 'lowrite.txt'
 
-conn = PGconn.connect( :dbname => 'test', :host => 'localhost', :port => 5432 )
+conn = PG.connect( :dbname => 'test', :host => 'localhost', :port => 5432 )
 puts "dbname: " + conn.db + "\thost: " + conn.host + "\tuser: " + conn.user
 
 # Start a transaction, as all large object functions require one.
@@ -20,15 +20,15 @@ puts "  imported as large object %d" % [ oid ]
 
 # Read back 50 bytes of the imported data
 puts "Read test:"
-fd = conn.lo_open( oid, PGconn::INV_READ|PGconn::INV_WRITE )
-conn.lo_lseek( fd, 0, PGconn::SEEK_SET )
+fd = conn.lo_open( oid, PG::INV_READ|PG::INV_WRITE )
+conn.lo_lseek( fd, 0, PG::SEEK_SET )
 buf = conn.lo_read( fd, 50 )
 puts "  read: %p" % [ buf ]
 puts "  read was ok!" if buf =~ /require 'pg'/
 
 # Append some test data onto the end of the object
 puts "Write test:"
-conn.lo_lseek( fd, 0, PGconn::SEEK_END )
+conn.lo_lseek( fd, 0, PG::SEEK_END )
 buf = SAMPLE_WRITE_DATA.dup
 totalbytes = 0
 until buf.empty?
@@ -53,9 +53,9 @@ puts 'Testing read and delete from a new transaction:'
 puts '  starting a new transaction'
 conn.exec( 'BEGIN' )
 
-fd = conn.lo_open( oid, PGconn::INV_READ )
+fd = conn.lo_open( oid, PG::INV_READ )
 puts '  reopened okay.'
-conn.lo_lseek( fd, 50, PGconn::SEEK_END )
+conn.lo_lseek( fd, 50, PG::SEEK_END )
 buf = conn.lo_read( fd, 50 )
 puts '  read okay.' if buf == SAMPLE_WRITE_DATA
 

data/sample/notify_wait.rb

@@ -2,25 +2,6 @@
 #
 # Test script, demonstrating a non-poll notification for a table event.
 #
-# To use, create a table called 'test', and attach a NOTIFY trigger to it
-# like so:
-#
-#     CREATE OR REPLACE FUNCTION notify_test()
-#     RETURNS TRIGGER
-#     LANGUAGE plpgsql
-#     AS $$
-#         BEGIN
-#             NOTIFY woo;
-#             RETURN NULL;
-#         END
-#     $$
-#
-#     CREATE TRIGGER notify_trigger
-#     AFTER UPDATE OR INSERT OR DELETE
-#     ON test
-#     FOR EACH STATEMENT
-#     EXECUTE PROCEDURE notify_test()
-#
 
 BEGIN {
         require 'pathname'
@@ -31,13 +12,61 @@ BEGIN {
 
 require 'pg'
 
-conn = PGconn.connect( :dbname => 'test' )
+TRIGGER_TABLE = %{
+	CREATE TABLE IF NOT EXISTS test ( message text );
+}
+
+TRIGGER_FUNCTION = %{
+CREATE OR REPLACE FUNCTION notify_test()
+RETURNS TRIGGER
+LANGUAGE plpgsql
+AS $$
+    BEGIN
+        NOTIFY woo;
+        RETURN NULL;
+    END
+$$
+}
+
+DROP_TRIGGER = %{
+DROP TRIGGER IF EXISTS notify_trigger ON test
+}
+
+
+TRIGGER = %{
+CREATE TRIGGER notify_trigger
+AFTER UPDATE OR INSERT OR DELETE
+ON test
+FOR EACH STATEMENT
+EXECUTE PROCEDURE notify_test();
+}
+
+conn = PG.connect( :dbname => 'test' )
+
+conn.exec( TRIGGER_TABLE )
+conn.exec( TRIGGER_FUNCTION )
+conn.exec( DROP_TRIGGER )
+conn.exec( TRIGGER )
+
 conn.exec( 'LISTEN woo' )  # register interest in the 'woo' event
 
+notifications = []
+
+puts "Now switch to a different term and run:",
+     '',
+     %{  psql test -c "insert into test values ('A message.')"},
+	 ''
+
 puts "Waiting up to 30 seconds for for an event!"
 conn.wait_for_notify( 30 ) do |notify, pid|
-	puts "I got one from pid %d: %s" % [ pid, notify ]
+	notifications << [ pid, notify ]
+end
+
+if notifications.empty?
+	puts "Awww, I didn't see any events."
+else
+	puts "I got one from pid %d: %s" % notifications.first
 end
 
-puts "Awww, I didn't see any events."
+