Class: PGconn

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

Overview

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

The class to access PostgreSQL database.

For example, to send query to the database on the localhost:
   require 'pg'
   conn = PGconn.open('dbname' => 'test1')
   res  = conn.exec('select * from a')

See the PGresult class for information on working with the results of a query.

Constant Summary collapse

CONNECTION_OK = 
INT2FIX(CONNECTION_OK)
CONNECTION_BAD = 
INT2FIX(CONNECTION_BAD)

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Object

call-seq:

   PGconn.open(connection_hash) -> PGconn
   PGconn.open(connection_string) -> PGconn
   PGconn.open(host, port, options, tty, dbname, , passwd) ->  PGconn

_host_::     server hostname
_port_::     server port number
_options_::  backend options (String)
_tty_::      tty to print backend debug message <i>(ignored in newer versions of PostgreSQL)</i> (String)
_dbname_::     connecting database name
_login_::      login user name
_passwd_::     login password

On failure, it raises a PGError exception.



608
609
610
 
# File 'ext/postgres.c', line 608

static VALUE
pgconn_init(argc, argv, self)
int argc;

Class Method Details

.escape ⇒ Object

Returns a SQL-safe version of the String str. Unlike #quote, does not wrap the String in ‘…’.



435
436
437
 
# File 'ext/postgres.c', line 435

static VALUE
pgconn_s_escape(self, string)
VALUE self;

.escape_bytea(obj) ⇒ Object

Escapes binary data for use within an SQL command with the type bytea.

Certain byte values must be escaped (but all byte values may be escaped) when used as part of a bytea literal in an SQL statement. In general, to escape a byte, it is converted into the three digit octal number equal to the octet value, and preceded by two backslashes. The single quote (‘) and backslash () characters have special alternative escape sequences. #escape_bytea performs this operation, escaping only the minimally required bytes.

See the PostgreSQL documentation on PQescapeBytea for more information.



490
491
492
 
# File 'ext/postgres.c', line 490

static VALUE
pgconn_s_escape_bytea(self, obj)
VALUE self;

.new ⇒ Object

call-seq:

   PGconn.open(connection_hash) -> PGconn
   PGconn.open(connection_string) -> PGconn
   PGconn.open(host, port, options, tty, dbname, , passwd) ->  PGconn

_host_::     server hostname
_port_::     server port number
_options_::  backend options (String)
_tty_::      tty to print backend debug message <i>(ignored in newer versions of PostgreSQL)</i> (String)
_dbname_::     connecting database name
_login_::      login user name
_passwd_::     login password

On failure, it raises a PGError exception.



596
597
598
 
# File 'ext/postgres.c', line 596

static VALUE
pgconn_s_new(argc, argv, klass)
int argc;

.quote(obj) ⇒ Object .quote(obj) {|obj| ... } ⇒ Object .format(obj) ⇒ Object .format(obj) {|obj| ... } ⇒ Object

If obj is a Number, String, Array, nil, true, or false then #quote returns a String representation of that object safe for use in PostgreSQL.

If obj is not one of the above classes and a block is supplied to #quote, the block is invoked, passing along the object. The return value from the block is returned as a string.

If obj is not one of the recognized classes andno block is supplied, a PGError is raised.

Overloads:

  • .quote(obj) {|obj| ... } ⇒ Object

    Yields:

    • (obj)
  • .format(obj) {|obj| ... } ⇒ Object

    Yields:

    • (obj) 


296
297
298
 
# File 'ext/postgres.c', line 296

static VALUE
pgconn_s_quote(self, obj)
VALUE self, obj;

.quote_ident(str) ⇒ Object

Returns a SQL-safe identifier.



404
405
406
 
# File 'ext/postgres.c', line 404

static VALUE
pgconn_s_quote_ident(self, string)
VALUE self;

.translate_results=(boolean) ⇒ Object

When true (default), results are translated to appropriate ruby class. When false, results are returned as Strings.



238
239
240
 
# File 'ext/postgres.c', line 238

static VALUE
pgconn_s_translate_results_set(self, fact)
VALUE self, fact;

.unescape_bytea(obj) ⇒ Object

Converts an escaped string representation of binary data into binary data — the reverse of #escape_bytea. This is needed when retrieving bytea data in text format, but not when retrieving it in binary format.

See the PostgreSQL documentation on PQunescapeBytea for more information.



557
558
559
 
# File 'ext/postgres.c', line 557

static VALUE
pgconn_s_unescape_bytea(self, obj)
VALUE self, obj;

Instance Method Details

#async_exec(sql) ⇒ Object

Sends an asyncrhonous SQL query request specified by sql to the PostgreSQL. Returns a PGresult instance on success. On failure, it raises a PGError exception.



799
800
801
 
# File 'ext/postgres.c', line 799

static VALUE
pgconn_async_exec(obj, str)
VALUE obj, str;

#async_query(sql) ⇒ Object

Sends an asynchronous SQL query request specified by sql to the PostgreSQL. Returns an Array as the resulting tuple on success. On failure, it returns nil, and the error details can be obtained by #error.



897
898
899
 
# File 'ext/postgres.c', line 897

static VALUE
pgconn_async_query(obj, str)
VALUE obj, str;

#client_encoding ⇒ String

Returns the client encoding as a String.

Returns:

  • (String) 


1357
1358
1359
 
# File 'ext/postgres.c', line 1357

static VALUE
pgconn_client_encoding(obj)
VALUE obj;

#close ⇒ Object Also known as: finish

Closes the backend connection.



638
639
640
 
# File 'ext/postgres.c', line 638

static VALUE
pgconn_close(self)
VALUE self;

#db ⇒ Object

Returns the connected database name.



1146
1147
1148
 
# File 'ext/postgres.c', line 1146

static VALUE
pgconn_db(obj)
VALUE obj;

#endcopy ⇒ Object

Waits until the backend completes the copying. You should call this method after #putline or #getline. Returns nil on success; raises an exception otherwise.



1065
1066
1067
 
# File 'ext/postgres.c', line 1065

static VALUE
pgconn_endcopy(obj)
VALUE obj;

#error ⇒ Object

Returns the error message about connection.



1219
1220
1221
 
# File 'ext/postgres.c', line 1219

static VALUE
pgconn_error(obj)
VALUE obj;

#escape ⇒ Object

Returns a SQL-safe version of the String str. Unlike #quote, does not wrap the String in ‘…’.



456
457
458
 
# File 'ext/postgres.c', line 456

static VALUE
pgconn_escape(self, string)
VALUE self;

#escape_bytea(obj) ⇒ Object

Escapes binary data for use within an SQL command with the type bytea.

Certain byte values must be escaped (but all byte values may be escaped) when used as part of a bytea literal in an SQL statement. In general, to escape a byte, it is converted into the three digit octal number equal to the octet value, and preceded by two backslashes. The single quote (‘) and backslash () characters have special alternative escape sequences. #escape_bytea performs this operation, escaping only the minimally required bytes.

See the PostgreSQL documentation on PQescapeBytea for more information.



526
527
528
 
# File 'ext/postgres.c', line 526

static VALUE
pgconn_escape_bytea(self, obj)
VALUE self;

#exec(sql, *bind_values) ⇒ Object

Sends SQL query request specified by sql to the PostgreSQL. Returns a PGresult instance on success. On failure, it raises a PGError exception.

bind_values represents values for the PostgreSQL bind parameters found in the sql. PostgreSQL bind parameters are presented as $1, $1, $2, etc.



721
722
723
 
# File 'ext/postgres.c', line 721

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

#get_notify ⇒ Object

Returns an array of the unprocessed notifiers. If there is no unprocessed notifier, it returns nil.



911
912
913
 
# File 'ext/postgres.c', line 911

static VALUE
pgconn_get_notify(obj)
VALUE obj;

#getline ⇒ Object

Reads a line from the backend server into internal buffer. Returns nil for EOF, 0 for success, 1 for buffer overflowed. You need to ensure single “.” from backend to confirm transmission completion. The sample program psql.rb (see source for postgres) treats this copy protocol right.



1029
1030
1031
 
# File 'ext/postgres.c', line 1029

static VALUE
pgconn_getline(obj)
VALUE obj;

#host ⇒ Object

Returns the connected server name.



1117
1118
1119
 
# File 'ext/postgres.c', line 1117

static VALUE
pgconn_host(obj)
VALUE obj;

#insert_table(table, values) ⇒ Object

Inserts contents of the values Array into the table.



951
952
953
 
# File 'ext/postgres.c', line 951

