# PyGreSQL - Python Interface

## Author

Written by D'Arcy J.M. Cain (darcy@druid.net). Based heavily on code written by Pascal Andre andre@chimay.via.ecp.fr. Copyright © 1995, Pascal Andre. Further modifications Copyright © 1997-2000 by D'Arcy J.M. Cain.

## Installation

- Note that if you are using the DB-API module you must also install `mxDateTime` from http://starship.python.net/~lemburg/mxDateTime.html.

- Also, check out `setup.py` for an alternate method of installing the package using Python's Distutils.

You have two options. You can compile PyGreSQL as a stand-alone module or you can build it into the Python interpreter.

## General

- You must first have installed Python and PostgreSQL on your system. The header files and developer's libraries for both Python and PostgreSQL must be installed on your system before you can build PyGreSQL. If you built both Python and PostgreSQL from source, you should be fine. If your system uses some package mechanism (such as RPM or `NetBSD` packages), then you probably need to install packages such as Python-devel in addition to the Python package.

- PyGreSQL is implemented as three parts, a C module labeled `_pg` and two Python wrappers called `pg.py` and `pgdb.py`. This changed between 2.1 and 2.2 and again in 3.0. These changes should not affect any existing programs but the installation is slightly different.

- Download and unpack the PyGreSQL tarball if you haven't already done so.

## Stand-alone

- In the directory containing `pgmodule.c`, run the following command

      cc -fpic -shared -o _pg.so -I[pyInc] -I[pgInc] -L[pgLib] -lpq pgmodule.c

  where:

  - [pyInc] = path of the Python include (usually `Python.h`)

  - [pgInc] = path of the PostgreSQL include (usually `postgres.h`)

  - [pgLib] = path of the PostgreSQL libraries (usually `libpq.so` or `libpq.a`)

  Some options may be added to this line:

  - `-DNO_DEF_VAR` - no default variables support

  - `-DNO_DIRECT` - no direct access methods

  - `-DNO_LARGE` - no large object support

  - `-DNO_SNPRINTF` - if running a system with no snprintf call

  - `-DNO_PQSOCKET` - if running an older PostgreSQL

  On some systems you may need to include `-lcrypt` in the list of libraries to make it compile. Define `DNO_PQSOCKET` if you are using a version of PostgreSQL before 6.4 that does not have the `PQsocket` function. The other options will be described in the next sections.

- Test the new module. Something like the following should work.

      $ python

      >>> import _pg
      >>> db = _pg.connect('thilo', 'localhost')
      >>> db.query("INSERT INTO test VALUES ('ping', 'pong');")
      18304
      >>> db.query("SELECT * FROM test;")
       eins | zwei
      ------+------
       ping | pong
      (1 row)

- Finally, move the `_pg.so`, `pg.py`, and `pgdb.py` to a directory in your `PYTHONPATH`. A good place would be `/usr/lib/python1.5/site-python` if your Python modules are in `/usr/lib/python1.5`.

## Built-in to python interpreter

- Find the directory where your `Setup` file lives (usually `??/Modules`) in the Python source hierarchy and copy or symlink the `pgmodule.c` file there.

- Add the following line to your `Setup` file

      _pg  pgmodule.c -I[pgInc] -L[pgLib] -lpq # -lcrypt # needed on some systems

  where:

  - [pgInc] = path of the PostgreSQL include (usually `postgres.h`)

  - [pgLib] = path of the PostgreSQL libraries (usually `libpq.so` or `libpq.a`)

  Some options may be added to this line:

  - `-DNO_DEF_VAR` - no default variables support

  - `-DNO_DIRECT` - no direct access methods

  - `-DNO_LARGE` - no large object support

  - `-DNO_SNPRINTF` - if running a system with no snprintf call

  - `-DNO_PQSOCKET` - if running an older PostgreSQL

  Define `-DNO_PQSOCKET` if you are using a version of PostgreSQL before 6.4 that does not have the `PQsocket` function. The other options will be described in the next sections.

- If you want a shared module, make sure that the `*shared*` key word is uncommented and add the above line below it. You used to need to install your shared modules with `make sharedinstall` but this no longer seems to be true.

