PGresult (Class)

In: postgres.c
Parent: Object

The class to represent the query result tuples (rows). An instance of this class is created as the result of every query. You may need to invoke the clear method of the instance when finished with the result for better memory performance.

Methods

[]   clear   cmdstatus   cmdtuples   each   fieldname   fieldnum   fields   getisnull   getlength   getvalue   getvalue_byname   num_fields   num_tuples   print   result   size   status   type  

Included Modules

Enumerable

Public Instance methods

res[ n ]

Returns the tuple (row) corresponding to n. Returns nil if n >= res.num_tuples.

Equivalent to res.result[n].

res.clear()

Clears the PGresult object as the result of the query.

res.cmdstatus()

Returns the status string of the last query command.

res.cmdtuples()

Returns the number of tuples (rows) affected by the SQL command.

If the SQL command that generated the PGresult was not one of INSERT, UPDATE, DELETE, MOVE, or FETCH, or if no tuples (rows) were affected, +0+ is returned.

res.each{ |tuple| ... }

Invokes the block for each tuple (row) in the result.

Equivalent to res.result.each{ |tuple| … }.

res.fieldname( index )

Returns the name of the field (column) corresponding to the index. 

  res=conn.exec("SELECT foo,bar AS biggles,jim,jam FROM mytable;")
  puts res.fieldname(2) => 'jim'
  puts res.fieldname(1) => 'biggles'

Equivalent to res.fields[index].

res.fieldnum( name )

Returns the index of the field specified by the string name. 

  res=conn.exec("SELECT foo,bar AS biggles,jim,jam FROM mytable;")
  puts res.fieldnum('foo') => 0

Raises an ArgumentError if the specified name isn’t one of the field names; raises a TypeError if name is not a String.

res.fields()

Returns an array of Strings representing the names of the fields in the result. 

  res=conn.exec("SELECT foo,bar AS biggles,jim,jam FROM mytable;")
  res.fields => [ 'foo' , 'biggles' , 'jim' , 'jam' ]
res.getisnull( tup_num, field_num ) => true or false

Returns true if the specified value is nil; false otherwise.

Equivalent to res.value(tup_num,field_num)==nil.

res.getlength( tup_num, field_num )

Returns the (String) length of the field in bytes. If the field is nil, returns +0+.

Equivalent to res.value(tup_num,field_num).length.

res.value( tup_num, field_num )

Returns the value in tuple number tup_num, field number field_num. (Row tup_num, column field_num.)

Equivalent to res.result[tup_num][field_num] (but faster).

res.value_byname( tup_num, field_name )

Returns the value in tuple number tup_num, for the field named field_name.

Equivalent to (but faster than) either of: 

   res.result[tup_num][res.fieldnum(field_name)]
   res.value( tup_num, res.fieldnum(field_name) )

(This method internally calls PGresult#value in a manner like the second example above; it is slower than using the field index directly.)

res.num_fields()

Returns the number of fields (columns) in the query result.

Similar to res.result[0].length (but faster).

res.num_tuples()

Returns the number of tuples (rows) in the query result.

Similar to res.result.length (but faster).

res.print( file, options )

Prints out all the rows and, optionally, the column names to the specified file output stream.

An example using this method can be found in samples/psql.rb in the postgres source code

For more information, see PQprint which is called internally by this method.

res.result()

Returns an array of tuples (rows, which are themselves arrays) that represent the query result.

res.size( index )

Returns the size of the field type in bytes. Returns -1 if the field is variable sized. 

  res = conn.exec("SELECT myInt, myVarChar50 FROM foo;")
  res.size(0) => 4
  res.size(1) => -1
res.status()

Returns the status of the query. The status value is one of:

  • EMPTY_QUERY — The string sent to the server was empty.
  • COMMAND_OK — Successful completion of a command returning no data.
  • TUPLES_OK — Successful completion of a command returning data (such as a SELECT or SHOW).
  • COPY_OUT — Copy Out (from server) data transfer started.
  • COPY_IN — Copy In (to server) data transfer started.
  • BAD_RESPONSE — The server’s response was not understood.
  • NONFATAL_ERROR — A nonfatal error (a notice or warning) occurred.
  • FATAL_ERROR — A fatal error occurred.

For more information, see PQresultStatus which is called internally by this method.

res.type( index )

Returns the data type associated with the given column number.

The integer returned is the internal OID number (in PostgreSQL) of the type. If you have the PostgreSQL source available, you can see the OIDs for every column type in the file src/include/catalog/pg_type.h.

Alternatively, you can look up the type direcly with: 

   oid = res.type(2)
   typename = conn.exec("select typname from pg_type where oid=#{oid}")

Note that there is no e in the field name ‘typname’.

[Validate]