jruby-pg 0.1-java

data/lib/pg.rb

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+
+begin
+  require 'pg_ext'
+rescue LoadError
+  # If it's a Windows binary gem, try the <major>.<minor> subdirectory
+  if RUBY_PLATFORM =~/(mswin|mingw)/i
+    major_minor = RUBY_VERSION[ /^(\d+\.\d+)/ ] or
+      raise "Oops, can't extract the major/minor version from #{RUBY_VERSION.dump}"
+    require "#{major_minor}/pg_ext"
+  else
+    raise
+  end
+end
+
+# The top-level PG namespace.
+module PG
+
+	# Library version
+	VERSION = RUBY_ENGINE == 'jruby' ? '0.1' : '0.17.1'
+
+	# VCS revision
+	REVISION = %q$Revision$
+
+	class NotAllCopyDataRetrieved < PG::Error
+	end
+
+	### 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
+
+
+	### Convenience alias for PG::Connection.new.
+	def self::connect( *args )
+		return PG::Connection.new( *args )
+	end
+
+
+	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,179 @@
+#!/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
+
+	#  call-seq:
+	#     conn.copy_data( sql ) {|sql_result| ... } -> PG::Result
+	#
+	# Execute a copy process for transfering data to or from the server.
+	#
+	# This issues the SQL COPY command via #exec. The response to this
+	# (if there is no error in the command) is a PG::Result object that
+	# is passed to the block, bearing a status code of PGRES_COPY_OUT or
+	# PGRES_COPY_IN (depending on the specified copy direction).
+	# The application should then use #put_copy_data or #get_copy_data
+	# to receive or transmit data rows and should return from the block
+	# when finished.
+	#
+	# #copy_data returns another PG::Result object when the data transfer
+	# is complete. An exception is raised if some problem was encountered,
+	# so it isn't required to make use of any of them.
+	# At this point further SQL commands can be issued via #exec.
+	# (It is not possible to execute other SQL commands using the same
+	# connection while the COPY operation is in progress.)
+	#
+	# This method ensures, that the copy process is properly terminated
+	# in case of client side or server side failures. Therefore, in case
+	# of blocking mode of operation, #copy_data is preferred to raw calls
+	# of #put_copy_data, #get_copy_data and #put_copy_end.
+	#
+	# Example with CSV input format:
+	#   conn.exec "create table my_table (a text,b text,c text,d text,e text)"
+	#   conn.copy_data "COPY my_table FROM STDOUT CSV" do
+	#     conn.put_copy_data "some,csv,data,to,copy\n"
+	#     conn.put_copy_data "more,csv,data,to,copy\n"
+	#   end
+	# This creates +my_table+ and inserts two rows.
+	#
+	# Example with CSV output format:
+	#   conn.copy_data "COPY my_table TO STDOUT CSV" do
+	#     while row=conn.get_copy_data
+	#       p row
+	#     end
+	#   end
+	# This prints all rows of +my_table+ to stdout:
+	#   "some,csv,data,to,copy\n"
+	#   "more,csv,data,to,copy\n"
+	def copy_data( sql )
+		res = exec( sql )
+
+		case res.result_status
+		when PGRES_COPY_IN
+			begin
+				yield res
+			rescue Exception => err
+				errmsg = "%s while copy data: %s" % [ err.class.name, err.message ]
+				put_copy_end( errmsg )
+				get_result
+				raise
+			else
+				put_copy_end
+				get_last_result
+			end
+
+		when PGRES_COPY_OUT
+			begin
+				yield res
+			rescue Exception => err
+				cancel
+				while get_copy_data
+				end
+				while get_result
+				end
+				raise
+			else
+				res = get_last_result
+				if res.result_status != PGRES_COMMAND_OK
+					while get_copy_data
+					end
+					while get_result
+					end
+					raise PG::NotAllCopyDataRetrieved, "Not all COPY data retrieved"
+				end
+				res
+			end
+
+		else
+			raise ArgumentError, "SQL command is no COPY statement: #{sql}"
+		end
+	end
+
+	# Backward-compatibility aliases for stuff that's moved into PG.
+	class << self
+		define_method( :isthreadsafe, &PG.method(:isthreadsafe) )
+	end
+
+
+	### Returns an array of Hashes with connection defaults. See ::conndefaults
+	### for details.
+	def conndefaults
+		return self.class.conndefaults
+	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/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

@@ -0,0 +1,106 @@
+#!/usr/bin/env ruby
+
+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 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
+
+# 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
+# comment this out entirely for cleaner output.
+progress_thread = Thread.new { loop { print 'x' } }
+
+# Output progress messages
+def output_progress( msg )
+	puts "\n>>> #{msg}\n"
+end
+
+# Start the connection
+output_progress "Starting 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 == PG::CONNECTION_BAD
+
+# Now grab a reference to the underlying socket so we know when the
+# connection is established
+socket = conn.socket_io
+
+# Track the progress of the connection, waiting for the socket to become readable/writable
+# before polling it
+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 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 PG::PGRES_POLLING_WRITING
+		output_progress "  waiting for socket to become writable"
+		select( nil, [socket], nil, TIMEOUT ) or
+			raise "Asynchronous connection timed out!"
+	end
+
+	# Output a status message about the progress
+	case conn.status
+	when PG::CONNECTION_STARTED
+		output_progress "  waiting for connection to be made."
+	when PG::CONNECTION_MADE
+		output_progress "  connection OK; waiting to send."
+	when PG::CONNECTION_AWAITING_RESPONSE
+		output_progress "  waiting for a response from the server."
+	when PG::CONNECTION_AUTH_OK
+		output_progress "  received authentication; waiting for backend start-up to finish."
+	when PG::CONNECTION_SSL_STARTUP
+		output_progress "  negotiating SSL encryption."
+	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 == PG::CONNECTION_OK
+
+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
+		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
+
+	puts "\n\nQuery result:\n%p\n" % [ result.values ]
+end
+
+output_progress "Done."
+conn.finish
+
+if defined?( progress_thread )
+	progress_thread.kill
+	progress_thread.join
+end
+

data/sample/async_copyto.rb

@@ -0,0 +1,39 @@
+#!/usr/bin/env ruby
+
+require 'pg'
+require 'stringio'
+
+# Using COPY asynchronously
+
+$stderr.puts "Opening database connection ..."
+conn = PG.connect( :dbname => 'test' )
+conn.setnonblocking( true )
+
+socket = conn.socket_io
+
+$stderr.puts "Running COPY command ..."
+buf = ''
+conn.transaction do
+	conn.send_query( "COPY logs TO STDOUT WITH csv" )
+	buf = nil
+
+	# #get_copy_data returns a row if there's a whole one to return, false
+	# if there isn't one but the COPY is still running, or nil when it's
+	# finished.
+	begin
+		$stderr.puts "COPY loop"
+		conn.consume_input
+		while conn.is_busy
+			$stderr.puts "  ready loop"
+			select( [socket], nil, nil, 5.0 ) or
+				raise "Timeout (5s) waiting for query response."
+			conn.consume_input
+		end
+
+		buf = conn.get_copy_data
+		$stdout.puts( buf ) if buf
+	end until buf.nil?
+end
+
+conn.finish
+

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
+