- Copy `pg.py` to the lib directory where the rest of your modules are. For example, that's `/usr/local/lib/Python` on my system.

- Rebuild Python from the root directory of the Python source hierarchy by running

      make -f Makefile.pre.in boot
      make && make install

- For more details read the documentation at the top of `Makefile.pre.in`

]]>

You may either choose to use the old mature interface provided by the `pg` module or otherwise the newer `pgdb` interface compliant with the DB-API 2.0 specification developed by the Python DB-SIG.

Here we describe only the older `pg` API. As long as PyGreSQL does not contain a description of the DB-API you should read about the API at http://www.python.org/topics/database/DatabaseAPI-2.0.html.

A tutorial-like introduction to the DB-API can be found at http://www2.linuxjournal.com/lj-issues/issue49/2605.html

## The `pg` Module

The `pg` module defines three objects:

- `pgobject`, which handles the connection and all the requests to the database,

- `pglargeobject`, which handles all the accesses to PostgreSQL large objects, and

- `pgqueryobject` that handles query results.

If you want to see a simple example of the use of some of these functions, see http://www.druid.net/rides where you can find a link at the bottom to the actual Python code for the page.

## Constants

Some constants are defined in the `pg` module dictionary. They are intended to be used as a parameters for methods calls. You should refer to the libpq description (libpq) for more information about them. These constants are:

`INV_READ`

`INV_WRITE`

- large objects access modes, used by `(pgobject.)locreate` and `(pglarge.)open`.

`SEEK_SET`

`SEEK_CUR`

`SEEK_END`

- positional flags, used by `(pglarge.)seek`.

`version`

`__version__`

- constants that give the current version

## `pg` Module Functions

`pg` module defines only a few methods that allow to connect to a database and to define default variables that override the environment variables used by PostgreSQL.

These default variables were designed to allow you to handle general connection parameters without heavy code in your programs. You can prompt the user for a value, put it in the default variable, and forget it, without having to modify your environment. The support for default variables can be disabled by setting the `-DNO_DEF_VAR` option in the Python `Setup` file. Methods relative to this are specified by the tag [DV].

All variables are set to None at module initialization, specifying that standard environment variables should be used.

connect

PYGRESQL - Connection Management

connect

open a connection to the database server

    connect(dbname, host, port, opt, tty, user, passwd)

### Parameters

`dbname`

- Name of connected database (string/None).

`host`

- Name of the server host (string/None).

`port`

- Port used by the database server (integer/-1).

`opt`

- Options for the server (string/None).

`tty`

- File or tty for optional debug output from backend (string/None).

`user`

- PostgreSQL user (string/None).

`passwd`

- Password for user (string/None).

### Return Type

`pgobject`

- If successful, an object handling a database connection is returned.

### Exceptions

`TypeError`

- Bad argument type, or too many arguments.

`SyntaxError`

- Duplicate argument definition.

`pg.error`

- Some error occurred during `pg` connection definition.

(plus all exceptions relative to object allocation)

### Description

This method opens a connection to a specified database on a given PostgreSQL server. You can use key words here, as described in the Python tutorial. The names of the key words are the name of the parameters given in the syntax line. For a precise description of the parameters, please refer to the PostgreSQL user manual.

### Examples

    import pg

    con1 = pg.connect('testdb', 'myhost', 5432, None, None, 'bob', None)
    con2 = pg.connect(dbname='testdb', host='localhost', user='bob')

get_defhost

PYGRESQL - Connection Management

get_defhost

get default host name [DV]

    get_defhost()

### Parameters

none

### Return Type

string or None

- Default host specification

### Exceptions

`SyntaxError`

- Too many arguments.

### Description

`get_defhost()` returns the current default host specification, or None if the environment variables should be used. Environment variables will not be looked up.

set_defhost

PYGRESQL - Connection Management

set_defhost

set default host name [DV]

    set_defhost(host)

### Parameters

`host`

- New default host (string/None).

### Return Type

string or None

- Previous default host specification.

### Exceptions

`TypeError`

- Bad argument type, or too many arguments.

### Description

`set_defhost()` sets the default host value for new connections. If None is supplied as parameter, environment variables will be used in future connections. It returns the previous setting for default host.

