Class: PGconn

The class to access PostgreSQL database. All other functionality of libpq save the large object to a file.

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

   require "postgres"
   conn = PGconn.connect("localhost", 5432, "", "", "test1")
   res  = conn.exec("select * from a;")

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

Public Class methods

connect(...)

See new.

PGconn.escape( str )

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

For more information, see PQescapestring which is called internally by this method.

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.

For more information, see PQescapeBytea which is called internally by this method.

new(...)

See new.

PGconn.connect( pghost, pgport, pgoptions, pgtty, dbname, login, passwd ) => conn
PGconn.new( pghost, pgport, pgoptions, pgtty, dbname, login, passwd ) => conn
PGconn.setdb( pghost, pgport, pgoptions, pgtty, dbname, login, passwd ) => conn
PGconn.setdblogin( pghost, pgport, pgoptions, pgtty, dbname, login, passwd ) => conn

pghost:	server hostname (String)
pgport:	server port number (Integer)
pgoptions:	backend options (String)
pgtty:	tty to print backend debug message (ignored in newer versions of PostgreSQL) (String)
dbname:	connecting database name (String)
login:	login user name (String)
passwd:	login password (String)

On failure, it raises a PGError exception.

PGConn.quote( obj )
PGConn.quote( 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 and no block is supplied, a PGError is raised.

setdb(...)

See new.

setdblogin(...)

See new.

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 )

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

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

Returns the next notification from a list of unhandled notification messages received from the server. It returns a null pointer if there are no pending notifications. Once a notification is returned from PQnotifies, it is considered handled and will be removed from the list of notifications.

For more information, see PQnotifies which is called internally by this method.

conn.options()

Returns backend option string.

conn.port()

Returns the connected server port number.

conn.putline()

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

conn.query( sql )

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.

conn.reset()

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

conn.set_client_encoding( encoding )

Sets the client encoding to the encoding String.

conn.status()

Returns the status of the connection. May be either: