Class: PGresult

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
ext/pg.c,
ext/pg.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.

Example:
   require 'pg'
   conn = PGconn.open(:dbname => 'test')
   res  = conn.exec('SELECT 1 AS a, 2 AS b, NULL AS c')
   res.getvalue(0,0) # '1'
   res[0]['b']       # '2'
   res[0]['c']       # nil

Constant Summary collapse

PGRES_EMPTY_QUERY =

result status *****

****     PGresult CONSTANTS
PGRES_COMMAND_OK = 
INT2FIX(PGRES_COMMAND_OK)
PGRES_TUPLES_OK = 
INT2FIX(PGRES_TUPLES_OK)
PGRES_COPY_OUT = 
INT2FIX(PGRES_COPY_OUT)
PGRES_COPY_IN = 
INT2FIX(PGRES_COPY_IN)
PGRES_BAD_RESPONSE = 
INT2FIX(PGRES_BAD_RESPONSE)
PGRES_NONFATAL_ERROR = 
INT2FIX(PGRES_NONFATAL_ERROR)
PGRES_FATAL_ERROR = 
INT2FIX(PGRES_FATAL_ERROR)
PG_DIAG_SEVERITY =

result error field codes *****

****     PGresult CONSTANTS
PG_DIAG_SQLSTATE = 
INT2FIX(PG_DIAG_SQLSTATE)
PG_DIAG_MESSAGE_PRIMARY = 
INT2FIX(PG_DIAG_MESSAGE_PRIMARY)
PG_DIAG_MESSAGE_DETAIL = 
INT2FIX(PG_DIAG_MESSAGE_DETAIL)
PG_DIAG_MESSAGE_HINT = 
INT2FIX(PG_DIAG_MESSAGE_HINT)
PG_DIAG_STATEMENT_POSITION = 
INT2FIX(PG_DIAG_STATEMENT_POSITION)
PG_DIAG_INTERNAL_POSITION = 
INT2FIX(PG_DIAG_INTERNAL_POSITION)
PG_DIAG_INTERNAL_QUERY = 
INT2FIX(PG_DIAG_INTERNAL_QUERY)
PG_DIAG_CONTEXT = 
INT2FIX(PG_DIAG_CONTEXT)
PG_DIAG_SOURCE_FILE = 
INT2FIX(PG_DIAG_SOURCE_FILE)
PG_DIAG_SOURCE_LINE = 
INT2FIX(PG_DIAG_SOURCE_LINE)
PG_DIAG_SOURCE_FUNCTION = 
INT2FIX(PG_DIAG_SOURCE_FUNCTION)

Instance Method Summary collapse

Instance Method Details

#[](n) ⇒ Hash

Returns tuple n as a hash.

Returns:

  • (Hash) 


3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
 
# File 'ext/pg.c', line 3253

static VALUE
pgresult_aref(VALUE self, VALUE index)
{
  PGresult *result = get_pgresult(self);
  int tuple_num = NUM2INT(index);
  int field_num;
  VALUE fname,val;
  VALUE tuple;

  if(tuple_num >= PQntuples(result))
    rb_raise(rb_eIndexError, "Index %d is out of range", tuple_num);
  tuple = rb_hash_new();
  for(field_num = 0; field_num < PQnfields(result); field_num++) {
    fname = rb_tainted_str_new2(PQfname(result,field_num));
    if(PQgetisnull(result, tuple_num, field_num)) {
      rb_hash_aset(tuple, fname, Qnil);
    }
    else {
      val = rb_tainted_str_new(PQgetvalue(result, tuple_num, field_num),
        PQgetlength(result, tuple_num, field_num));
      rb_hash_aset(tuple, fname, val);
    }
  }
  return tuple;
}

#clear ⇒ nil

Clears the PGresult object as the result of the query.

Returns:

  • (nil) 


2882
2883
2884
2885
2886
2887
2888
 
# File 'ext/pg.c', line 2882

static VALUE
pgresult_clear(VALUE self)
{
  PQclear(get_pgresult(self));
  DATA_PTR(self) = NULL;
  return Qnil;
}

#cmd_status ⇒ String

Returns the status string of the last query command.

Returns:

  • (String) 


3200
3201
3202
3203
3204
 
# File 'ext/pg.c', line 3200

static VALUE
pgresult_cmd_status(VALUE self)
{
  return rb_tainted_str_new2(PQcmdStatus(get_pgresult(self)));
}

