pglarge – Large Objects

class pg.pglarge

Objects that are instances of the class pglarge are used to handle all the requests concerning a PostgreSQL large object. These objects embed and hide all the “recurrent” variables (object OID and connection), exactly in the same way pgobject instances do, thus only keeping significant parameters in function calls. The pglarge object keeps a reference to the pgobject used for its creation, sending requests though with its parameters. Any modification but dereferencing the pgobject will thus affect the pglarge object. Dereferencing the initial pgobject is not a problem since Python won’t deallocate it before the pglarge object dereferences it. All functions return a generic error message on call error, whatever the exact error was. The error attribute of the object allows to get the exact error message.

See also the PostgreSQL programmer’s guide for more information about the large object interface.

open – open a large object

pglarge.open(mode)

Open a large object

Parameters:

mode (int) – open mode definition

Return type:

None

Raises:
  • TypeError – invalid connection, bad parameter type, or too many parameters
  • IOError – already opened object, or open error

This method opens a large object for reading/writing, in the same way than the Unix open() function. The mode value can be obtained by OR-ing the constants defined in the pg module (INV_READ, INV_WRITE).

close – close a large object

pglarge.close()

Close a large object

Return type:

None

Raises:
  • TypeError – invalid connection
  • TypeError – too many parameters
  • IOError – object is not opened, or close error

This method closes a previously opened large object, in the same way than the Unix close() function.

size – get the large object size

pglarge.size()

Return the large object size

Returns:

the large object size

Return type:

int

Raises:
  • TypeError – invalid connection or invalid object
  • TypeError – too many parameters
  • IOError – object is not opened, or seek/tell error

This (composite) method allows to get the size of a large object. It was implemented because this function is very useful for a web interfaced database. Currently, the large object needs to be opened first.

export – save a large object to a file

pglarge.export(name)

Export a large object to a file

Parameters:

name (str) – file to be created

Return type:

None

Raises:
  • TypeError – invalid connection or invalid object, bad parameter type, or too many parameters
  • IOError – object is not closed, or export error

This methods allows to dump the content of a large object in a very simple way. The exported file is created on the host of the program, not the server host.

Object attributes

pglarge objects define a read-only set of attributes that allow to get some information about it. These attributes are:

pglarge.oid

the OID associated with the object (int)

pglarge.pgcnx

the pgobject associated with the object

pglarge.error

the last warning/error message of the connection

Warning

In multi-threaded environments, pglarge.error may be modified by another thread using the same pgobject. Remember these object are shared, not duplicated. You should provide some locking to be able if you want to check this. The pglarge.oid attribute is very interesting, because it allows you to reuse the OID later, creating the pglarge object with a pgobject.getlo() method call.