static VALUE
pgconn_insert_table(obj, table, values)
VALUE obj, table, values;

#lo_create([mode]) ⇒ PGlarge Also known as: locreate

Returns a PGlarge instance on success. On failure, it raises PGError exception. (See #lo_open for information on mode.)

Returns:



2051
2052
2053
 
# File 'ext/postgres.c', line 2051

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

#lo_export(oid, file) ⇒ Object Also known as: loexport

Saves a large object of oid to a file.



2025
2026
2027
 
# File 'ext/postgres.c', line 2025

static VALUE
pgconn_loexport(obj, lo_oid,filename)
VALUE obj, lo_oid, filename;

#lo_import(file) ⇒ PGlarge Also known as: loimport

Import a file to a large object. Returns a PGlarge instance on success. On failure, it raises a PGError exception.

Returns:



2002
2003
2004
 
# File 'ext/postgres.c', line 2002

static VALUE
pgconn_loimport(obj, filename)
VALUE obj, filename;

#lo_open(oid, [mode]) ⇒ PGlarge Also known as: loopen

Open a large object of oid. Returns a PGlarge instance on success. The mode argument specifies the mode for the opened large object, which is either INV_READ, or INV_WRITE.

  • If mode On failure, it raises a PGError exception.

  • If mode is omitted, the default is INV_READ.

Returns:



2088
2089
2090
 
# File 'ext/postgres.c', line 2088

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

#lo_unlink(oid) ⇒ Object Also known as: lounlink

Unlinks (deletes) the postgres large object of oid.



2127
2128
2129
 
# File 'ext/postgres.c', line 2127

static VALUE
pgconn_lounlink(obj, lo_oid)
VALUE obj, lo_oid;

#on_notice {|message| ... } ⇒ Object

Notice and warning messages generated by the server are not returned by the query execution functions, since they do not imply failure of the query. Instead they are passed to a notice handling function, and execution continues normally after the handler returns. The default notice handling function prints the message on stderr, but the application can override this behavior by supplying its own handling function.

Yields:

  • (message) 


1098
1099
1100
 
# File 'ext/postgres.c', line 1098

static VALUE
pgconn_on_notice(self)
VALUE self;

#options ⇒ Object

Returns backend option string.



1161
1162
1163
 
# File 'ext/postgres.c', line 1161

static VALUE
pgconn_options(obj)
VALUE obj;

#port ⇒ Object

Returns the connected server port number.



1132
1133
1134
 
# File 'ext/postgres.c', line 1132

static VALUE
pgconn_port(obj)
VALUE obj;

#protocol_version ⇒ Integer

The 3.0 protocol will normally be used when communicating with PostgreSQL 7.4 or later servers; pre-7.4 servers support only protocol 2.0. (Protocol 1.0 is obsolete and not supported by libpq.)

Returns:

  • (Integer) 


1292
1293
1294
 
# File 'ext/postgres.c', line 1292

static VALUE
pgconn_protocol_version(obj)
VALUE obj;

#putline ⇒ Object

Sends the string to the backend server. Users must send a single “.” to denote the end of data transmission.



1011
1012
1013
 
# File 'ext/postgres.c', line 1011

static VALUE
pgconn_putline(obj, str)
VALUE obj, str;

#query(sql, *bind_values) ⇒ Object

Sends SQL query request specified by sql to the PostgreSQL. Returns an Array as the resulting tuple on success. On failure, it returns nil, and the error details can be obtained by #error.

bind_values represents values for the PostgreSQL bind parameters found in the sql. PostgreSQL bind parameters are presented as $1, $1, $2, etc.



880
881
882
 
# File 'ext/postgres.c', line 880

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

#quote(obj) ⇒ Object #quote(obj) {|obj| ... } ⇒ Object #format(obj) ⇒ Object #format(obj) {|obj| ... } ⇒ Object Also known as: format

If obj is a Number, String, Array, nil, true, or false then #quote returns a String representation of that object safe for use in PostgreSQL.

If obj is not one of the above classes and a block is supplied to #quote, the block is invoked, passing along the object. The return value from the block is returned as a string.

If obj is not one of the recognized classes andno block is supplied, a PGError is raised.

Overloads:

  • #quote(obj) {|obj| ... } ⇒ Object

    Yields:

    • (obj)
  • #format(obj) {|obj| ... } ⇒ Object

    Yields:

    • (obj) 


336
337
338
 
# File 'ext/postgres.c', line 336

static VALUE
pgconn_quote(self, obj)
VALUE self, obj;

#quote_ident(str) ⇒ Object

Returns a SQL-safe identifier.



404
405
406
 
# File 'ext/postgres.c', line 404

static VALUE
pgconn_s_quote_ident(self, string)
VALUE self;

#reset ⇒ Object

Resets the backend connection. This method closes the backend connection and tries to re-connect.



653
654
655
 
# File 'ext/postgres.c', line 653

static VALUE
pgconn_reset(obj)
VALUE obj;

#select_one(query, *bind_values) ⇒ Object

Return the first row of the query results. Equivalent to conn.query(query, *bind_values).first



1520
1521
1522
 
# File 'ext/postgres.c', line 1520

static VALUE
pgconn_select_one(argc, argv, self)
int argc;

#select_value(query, *bind_values) ⇒ Object

Return the first value of the first row of the query results. Equivalent to conn.query(query, *bind_values).first.first



1539
1540
1541
 
# File 'ext/postgres.c', line 1539

static VALUE
pgconn_select_value(argc, argv, self)
int argc;

#select_values(query, *bind_values) ⇒ Object

Equivalent to conn.query(query, *bind_values).flatten



1557
1558
1559
 
# File 'ext/postgres.c', line 1557

static VALUE
pgconn_select_values(argc, argv, self)
int argc;

#server_version ⇒ Integer

The number is formed by converting the major, minor, and revision numbers into two-decimal-digit numbers and appending them together. For example, version 7.4.2 will be returned as 70402, and version 8.1 will be returned as 80100 (leading zeroes are not shown). Zero is returned if the connection is bad.

Returns:

  • (Integer) 


1305
1306
1307
 
# File 'ext/postgres.c', line 1305

static VALUE
pgconn_server_version(obj)
VALUE obj;

#set_client_encoding(encoding) ⇒ Object

Sets the client encoding to the encoding String.



1371
1372
1373
 
# File 'ext/postgres.c', line 1371

static VALUE
pgconn_set_client_encoding(obj, str)
VALUE obj, str;

#status ⇒ Object

MISSING: documentation



1206
1207
1208
 
# File 'ext/postgres.c', line 1206

static VALUE
pgconn_status(obj)
VALUE obj;

#trace ⇒ Object

TODO broken for ruby 1.9

call-seq:
   conn.trace( port )

Enables tracing message passing between backend.
The trace message will be written to the _port_ object,
which is an instance of the class +File+.



1236
1237
1238
 
# File 'ext/postgres.c', line 1236

static VALUE
pgconn_trace(obj, port)
VALUE obj, port;

#transaction_status ⇒ Object

returns one of the following statuses:

PQTRANS_IDLE    = 0 (connection idle)
PQTRANS_ACTIVE  = 1 (command in progress)
PQTRANS_INTRANS = 2 (idle, within transaction block)
PQTRANS_INERROR = 3 (idle, within failed transaction)
PQTRANS_UNKNOWN = 4 (cannot determine status)

See the PostgreSQL documentation on PQtransactionStatus for more information.



1277
1278
1279
 
# File 'ext/postgres.c', line 1277

static VALUE
pgconn_transaction_status(obj)
VALUE obj;

#tty ⇒ Object

Returns the connected pgtty.



1176
1177
1178
 
# File 'ext/postgres.c', line 1176

static VALUE
pgconn_tty(obj)
VALUE obj;

#unescape_bytea(obj) ⇒ Object

Converts an escaped string representation of binary data into binary data — the reverse of #escape_bytea. This is needed when retrieving bytea data in text format, but not when retrieving it in binary format.

See the PostgreSQL documentation on PQunescapeBytea for more information.



557
558
559
 
# File 'ext/postgres.c', line 557

static VALUE
pgconn_s_unescape_bytea(self, obj)
VALUE self, obj;

#untrace ⇒ Object

Disables the message tracing.



1256
1257
1258
 
# File 'ext/postgres.c', line 1256

static VALUE
pgconn_untrace(obj)
VALUE obj;

#user ⇒ Object

Returns the authenticated user name.



1191
1192
1193
 
# File 'ext/postgres.c', line 1191

static VALUE
pgconn_user(obj)
VALUE obj;