#cmd_tuples ⇒ Fixnum 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

  • FETCH

or if no tuples were affected, 0 is returned.

Returns:

  • (Fixnum) 


3220
3221
3222
3223
3224
3225
3226
 
# File 'ext/pg.c', line 3220

static VALUE
pgresult_cmd_tuples(VALUE self)
{
  long n;
  n = strtol(PQcmdTuples(get_pgresult(self)),NULL, 10);
  return INT2NUM(n);
}

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

Invokes block for each tuple in the result set.

Yields:

  • (tuple) 


3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
 
# File 'ext/pg.c', line 3285

static VALUE
pgresult_each(VALUE self)
{
  PGresult *result = get_pgresult(self);
  int tuple_num;

  for(tuple_num = 0; tuple_num < PQntuples(result); tuple_num++) {
    rb_yield(pgresult_aref(self, INT2NUM(tuple_num)));
  }
  return self;
}

#fformat(column_number) ⇒ Fixnum

Returns the format (0 for text, 1 for binary) of column column_number.

Raises ArgumentError if column_number is out of range.

Returns:

  • (Fixnum) 


3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
 
# File 'ext/pg.c', line 3008

static VALUE
pgresult_fformat(VALUE self, VALUE column_number)
{
  PGresult *result = get_pgresult(self);
  int fnumber = NUM2INT(column_number);
  if (fnumber >= PQnfields(result)) {
    rb_raise(rb_eArgError, "Column number is out of range: %d",
      fnumber);
  }
  return INT2FIX(PQfformat(result, fnumber));
}

#fields ⇒ Array

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

Returns:

  • (Array) 


3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
 
# File 'ext/pg.c', line 3303

static VALUE
pgresult_fields(VALUE self)
{
  PGresult *result;
  VALUE ary;
  int n, i;

  result = get_pgresult(self);
  n = PQnfields(result);
  ary = rb_ary_new2(n);
  for (i=0;i<n;i++) {
    rb_ary_push(ary, rb_tainted_str_new2(PQfname(result, i)));
  }
  return ary;
}

#fmod(column_number) ⇒ Object

Returns the type modifier associated with column column_number.

Raises ArgumentError if column_number is out of range.



3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
 
# File 'ext/pg.c', line 3047

static VALUE
pgresult_fmod(VALUE self, VALUE column_number)
{
  PGresult *result = get_pgresult(self);
  int fnumber = NUM2INT(column_number);
  int modifier;
  if (fnumber >= PQnfields(result)) {
    rb_raise(rb_eArgError, "Column number is out of range: %d",
      fnumber);
  }
  if((modifier = PQfmod(result,fnumber)) == -1)
    rb_raise(rb_eArgError,
      "No modifier information available for column: %d",
      fnumber);
  return INT2NUM(modifier);
}

#fname(index) ⇒ String

Returns the name of the column corresponding to index.

Returns:

  • (String) 


2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
 
# File 'ext/pg.c', line 2920

static VALUE
pgresult_fname(VALUE self, VALUE index)
{
  PGresult *result;
  int i = NUM2INT(index);

  result = get_pgresult(self);
  if (i < 0 || i >= PQnfields(result)) {
    rb_raise(rb_eArgError,"invalid field number %d", i);
  }
  return rb_tainted_str_new2(PQfname(result, i));
}

#fnumber(name) ⇒ Fixnum

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

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

Returns:

  • (Fixnum) 


2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
 
# File 'ext/pg.c', line 2942

static VALUE
pgresult_fnumber(VALUE self, VALUE name)
{
  int n;

  Check_Type(name, T_STRING);

  n = PQfnumber(get_pgresult(self), StringValuePtr(name));
  if (n == -1) {
    rb_raise(rb_eArgError,"Unknown field: %s", StringValuePtr(name));
  }
  return INT2FIX(n);
}

#fsize(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



3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
 
# File 'ext/pg.c', line 3074

static VALUE
pgresult_fsize(VALUE self, VALUE index)
{
  PGresult *result;
  int i = NUM2INT(index);

  result = get_pgresult(self);
  if (i < 0 || i >= PQnfields(result)) {
    rb_raise(rb_eArgError,"invalid field number %d", i);
  }
  return INT2NUM(PQfsize(result, i));
}

#ftable(column_number) ⇒ Fixnum