get_defport

PYGRESQL - Connection Management

get_defport

get default port [DV]

    get_defport()

### Parameters

none

### Return Type

integer or None

- Default port specification

### Exceptions

`SyntaxError`

- Too many arguments.

### Description

`get_defport()` returns the current default port specification, or None if the environment variables should be used. Environment variables will not be looked up.

set_defport

PYGRESQL - Connection Management

set_defport

set default port [DV]

    set_defport(port)

### Parameters

`port`

- New default host (integer/-1).

### Return Type

integer or None

- Previous default port specification.

### Exceptions

`TypeError`

- Bad argument type, or too many arguments.

### Description

`set_defport()` sets the default port value for new connections. If -1 is supplied as parameter, environment variables will be used in future connections. It returns the previous setting for default port.

get_defopt

PYGRESQL - Connection Management

get_defopt

get default options specification [DV]

    get_defopt()

### Parameters

none

### Return Type

string or None

- Default options specification

### Exceptions

`SyntaxError`

- Too many arguments.

### Description

`get_defopt()` returns the current default connection options specification, or None if the environment variables should be used. Environment variables will not be looked up.

set_defopt

PYGRESQL - Connection Management

set_defopt

set default options specification [DV]

    set_defopt(options)

### Parameters

`options`

- New default connection options (string/None).

### Return Type

string or None

- Previous default opt specification.

### Exceptions

`TypeError`

- Bad argument type, or too many arguments.

### Description

`set_defopt()` sets the default connection options value for new connections. If None is supplied as parameter, environment variables will be used in future connections. It returns the previous setting for default options.

get_deftty

PYGRESQL - Connection Management

get_deftty

get default connection debug terminal specification [DV]

    get_deftty()

### Parameters

none

### Return Type

string or None

- Default debug terminal specification

### Exceptions

`SyntaxError`

- Too many arguments.

### Description

`get_deftty()` returns the current default debug terminal specification, or None if the environment variables should be used. Environment variables will not be looked up.

set_deftty

PYGRESQL - Connection Management

set_deftty

set default connection debug terminal specification [DV]

    set_deftty(terminal)

### Parameters

`terminal`

- New default debug terminal (string/None).

### Return Type

string or None

- Previous default debug terminal specification.

### Exceptions

`TypeError`

- Bad argument type, or too many arguments.

### Description

`set_deftty()` sets the default terminal value for new connections. If None is supplied as parameter, environment variables will be used in future connections. It returns the previous setting for default terminal.

get_defbase

PYGRESQL - Connection Management

get_defbase

get default database name specification [DV]

    get_defbase()

### Parameters

none

### Return Type

string or None

- Default debug database name specification

### Exceptions

`SyntaxError`

- Too many arguments.

### Description

`get_defbase()` returns the current default database name specification, or None if the environment variables should be used. Environment variables will not be looked up.

set_defbase

PYGRESQL - Connection Management

set_defbase

set default database name specification [DV]

    set_defbase(database)

### Parameters

`database`

- New default database name (string/None).

### Return Type

string or None

- Previous default database name specification.

### Exceptions

`TypeError`

- Bad argument type, or too many arguments.

### Description

`set_defbase()` sets the default database name for new connections. If None is supplied as parameter, environment variables will be used in future connections. It returns the previous setting for default database name.

## Connection Object: `pgobject`

This object handles a connection to the PostgreSQL database. It embeds and hides all the parameters that define this connection, leaving just really significant parameters in function calls.

Some methods give direct access to the connection socket. They are specified by the tag [DA]. Do not use them unless you really know what you are doing. If you prefer disabling them, set the `-DNO_DIRECT` option in the Python `Setup` file.

Some other methods give access to large objects. if you want to forbid access to these from the module, set the `-DNO_LARGE` option in the Python `Setup` file. These methods are specified by the tag [LO].

Every `pgobject` defines a set of read-only attributes that describe the connection and its status. These attributes are:

host

- the host name of the server (string)

port

- the port of the server (integer)

db

- the selected database (string)

options

- the connection options (string)

tty

- the connection debug terminal (string)

