Class: PGconn

Class | PGconn
In: | postgres.c
Parent: | Object

The class to access PostgreSQL database.

For example, to send query to the database on the localhost:

       require 'postgres'
       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

async_exec async_query client_encoding close db endcopy error escape escape_bytea exec finish get_notify getline host insert_table lastval lo_create lo_export lo_import lo_open lo_unlink locreate loexport loimport loopen lounlink new new on_notice options port protocol_version putline query quote reset select_one select_value select_values server_version set_client_encoding status trace transaction_status translate_results= tty unescape_bytea untrace user

### Constants

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

### Public Class methods

PGconn.escape( str )

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

PGconn.escape_bytea( obj )

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.

PGconn.quote( obj )
PGconn.quote( obj ) { |obj| ... }
PGconn.format( obj )
PGconn.format( obj ) { |obj| ... }

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.

PGconn.translate_results = boolean

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

PGconn.unescape_bytea( obj )

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

conn.async_exec( sql )

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.

conn.async_query(sql)

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.

conn.client_encoding() → String

Returns the client encoding as a String.

conn.close

Closes the backend connection.

conn.db()

Returns the connected database name.

conn.endcopy()

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

conn.error()

Returns the error message about connection.

conn.exec(sql, *bind_values)

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

conn.get_notify()

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

conn.getline()

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.

conn.host()

Returns the connected server name.

conn.insert_table( table, values )

Inserts contents of the values Array into the table.

conn.lastval → Integer

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.

conn.lo_create( [mode] ) → PGlarge

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

conn.lo_export( oid, file )

Saves a large object of oid to a file.

conn.lo_import(file) → PGlarge

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

conn.lo_open( oid, [mode] ) → PGlarge

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

conn.lo_unlink( oid )

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

conn.on_notice {|message| ... }

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.

conn.options()

Returns backend option string.

conn.port()

Returns the connected server port number.

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

conn.putline()

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

conn.query(sql, *bind_values)

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.

conn.reset()

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

conn.select_one(query, *bind_values)

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

conn.select_value(query, *bind_values)

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

conn.select_values(query, *bind_values)

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

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

conn.set_client_encoding( encoding )

Sets the client encoding to the encoding String.

conn.status()

MISSING: documentation

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

conn.transaction_status()

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.

conn.tty()

Returns the connected pgtty.

conn.untrace()

Disables the message tracing.

conn.user()

Returns the authenticated user name.

[Validate]