Returns the Oid of the table from which the column column_number was fetched.

Raises ArgumentError if column_number is out of range or if the Oid is undefined for that column.

Returns:

  • (Fixnum) 


2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
 
# File 'ext/pg.c', line 2966

static VALUE
pgresult_ftable(VALUE self, VALUE column_number)
{
  Oid n = PQftable(get_pgresult(self), NUM2INT(column_number));
  if (n == InvalidOid) {
    rb_raise(rb_eArgError,"Oid is undefined for column: %d",
      NUM2INT(column_number));
  }
  return INT2FIX(n);
}

#ftablecol(column_number) ⇒ Fixnum

Returns the column number (within its table) of the table from which the column column_number is made up.

Raises ArgumentError if column_number is out of range or if the column number from its table is undefined for that column.

Returns:

  • (Fixnum) 


2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
 
# File 'ext/pg.c', line 2987

static VALUE
pgresult_ftablecol(VALUE self, VALUE column_number)
{
  int n = PQftablecol(get_pgresult(self), NUM2INT(column_number));
  if (n == 0) {
    rb_raise(rb_eArgError,
      "Column number from table is undefined for column: %d",
      NUM2INT(column_number));
  }
  return INT2FIX(n);
}

#ftype(column_number) ⇒ Object

Returns the data type associated with column_number.

The integer returned is the internal OID number (in PostgreSQL) of the type.



3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
 
# File 'ext/pg.c', line 3028

static VALUE
pgresult_ftype(VALUE self, VALUE index)
{
  PGresult* result = get_pgresult(self);
  int i = NUM2INT(index);
  if (i < 0 || i >= PQnfields(result)) {
    rb_raise(rb_eArgError, "invalid field number %d", i);
  }
  return INT2NUM(PQftype(result, i));
}

#getisnull(tuple_position, field_position) ⇒ Boolean

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

Returns:

  • (Boolean) 


3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
 
# File 'ext/pg.c', line 3120

static VALUE
pgresult_getisnull(VALUE self, VALUE tup_num, VALUE field_num)
{
  PGresult *result;
  int i = NUM2INT(tup_num);
  int j = NUM2INT(field_num);

  result = get_pgresult(self);
  if (i < 0 || i >= PQntuples(result)) {
    rb_raise(rb_eArgError,"invalid tuple number %d", i);
  }
  if (j < 0 || j >= PQnfields(result)) {
    rb_raise(rb_eArgError,"invalid field number %d", j);
  }
  return PQgetisnull(result, i, j) ? Qtrue : Qfalse;
}

#getlength(tup_num, field_num) ⇒ Fixnum

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

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

Returns:

  • (Fixnum) 


3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
 
# File 'ext/pg.c', line 3145

static VALUE
pgresult_getlength(VALUE self, VALUE tup_num, VALUE field_num)
{
  PGresult *result;
  int i = NUM2INT(tup_num);
  int j = NUM2INT(field_num);

  result = get_pgresult(self);
  if (i < 0 || i >= PQntuples(result)) {
    rb_raise(rb_eArgError,"invalid tuple number %d", i);
  }
  if (j < 0 || j >= PQnfields(result)) {
    rb_raise(rb_eArgError,"invalid field number %d", j);
  }
  return INT2FIX(PQgetlength(result, i, j));
}

#getvalue(tup_num, field_num) ⇒ Object

Returns the value in tuple number tup_num, field field_num, or nil if the field is NULL.



3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
 
# File 'ext/pg.c', line 3094

static VALUE
pgresult_getvalue(VALUE self, VALUE tup_num, VALUE field_num)
{
  PGresult *result;
  int i = NUM2INT(tup_num);
  int j = NUM2INT(field_num);

  result = get_pgresult(self);
  if(i < 0 || i >= PQntuples(result)) {
    rb_raise(rb_eArgError,"invalid tuple number %d", i);
  }
  if(j < 0 || j >= PQnfields(result)) {
    rb_raise(rb_eArgError,"invalid field number %d", j);
  }
  if(PQgetisnull(result, i, j))
    return Qnil;
  return rb_tainted_str_new(PQgetvalue(result, i, j),
        PQgetlength(result, i, j));
}

#nfields ⇒ Fixnum Also known as: num_fields

Returns the number of columns in the query result.

Returns:

  • (Fixnum) 


2908
2909
2910
2911
2912
 
# File 'ext/pg.c', line 2908