user

- user name on the database system (string)

status

- the status of the connection (integer: 1 - OK, 0 - bad)

error

- the last warning/error message from the server (string)

query

PYGRESQL - Query

query

execute a SQL command

    query(command)

### Parameters

`command`

- SQL command (string).

### Return Type

`pgqueryobject` or None

- Result values.

### Exceptions

`TypeError`

- Bad argument type, or too many arguments.

`ValueError`

- Empty SQL query.

`pg.error`

- Error during query processing, or invalid connection.

### Description

`query()` method sends a SQL query to the database. If the query is an insert statement, the return value is the OID of the newly inserted row. If it is otherwise a query that does not return a result (i.e., is not a some kind of `SELECT` statement), it returns None. Otherwise, it returns a `pgqueryobject` that can be accessed via the `getresult()` or `dictresult()` methods or simply printed.

reset

PYGRESQL - Reset

reset

reset the connection

    reset()

### Parameters

none

### Return Type

none

### Exceptions

`TypeError`

- Too many (any) arguments.

### Description

`reset()` method resets the current database.

close

PYGRESQL - Close

close

close the database connection

    close()

### Parameters

none

### Return Type

none

### Exceptions

`TypeError`

- Too many (any) arguments.

### Description

`close()` method closes the database connection. The connection will be closed in any case when the connection is deleted but this allows you to explicitly close it. It is mainly here to allow the DB-SIG API wrapper to implement a close function.

fileno

PYGRESQL - Fileno

fileno

return the socket used to connect to the database

    fileno()

### Parameters

none

### Return Type

socket id

- The underlying socket id used to connect to the database.

### Exceptions

`TypeError`

- Too many (any) arguments.

### Description

`fileno()` method returns the underlying socket id used to connect to the database. This is useful for use in `select` calls, etc.

getnotify

PYGRESQL - Getnotify

getnotify

get the last notify from the server

    getnotify()

### Parameters

none

### Return Type

tuple, None

- Last notify from server

### Exceptions

`TypeError`

- Too many (any) arguments.

`pg.error`

- Invalid connection.

### Description

`getnotify()` method tries to get a notify from the server (from the SQL statement `NOTIFY`). If the server returns no notify, the methods returns None. Otherwise, it returns a tuple (couple) `(relname, pid)`, where `relname` is the name of the notify and `pid` the process id of the connection that triggered the notify. Remember to do a listen query first otherwise `getnotify` will always return None.

inserttable

PYGRESQL - Inserttable

inserttable

insert a list into a table

    inserttable(table, values)

### Parameters

`table`

- The table name (string).

`values`

- The list of rows values to insert (list).

### Return Type

none

### Exceptions

`TypeError`

- Bad argument type or too many (any) arguments.

`pg.error`

- Invalid connection.

### Description

`inserttable()` method allows to quickly insert large blocks of data in a table: it inserts the whole values list into the given table. The list is a list of tuples/lists that define the values for each inserted row. The rows values may contain string, integer, long or double (real) values. Be very careful: this method does not type-check the fields according to the table definition; it just look whether or not it knows how to handle such types.

putline

PYGRESQL - Putline

putline

write a line to the server socket [DA]

    putline(line)

### Parameters

`line`

- Line to be written (string).

### Return Type

none

### Exceptions

`TypeError`

- Bad argument type or too many (any) arguments.

`pg.error`

- Invalid connection.

### Description

`putline()` method allows to directly write a string to the server socket.

getline

PYGRESQL - Getline

getline

get a line from server socket [DA]

    getline()

### Parameters

none

### Return Type

string

- The line read.

### Exceptions

`TypeError`

- Bad argument type or too many (any) arguments.

`pg.error`

- Invalid connection.

### Description

`getline()` method allows to directly read a string from the server socket.

endcopy

PYGRESQL - Endcopy

endcopy

synchronize client and server [DA]

    endcopy()

### Parameters

none

### Return Type

none

### Exceptions

`TypeError`

- Bad argument type or too many (any) arguments.

`pg.error`

- Invalid connection.

### Description

The use of direct access methods may desynchronize client and server. This method ensure that client and server will be synchronized.

locreate

