Class: PGresult

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
ext/postgres.c,
ext/postgres.c

Overview

******************************************************************

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.

Constant Summary collapse

EMPTY_QUERY = 
INT2FIX(PGRES_EMPTY_QUERY)
COMMAND_OK = 
INT2FIX(PGRES_COMMAND_OK)
TUPLES_OK = 
INT2FIX(PGRES_TUPLES_OK)
COPY_OUT = 
INT2FIX(PGRES_COPY_OUT)
COPY_IN = 
INT2FIX(PGRES_COPY_IN)
BAD_RESPONSE = 
INT2FIX(PGRES_BAD_RESPONSE)
NONFATAL_ERROR = 
INT2FIX(PGRES_NONFATAL_ERROR)
FATAL_ERROR = 
INT2FIX(PGRES_FATAL_ERROR)

Instance Method Summary collapse

Instance Method Details

#[](n) ⇒ Object

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

Equivalent to res.result[n].



1613
1614
1615
 
# File 'ext/postgres.c', line 1613

static VALUE
pgresult_aref(argc, argv, obj)
int argc;

#clear ⇒ Object Also known as: close

Clears the PGresult object as the result of the query.



1966
1967
1968
 
# File 'ext/postgres.c', line 1966

static VALUE
pgresult_clear(obj)
VALUE obj;

#cmdtuples ⇒ Object Also known as: 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.



1922
1923
1924
 
# File 'ext/postgres.c', line 1922

static VALUE
pgresult_cmdtuples(obj)
VALUE obj;

#cmdstatus ⇒ Object

Returns the status string of the last query command.



1936
1937
1938
 
# File 'ext/postgres.c', line 1936

static VALUE
pgresult_cmdstatus(obj)
VALUE obj;

#each {|tuple| ... } ⇒ Object

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

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

Yields:

  • (tuple) 


1588
1589
1590
 
# File 'ext/postgres.c', line 1588

static VALUE
pgresult_each(self)
VALUE self;

#fieldname(index) ⇒ Object

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_].



1724
1725
1726
 
# File 'ext/postgres.c', line 1724

static VALUE
pgresult_fieldname(obj, index)
VALUE obj, index;

#fieldnum(name) ⇒ Object

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.



1752
1753
1754
 
# File 'ext/postgres.c', line 1752

static VALUE
pgresult_fieldnum(obj, name)
VALUE obj, name;

#fields ⇒ Object

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' ]



1659
1660
1661
 
# File 'ext/postgres.c', line 1659

static VALUE
pgresult_fields(obj)
VALUE obj;

#type(index) ⇒ Object Also known as: type

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.



1776
1777
1778
 
# File 'ext/postgres.c', line 1776

static VALUE
pgresult_type(obj, index)
VALUE obj, index;

#getisnull(tuple_position, field_position) ⇒ Boolean

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

Equivalent to res.value(<i>tup_num</i>,<i>field_num</i>)==+nil+.

Returns:

  • (Boolean) 


1896
1897
1898
 
# File 'ext/postgres.c', line 1896

static VALUE
pgresult_getisnull(obj, tup_num, field_num)
VALUE obj, tup_num, field_num;

#getlength(tup_num, field_num) ⇒ Object

Returns the (String) length of the field in bytes.

Equivalent to res.value(<i>tup_num</i>,<i>field_num</i>).length.



1870
1871
1872
 
# File 'ext/postgres.c', line 1870

static VALUE
pgresult_getlength(obj, tup_num, field_num)
VALUE obj, tup_num, field_num;

#value(tup_num, field_num) ⇒ Object

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

Equivalent to res.result[<i>tup_num</i>][<i>field_num</i>] (but faster).



1822
1823
1824
 
# File 'ext/postgres.c', line 1822

static VALUE
pgresult_getvalue(obj, tup_num, field_num)
VALUE obj, tup_num, field_num;

#value_byname(tup_num, field_name) ⇒ Object

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

Equivalent to (but faster than) either of:

res.result[<i>tup_num</i>][ res.fieldnum(<i>field_name</i>) ]
res.value( <i>tup_num</i>, res.fieldnum(<i>field_name</i>) )

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



1854
1855
1856
 
# File 'ext/postgres.c', line 1854

static VALUE
pgresult_getvalue_byname(obj, tup_num, field_name)
VALUE obj, tup_num, field_name;

#num_fields ⇒ Object Also known as: num_fields

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

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



1702
1703
1704
 
# File 'ext/postgres.c', line 1702

static VALUE
pgresult_num_fields(obj)
VALUE obj;

#num_tuples ⇒ Object Also known as: num_tuples

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

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



1684
1685
1686
 
# File 'ext/postgres.c', line 1684

static VALUE
pgresult_num_tuples(obj)
VALUE obj;

#oid ⇒ Object

Returns the oid.



1949
1950
1951
 
# File 'ext/postgres.c', line 1949

static VALUE
pgresult_oid(obj)
VALUE obj;

#size(index) ⇒ Object

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



1798
1799
1800
 
# File 'ext/postgres.c', line 1798

static VALUE
pgresult_size(obj, index)
VALUE obj, index;

#status ⇒ Object

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

  • EMPTY_QUERY

  • COMMAND_OK

  • TUPLES_OK

  • COPY_OUT

  • COPY_IN



1484
1485
1486
 
# File 'ext/postgres.c', line 1484

static VALUE
pgresult_status(obj)
VALUE obj;