Method: PG::Connection#set_single_row_mode

Defined in:

ext/pg_connection.c

#set_single_row_mode ⇒ self

To enter single-row mode, call this method immediately after a successful call of send_query (or a sibling function). This mode selection is effective only for the currently executing query. Then call Connection#get_result repeatedly, until it returns nil.

Each (but the last) received Result has exactly one row and a Result#result_status of PGRES_SINGLE_TUPLE. The last Result has zero rows and is used to indicate a successful execution of the query. All of these Result objects will contain the same row description data (column names, types, etc) that an ordinary Result object for the query would have.

Caution: While processing a query, the server may return some rows and then encounter an error, causing the query to be aborted. Ordinarily, pg discards any such rows and reports only the error. But in single-row or chunked mode, some rows may have already been returned to the application. Hence, the application will see some PGRES_SINGLE_TUPLE or PGRES_TUPLES_CHUNK PG::Result objects followed by a PG::Error raised in get_result. For proper transactional behavior, the application must be designed to discard or undo whatever has been done with the previously-processed rows, if the query ultimately fails.

Example:

conn.send_query( "your SQL command" )
conn.set_single_row_mode
loop do
  res = conn.get_result or break
  res.check
  res.each do |row|
    # do something with the received row
  end
end

Returns:

• (self)

# File 'ext/pg_connection.c', line 1882

static VALUE
pgconn_set_single_row_mode(VALUE self)
{
	PGconn *conn = pg_get_pgconn(self);

	rb_check_frozen(self);
	if( PQsetSingleRowMode(conn) == 0 )
		pg_raise_conn_error( rb_ePGerror, self, "PQsetSingleRowMode %s", PQerrorMessage(conn));

	return self;
}