PYGRESQL - Locreate

locreate

create a large object in the database [LO]

    locreate(mode)

### Parameters

`mode`

- Large object create mode.

### Return Type

`pglarge`

- Object handling the PostgreSQL large object.

### Exceptions

`TypeError`

- Bad argument type or too many arguments.

`pg.error`

- Invalid connection, or creation error.

### Description

`locreate()` method creates a large object in the database. The mode can be defined by OR-ing the constants defined in the pg module (`INV_READ` and `INV_WRITE`).

getlo

PYGRESQL - Getlo

getlo

build a large object from given OID [LO]

    getlo(oid)

### Parameters

`oid`

- OID of the existing large object (integer).

### Return Type

`pglarge`

- Object handling the PostgreSQL large object.

### Exceptions

`TypeError`

- Bad argument type or too many arguments.

`pg.error`

- Invalid connection.

### Description

`getlo()` method allows to reuse a formerly created large object through the `pglarge` interface, providing the user has its OID.

loimport

PYGRESQL - Loimport

loimport

import a file to a PostgreSQL large object [LO]

    loimport(filename)

### Parameters

`filename`

- The name of the file to be imported (string).

### Return Type

`pglarge`

- Object handling the PostgreSQL large object.

### Exceptions

`TypeError`

- Bad argument type or too many arguments.

`pg.error`

- Invalid connection, or error during file import.

### Description

`loimport()` method allows to create large objects in a very simple way. You just give the name of a file containing the data to be use.

## Database Wrapper Class: `DB`

`pg` module contains a class called `DB`. All `pgobject` methods are included in this class also. A number of additional `DB` class methods are described below. The preferred way to use this module is as follows (See description of the initialization method below.):

    import pg

    db = pg.DB(...)

    for r in db.query(
        "SELECT foo,bar
           FROM foo_bar_table
          WHERE foo !~ bar"
        ).dictresult():

        print '%(foo)s %(bar)s' % r

The following describes the methods and variables of this class.

The `DB` class is initialized with the same arguments as the `pg.connect` method. It also initializes a few internal variables. The statement `db = DB()` will open the local database with the name of the user just like `pg.connect()` does.

pkey

PYGRESQL - Pkey

pkey

return the primary key of a table

    pkey(table)

### Parameters

`table`

- name of table.

### Return Type

string

- Name of field which is the primary key of the table.

### Description

`pkey()` method returns the primary key of a table. Note that this raises an exception if the table does not have a primary key.

get_databases

PYGRESQL - Get_databases

get_databases

get list of databases in the system

    get_databases()

### Parameters

none

### Return Type

list

- List of databases in the system.

### Description

Although you can do this with a simple select, it is added here for convenience

get_tables

PYGRESQL - get_tables

get_tables

get list of tables in connected database

    get_tables()

### Parameters

none

### Return Type

list

- List of tables in connected database.

### Description

Although you can do this with a simple select, it is added here for convenience

get_attnames

PYGRESQL - Get_Attnames

get_attnames

return the attribute names of a table

    get_attnames(table)

### Parameters

`table`

- name of table.

### Return Type

dictionary

- The dictionary's keys are the attribute names, the values are the type names of the attributes.

### Description

Given the name of a table, digs out the set of attribute names and types.

get

PYGRESQL - Get

get

get a tuple from a database table

    get(table, arg, keyname)

### Parameters

`table`

- Name of table.

`arg`

- Either a dictionary or the value to be looked up.

`keyname`

- Name of field to use as key (optional).

### Return Type

dictionary

- A dictionary mapping attribute names to row values.

### Description

This method is the basic mechanism to get a single row. It assumes that the key specifies a unique row. If `keyname` is not specified then the primary key for the table is used. If `arg` is a dictionary then the value for the key is taken from it and it is modified to include the new values, replacing existing values where necessary. The OID is also put into the dictionary but in order to allow the caller to work with multiple tables, the attribute name is munged to make it unique. It consists of the string `oid_` followed by the name of the table.

insert

PYGRESQL - Insert

insert

insert a tuple into a database table

    insert(table, a)

### Parameters

`table`

- Name of table.

`a`

