Class PGconn
In: ext/postgres.c
Parent: Object

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.

Methods

Constants

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

Public Class methods

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

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.

PGconn.open(connection_hash) → PGconn
PGconn.open(connection_string) → PGconn
PGconn.open(host, port, options, tty, dbname, login, passwd) → PGconn
host:server hostname
port:server port number
options:backend options (String)
tty:tty to print backend debug message (ignored in newer versions of PostgreSQL) (String)
dbname:connecting database name
login:login user name
passwd:login password

On failure, it raises a PGError exception.

PGconn.open(connection_hash) → PGconn
PGconn.open(connection_string) → PGconn
PGconn.open(host, port, options, tty, dbname, login, passwd) → PGconn
host:server hostname
port:server port number
options:backend options (String)
tty:tty to print backend debug message (ignored in newer versions of PostgreSQL) (String)
dbname:connecting database name
login:login user name
passwd:login password

On failure, it raises a PGError exception.

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.

Returns a SQL-safe identifier.

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

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.

Public Instance methods

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.

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.

Returns the client encoding as a String.

Closes the backend connection.

Returns the connected database name.

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

Returns the error message about connection.

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

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.

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.

finish()

Alias for close

format(p1)

Alias for quote

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

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.

Returns the connected server name.

Inserts contents of the values Array into the table.

Returns the sequence value returned by the last call to the PostgreSQL function nextval(sequence_name). Equivalent to conn.query(‘select lastval()’).first.first.

This functionality is only available with PostgreSQL 8.1 and newer. See the PostgreSQL documentation on lastval for more information.

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

Saves a large object of oid to a file.

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

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.

Unlinks (deletes) the postgres large object of oid.

locreate(...)

Alias for lo_create

loexport(p1, p2)

Alias for lo_export

loimport(p1)

Alias for lo_import

loopen(...)

Alias for lo_open

lounlink(p1)

Alias for lo_unlink

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.

Returns backend option string.

Returns the connected server port number.

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.)

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

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.

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.

Returns a SQL-safe identifier.

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

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

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

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

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.

Sets the client encoding to the encoding String.

MISSING: documentation

TODO broken for ruby 1.9

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

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.

Returns the connected pgtty.

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.

Disables the message tracing.

Returns the authenticated user name.

[Validate]