static VALUE
pgresult_nfields(VALUE self)
{
  return INT2NUM(PQnfields(get_pgresult(self)));
}

#nparams ⇒ Fixnum

Returns the number of parameters of a prepared statement. Only useful for the result returned by conn.describePrepared

Returns:

  • (Fixnum) 


3169
3170
3171
3172
3173
3174
3175
3176
 
# File 'ext/pg.c', line 3169

static VALUE
pgresult_nparams(VALUE self)
{
  PGresult *result;

  result = get_pgresult(self);
  return INT2FIX(PQnparams(result));
}

#ntuples ⇒ Fixnum Also known as: num_tuples

Returns the number of tuples in the query result.

Returns:

  • (Fixnum) 


2896
2897
2898
2899
2900
 
# File 'ext/pg.c', line 2896

static VALUE
pgresult_ntuples(VALUE self)
{
  return INT2FIX(PQntuples(get_pgresult(self)));
}

#oid_value ⇒ Fixnum

Returns the oid of the inserted row if applicable, otherwise nil.

Returns:

  • (Fixnum) 


3235
3236
3237
3238
3239
3240
3241
3242
3243
 
# File 'ext/pg.c', line 3235

static VALUE
pgresult_oid_value(VALUE self)
{
  Oid n = PQoidValue(get_pgresult(self));
  if (n == InvalidOid)
    return Qnil;
  else
    return INT2FIX(n);
}

#paramtype(param_number) ⇒ Oid

Returns the Oid of the data type of parameter param_number. Only useful for the result returned by conn.describePrepared

Returns:

  • (Oid) 


3185
3186
3187
3188
3189
3190
3191
3192
 
# File 'ext/pg.c', line 3185

static VALUE
pgresult_paramtype(VALUE self, VALUE param_number)
{
  PGresult *result;

  result = get_pgresult(self);
  return INT2FIX(PQparamtype(result,NUM2INT(param_number)));
}

#res_status(status) ⇒ String

Returns the string representation of status status.

Returns:

  • (String) 


2830
2831
2832
2833
2834
 
# File 'ext/pg.c', line 2830

static VALUE
pgresult_res_status(VALUE self, VALUE status)
{
  return rb_tainted_str_new2(PQresStatus(NUM2INT(status)));
}

#result_error_field(fieldcode) ⇒ String

Returns the individual field of an error.

fieldcode is one of:

  • PG_DIAG_SEVERITY

  • PG_DIAG_SQLSTATE

  • PG_DIAG_MESSAGE_PRIMARY

  • PG_DIAG_MESSAGE_DETAIL

  • PG_DIAG_MESSAGE_HINT

  • PG_DIAG_STATEMENT_POSITION

  • PG_DIAG_INTERNAL_POSITION

  • PG_DIAG_INTERNAL_QUERY

  • PG_DIAG_CONTEXT

  • PG_DIAG_SOURCE_FILE

  • PG_DIAG_SOURCE_LINE

  • PG_DIAG_SOURCE_FUNCTION

Returns:

  • (String) 


2868
2869
2870
2871
2872
2873
2874
 
# File 'ext/pg.c', line 2868

static VALUE
pgresult_result_error_field(VALUE self, VALUE field)
{
  PGresult *result = get_pgresult(self);
  int fieldcode = NUM2INT(field);
  return rb_tainted_str_new2(PQresultErrorField(result,fieldcode));
}

#result_error_message ⇒ String

Returns the error message of the command as a string.

Returns:

  • (String) 


2842
2843
2844
2845
2846
 
# File 'ext/pg.c', line 2842

static VALUE
pgresult_result_error_message(VALUE self)
{
  return rb_tainted_str_new2(PQresultErrorMessage(get_pgresult(self)));
}

#result_status ⇒ Fixnum

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

  • PGRES_EMPTY_QUERY

  • PGRES_COMMAND_OK

  • PGRES_TUPLES_OK

  • PGRES_COPY_OUT

  • PGRES_COPY_IN

  • PGRES_BAD_RESPONSE

  • PGRES_NONFATAL_ERROR

  • PGRES_FATAL_ERROR

Returns:

  • (Fixnum) 


2817
2818
2819
2820
2821
 
# File 'ext/pg.c', line 2817

static VALUE
pgresult_result_status(VALUE self)
{
  return INT2FIX(PQresultStatus(get_pgresult(self)));
}