- A dictionary of values.

### Return Type

integer

- The OID of the newly inserted row.

### Description

This method inserts values into the table specified filling in the values from the dictionary. It then reloads the dictionary with the values from the database. This causes the dictionary to be updated with values that are modified by rules, triggers, etc.

Due to the way that this function works you will find inserts taking longer and longer as your table gets bigger. To overcome this problem simply add an index onto the OID of any table that you think may get large over time.

update

PYGRESQL - Update

update

update a database table

    update(table, a)

### Parameters

`table`

- Name of table.

`a`

- A dictionary of values.

### Return Type

integer

- The OID of the newly updated row.

### Description

Similar to insert but updates an existing row. The update is based on the OID value as munged by get. The array returned is the one sent modified to reflect any changes caused by the update due to triggers, rules, defaults, etc.

clear

PYGRESQL - Clear

clear

clear a database table

    clear(table, a)

### Parameters

`table`

- Name of table.

`a`

- A dictionary of values.

### Return Type

dictionary

- A dictionary with an empty row.

### Description

This method clears all the attributes to values determined by the types. Numeric types are set to 0, dates are set to `'today'` and everything else is set to the empty string. If the array argument is present, it is used as the array and any entries matching attribute names are cleared with everything else left unchanged.

delete

PYGRESQL - Delete

delete

delete a row from a table

    delete(table, a)

### Parameters

`table`

- Name of table.

`a`

- A dictionary of values.

### Return Type

none

### Description

This method deletes the row from a table. It deletes based on the OID as munged as described above.

## Query Result Object: `pgqueryobject`

getresult

PYGRESQL - Getresult

getresult

get the values returned by the query

    getresult()

### Parameters

none

### Return Type

list

- List of tuples.

### Exceptions

`SyntaxError`

- Too many arguments.

`pg.error`

- Invalid previous result.

### Description

`getresult()` method returns the list of the values returned by the query. More information about this result may be accessed using `listfields`, `fieldname` and `fieldnum` methods.

dictresult

PYGRESQL - Dictresult

dictresult

get the values returned by the query as a list of dictionaries

    dictresult()

### Parameters

none

### Return Type

list

- List of dictionaries.

### Exceptions

`SyntaxError`

- Too many arguments.

`pg.error`

- Invalid previous result.

### Description

`dictresult()` method returns the list of the values returned by the query with each tuple returned as a dictionary with the field names used as the dictionary index.

listfields

PYGRESQL - Listfields

listfields

list the fields names of the query result

    listfields()

### Parameters

none

### Return Type

list

- field names

### Exceptions

`SyntaxError`

- Too many arguments.

`pg.error`

- Invalid query result, or invalid connection.

### Description

`listfields()` method returns the list of field names defined for the query result. The fields are in the same order as the result values.

fieldname

PYGRESQL - Fieldname

fieldname

get field name by number

    fieldname(i)

### Parameters

`i`

- field number (integer).

### Return Type

string

- field name.

### Exceptions

`TypeError`

- Bad parameter type, or too many arguments.

`ValueError`

- Invalid field number.

`pg.error`

- Invalid query result, or invalid connection.

### Description

`fieldname()` method allows to find a field name from its rank number. It can be useful for displaying a result. The fields are in the same order than the result values.

fieldnum

PYGRESQL - Fieldnum

fieldnum

get field number by name

    fieldnum(name)

### Parameters

`name`

- field name (string).

### Return Type

integer

- field number (integer).

### Exceptions

`TypeError`

- Bad parameter type, or too many arguments.

`ValueError`

- Unknown field name.

`pg.error`

- Invalid query result, or invalid connection.

### Description

`fieldnum()` method returns a field number from its name. It can be used to build a function that converts result list strings to their correct type, using a hardcoded table definition. The number returned is the field rank in the result values list.

ntuples

PYGRESQL - Ntuples

ntuples

return the number of tuples in query object

    ntuples()

### Parameters

none

### Return Type

integer

- The number of tuples in query object.

### Exceptions

`SyntaxError`

- Too many arguments.

### Description

`ntuples()` method returns the number of tuples found in a query.

## Large Object: `pglarge`

This object handles all the request concerning a PostgreSQL large object. It embeds and hides all the recurrent variables (object OID and connection), exactly in the same way `pgobject`s do, thus only keeping significant parameters in function calls. It 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 will not deallocate it before the large object dereference 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.

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

oid

- the OID associated with the object

pgcnx

- the `pgobject` associated with the object

error

- the last warning/error message of the connection

In multithreaded environments, error may be modified by another thread using the same `pgobject`. Remember that these object are shared, not duplicated; you should provide some locking if you want to check for the error message in this situation. The OID attribute is very interesting because it allow you to reuse the OID later, creating the `pglarge` object with a `pgobject` `getlo()` method call.

See also largeobjects for more information about the PostgreSQL large object interface.

open

PYGRESQL - Open

open

open a large object

    open(mode)

### Parameters

`mode`

- open mode definition (integer).

### Return Type

none

### Exceptions

`TypeError`

- Bad parameter type, or too many arguments.

`IOError`

- Already opened object, or open error.

`pg.error`

- Invalid connection.

### Description

`open()` 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

PYGRESQL - Close

close

close the large object

    close()

### Parameters

none

### Return Type

none

### Exceptions

`SyntaxError`

- Too many arguments.

`IOError`

- Object is not opened, or close error.

`pg.error`

- Invalid connection.

### Description

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

read

PYGRESQL - Read

read

read from the large object

    read(size)

### Parameters

`size`

- Maximal size of the buffer to be read (integer).

### Return Type

string

- The read buffer.

### Exceptions

`TypeError`

- Bad parameter type, or too many arguments.

`IOError`

- Object is not opened, or read error.

`pg.error`

- Invalid connection or invalid object.

### Description

`read()` method allows to read data from the large object, starting at current position.

write

PYGRESQL - Write

write

write to the large object

    write(string)

### Parameters

`string`

- Buffer to be written (string).

### Return Type

none

### Exceptions

`TypeError`

- Bad parameter type, or too many arguments.

`IOError`

- Object is not opened, or write error.

`pg.error`

- Invalid connection or invalid object.

### Description

`write()` method allows to write data to the large object, starting at current position.

seek

PYGRESQL - Seek

seek

change current position in the large object

    seek(offset, whence)

### Parameters

`offset`

- Position offset (integer).

`whence`

- Positional parameter (integer).

### Return Type

integer

- New current position in the object.

### Exceptions

`TypeError`

- Bad parameter type, or too many arguments.

`IOError`

- Object is not opened, or seek error.

`pg.error`

- Invalid connection or invalid object.

### Description

`seek()` method allows to move the cursor position in the large object. The whence parameter can be obtained by OR-ing the constants defined in the `pg` module (`SEEK_SET`, `SEEK_CUR`, `SEEK_END`).

tell

PYGRESQL - Tell

tell

return current position in the large object

    tell()

### Parameters

none

### Return Type

integer

- Current position in the object.

### Exceptions

`SyntaxError`

- Too many arguments.

`IOError`

- Object is not opened, or seek error.

`pg.error`

- Invalid connection or invalid object.

### Description

`tell()` method allows to get the current position in the large object.

unlink

PYGRESQL - Unlink

unlink

delete the large object

    unlink()

### Parameters

none

### Return Type

none

### Exceptions

`SyntaxError`

- Too many arguments.

`IOError`

- Object is not closed, or unlink error.

`pg.error`

- Invalid connection or invalid object.

### Description

`unlink()` method unlinks (deletes) the large object.

size

PYGRESQL - Size

size

return the large object size

    size()

### Parameters

none

### Return Type

integer

- The large object size.

### Exceptions

`SyntaxError`

- Too many arguments.

`IOError`

- Object is not opened, or seek/tell error.

`pg.error`

- Invalid connection or invalid object.

### Description

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

export

PYGRESQL - Export

export

save the large object to file

    export(filename)

### Parameters

`filename`

- The file to be created.

### Return Type

none

### Exceptions

`TypeError`

- Bad argument type, or too many arguments.

`IOError`

- Object is not closed, or export error.

`pg.error`

- Invalid connection or invalid object.

### Description

`export()` method 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.