The pg module handles three types of objects,
and it provides a convenient wrapper class DB for the pgobject.
If you want to see a simple example of the use of some of these functions, see the examples page.
The pg module defines a few functions 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.
Opens a pg connection
Syntax:
connect([dbname], [host], [port], [opt], [tty], [user], [passwd])
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: | connection options (string/None) |
tty: | debug terminal (string/None) |
user: | PostgreSQL user (string/None) |
passwd: | password for user (string/None) |
pgobject: | If successful, the pgobject handling the connection |
---|
TypeError: | bad argument type, or too many arguments |
---|---|
SyntaxError: | duplicate argument definition |
pg.InternalError: | |
some error occurred during pg connection definition |
(plus all exceptions relative to object allocation)
Examples:
import pg con1 = pg.connect('testdb', 'myhost', 5432, None, None, 'bob', None) con2 = pg.connect(dbname='testdb', host='localhost', user='bob')
default server host [DV]
Syntax:
get_defhost()
string, None: | default host specification |
---|
TypeError: | too many arguments |
---|
Syntax:
set_defhost(host)
host: | new default host (string/None) |
---|
string, None: | previous default host specification |
---|
TypeError: | bad argument type, or too many arguments |
---|
default server port [DV]
Syntax:
get_defport()
integer, None: | default port specification |
---|
TypeError: | too many arguments |
---|
Syntax:
set_defport(port)
port: | new default port (integer/-1) |
---|
integer, None: | previous default port specification |
---|
default connection options [DV]
Syntax:
get_defopt()
string, None: | default options specification |
---|
TypeError: | too many arguments |
---|
Syntax:
set_defopt(options)
options: | new default connection options (string/None) |
---|
string, None: | previous default options specification |
---|
TypeError: | bad argument type, or too many arguments |
---|
default debug tty [DV]
Syntax:
get_deftty()
string, None: | default debug terminal specification |
---|
TypeError: | too many arguments |
---|
Syntax:
set_deftty(terminal)
terminal: | new default debug terminal (string/None) |
---|
string, None: | previous default debug terminal specification |
---|
TypeError: | bad argument type, or too many arguments |
---|
default database name [DV]
Syntax:
get_defbase()
string, None: | default database name specification |
---|
TypeError: | too many arguments |
---|
Syntax:
set_defbase(base)
base: | new default base name (string/None) |
---|
string, None: | previous default database name specification |
---|
TypeError: | bad argument type, or too many arguments |
---|
escape a string for use within SQL
Syntax:
escape_string(string)
string: | the string that is to be escaped |
---|
str: | the escaped string |
---|
TypeError: | bad argument type, or too many arguments |
---|
Caution!
It is especially important to do proper escaping when handling strings that were received from an untrustworthy source. Otherwise there is a security risk: you are vulnerable to "SQL injection" attacks wherein unwanted SQL commands are fed to your database.
Example:
name = raw_input("Name? ") phone = con.query("select phone from employees" " where name='%s'" % escape_string(name)).getresult()
escape binary data for use within SQL as type bytea
Syntax:
escape_bytea(datastring)
datastring: | string containing the binary data that is to be escaped |
---|
str: | the escaped string |
---|
TypeError: | bad argument type, or too many arguments |
---|
Example:
picture = file('garfield.gif', 'rb').read() con.query("update pictures set img='%s' where name='Garfield'" % escape_bytea(picture))
unescape bytea data that has been retrieved as text
Syntax:
unescape_bytea(string)
datastring: | the bytea data string that has been retrieved as text |
---|
str: | string containing the binary data |
---|
TypeError: | bad argument type, or too many arguments |
---|
Example:
picture = unescape_bytea(con.query( "select img from pictures where name='Garfield'").getresult[0][0]) file('garfield.gif', 'wb').write(picture)
get the decimal type to be used for numeric values
Syntax:
get_decimal()
cls: | the Python class used for PostgreSQL numeric values |
---|
set a decimal type to be used for numeric values
Syntax:
set_decimal(cls)
cls: | the Python class to be used for PostgreSQL numeric values |
---|
get the decimal mark used for monetary values
Syntax:
get_decimal_point()
str: | string with one character representing the decimal mark |
---|
specify which decimal mark is used for interpreting monetary values
Syntax:
set_decimal_point(str)
str: | string with one character representing the decimal mark |
---|
check whether boolean values are returned as bool objects
Syntax:
get_bool()
bool: | whether or not bool objects will be returned |
---|
set whether boolean values are returned as bool objects
Syntax:
set_bool(bool)
bool: | whether or not bool objects shall be returned |
---|
set a function that will convert to named tuples
Syntax:
set_namedresult()
set a function that will convert to named tuples
Syntax:
set_namedresult(func)
func: | the function to be used to convert results to named tuples |
---|
Some constants are defined in the module dictionary. They are intended to be used as parameters for methods calls. You should refer to the libpq description in the PostgreSQL user manual for more information about them. These constants are:
version, __version__: | |
---|---|
constants that give the current version. | |
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 |
Connection object
This object handles a connection to a PostgreSQL database. It embeds and hides all the parameters that define this connection, thus just leaving really significant parameters in function calls.
Caution!
Some methods give direct access to the connection socket. 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.
These methods are specified by the tag [DA].
Note
Some other methods give access to large objects (refer to PostgreSQL user manual for more information about these). 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].
executes a SQL command string
Syntax:
query(command, [args])
command: | SQL command (string) |
---|---|
args: | optional positional arguments |
pgqueryobject, None: | |
---|---|
result values |
TypeError: | bad argument type, or too many arguments |
---|---|
TypeError: | invalid connection |
ValueError: | empty SQL query or lost connection |
pg.ProgrammingError: | |
error in query | |
pg.InternalError: | |
error during query processing |
This method simply sends a SQL query to the database. If the query is an insert statement that inserted exactly one row into a table that has OIDs, the return value is the OID of the newly inserted row. If the query is an update or delete statement, or an insert statement that did not insert exactly one row in a table with OIDs, then the numer of rows affected is returned as a string. If it is a statement that returns rows as a result (usually a select statement, but maybe also an "insert/update ... returning" statement), this method returns a pgqueryobject that can be accessed via the getresult(), dictresult() or namedresult() methods or simply printed. Otherwise, it returns None.
The query may optionally contain positional parameters of the form $1, $2, etc instead of literal data, and the values supplied as a tuple. The values are substituted by the database in such a way that they don't need to be escaped, making this an effective way to pass arbitrary or unknown data without worrying about SQL injection or syntax errors.
When the database could not process the query, a pg.ProgrammingError or a pg.InternalError is raised. You can check the "SQLSTATE" code of this error by reading its sqlstate attribute.
Example:
name = raw_input("Name? ") phone = con.query("select phone from employees" " where name=$1", (name, )).getresult()
resets the connection
Syntax:
reset()
TypeError: | too many (any) arguments |
---|---|
TypeError: | invalid connection |
abandon processing of current SQL command
Syntax:
cancel()
TypeError: | too many (any) arguments |
---|---|
TypeError: | invalid connection |
close the database connection
Syntax:
close()
TypeError: | too many (any) arguments |
---|
returns the socket used to connect to the database
Syntax:
fileno()
TypeError: | too many (any) arguments |
---|---|
TypeError: | invalid connection |
gets the last notify from the server
Syntax:
getnotify()
tuple, None: | last notify from server |
---|
TypeError: | too many parameters |
---|---|
TypeError: | invalid connection |
insert a list into a table
Syntax:
inserttable(table, values)
table: | the table name (string) |
---|---|
values: | list of rows values (list) |
TypeError: | invalid connection, bad argument type, or too many arguments |
---|---|
MemoryError: | insert buffer could not be allocated |
ValueError: | unsupported values |
Caution!
Be very careful: This method doesn't typecheck the fields according to the table definition; it just look whether or not it knows how to handle such types.
set a custom notice receiver
Syntax:
set_notice_receiver(proc)
proc: | the custom notice receiver callback function |
---|
TypeError: | the specified notice receiver is not callable |
---|
This method allows setting a custom notice receiver callback function. When a notice or warning message is received from the server, or generated internally by libpq, and the message level is below the one set with client_min_messages, the specified notice receiver function will be called. This function must take one parameter, the pgnotice object, which provides the following read-only attributes:
pgcnx: the connection message: the full message with a trailing newline severity: the level of the message, e.g. 'NOTICE' or 'WARNING' primary: the primary human-readable error message detail: an optional secondary error message hint: an optional suggestion what to do about the problem
get the current notice receiver
Syntax:
get_notice_receiver()
callable, None: | the current notice receiver callable |
---|
TypeError: | too many (any) arguments |
---|
writes a line to the server socket [DA]
Syntax:
putline(line)
line: | line to be written (string) |
---|
TypeError: | invalid connection, bad parameter type, or too many parameters |
---|
gets a line from server socket [DA]
Syntax:
getline()
string: | the line read |
---|
TypeError: | invalid connection |
---|---|
TypeError: | too many parameters |
MemoryError: | buffer overflow |
synchronizes client and server [DA]
Syntax:
endcopy()
TypeError: | invalid connection |
---|---|
TypeError: | too many parameters |
create a large object in the database [LO]
Syntax:
locreate(mode)
mode: | large object create mode |
---|
pglarge: | object handling the PostGreSQL large object |
---|
Exceptions raised:
TypeError: invalid connection, bad parameter type, or too many parameters pg.OperationalError: creation error
build a large object from given oid [LO]
Syntax:
getlo(oid)
oid: | OID of the existing large object (integer) |
---|
pglarge: | object handling the PostGreSQL large object |
---|
TypeError: | invalid connection, bad parameter type, or too many parameters |
---|---|
ValueError: | bad OID value (0 is invalid_oid) |
import a file to a large object [LO]
Syntax:
loimport(name)
name: | the name of the file to be imported (string) |
---|
pglarge: | object handling the PostGreSQL large object |
---|
TypeError: | invalid connection, bad argument type, or too many arguments |
---|---|
pg.OperationalError: | |
error during file import |
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) protocol_version: the frontend/backend protocol being used (integer) server_version: the backend version (integer, e.g. 80305 for 8.3.5) status: the status of the connection (integer: 1 - OK, 0 - bad) error: the last warning/error message from the server (string)
the DB wrapper class
The pgobject methods are wrapped in the class DB. The preferred way to use this module is as follows:
import pg db = pg.DB(...) # see below for r in db.query( # just for example """SELECT foo,bar FROM foo_bar_table WHERE foo !~ bar""" ).dictresult(): print '%(foo)s %(bar)s' % r
This class can be subclassed as in this example:
import pg class DB_ride(pg.DB): """This class encapsulates the database functions and the specific methods for the ride database.""" def __init__(self): """Opens a database connection to the rides database""" pg.DB.__init__(self, dbname = 'ride') self.query("""SET DATESTYLE TO 'ISO'""") [Add or override methods here]
The following describes the methods and variables of this class.
The DB class is initialized with the same arguments as the connect function described in section 2. It also initializes a few internal variables. The statement db = DB() will open the local database with the name of the user just like connect() does.
You can also initialize the DB class with an existing _pg or pgdb connection. Pass this connection as a single unnamed parameter, or as a single parameter named db. This allows you to use all of the methods of the DB class with a DB-API 2 compliant connection. Note that the close() and reopen() methods are inoperative in this case.
return the primary key of a table
Syntax:
pkey(table)
table: | name of table |
---|
string: | Name of the field which is the primary key of the table |
---|
get list of databases in the system
Syntax:
get_databases()
list: | all databases in the system |
---|
get list of relations in connected database
Syntax:
get_relations(kinds)
kinds: | a string or sequence of type letters |
---|
get list of tables in connected database
Syntax:
get_tables()
list: | all tables in connected database |
---|
get the attribute names of a table
Syntax:
get_attnames(table)
table: | name of table |
---|
dictionary: | The keys are the attribute names, the values are the type names of the attributes. |
---|
check whether current user has specified table privilege
Syntax:
has_table_privilege(table, privilege)
table: | name of table |
---|---|
privilege: | privilege to be checked - default is 'select' |
get a row from a database table or view
Syntax:
get(table, arg, [keyname])
table: | name of table or view |
---|---|
arg: | either a dictionary or the value to be looked up |
keyname: | name of field to use as key (optional) |
dictionary: | The keys are the attribute names, the values are the row values. |
---|
insert a row into a database table
Syntax:
insert(table, [d,] [key = val, ...])
table: | name of table |
---|---|
d: | optional dictionary of values |
dictionary: | The dictionary of values inserted |
---|
This method inserts a row into a table. If the optional dictionary is not supplied then the required values must be included as keyword/value pairs. If a dictionary is supplied then any keywords provided will be added to or replace the entry in the dictionary.
The dictionary is then, if possible, reloaded with the values actually inserted in order to pick up values modified by rules, triggers, etc.
Note: The method currently doesn't support insert into views although PostgreSQL does.
update a row in a database table
Syntax:
update(table, [d,] [key = val, ...])
table: | name of table |
---|---|
d: | optional dictionary of values |
dictionary: | the new row |
---|
Similar to insert but updates an existing row. The update is based on the OID value as munged by get or passed as keyword, or on the primary key of the table. The dictionary is modified, if possible, to reflect any changes caused by the update due to triggers, rules, default values, etc.
Like insert, the dictionary is optional and updates will be performed on the fields in the keywords. There must be an OID or primary key either in the dictionary where the OID must be munged, or in the keywords where it can be simply the string "oid".
executes a SQL command string
Syntax:
query(command, [arg1, [arg2, ...]])
command: | SQL command (string) |
---|---|
arg*: | optional positional arguments |
pgqueryobject, None: | |
---|---|
result values |
TypeError: | bad argument type, or too many arguments |
---|---|
TypeError: | invalid connection |
ValueError: | empty SQL query or lost connection |
pg.ProgrammingError: | |
error in query | |
pg.InternalError: | |
error during query processing |
Example:
name = raw_input("Name? ") phone = raw_input("Phone? " rows = db.query("update employees set phone=$2" " where name=$1", (name, phone)).getresult()[0][0] # or rows = db.query("update employees set phone=$2" " where name=$1", name, phone).getresult()[0][0]
clears row values in memory
Syntax:
clear(table, [a])
table: | name of table |
---|---|
a: | optional dictionary of values |
dictionary: | an empty row |
---|
This method clears all the attributes to values determined by the types. Numeric types are set to 0, Booleans are set to 'f', dates are set to 'now()' 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.
If the dictionary is not supplied a new one is created.
delete a row from a database table
Syntax:
delete(table, [d,] [key = val, ...])
table: | name of table |
---|---|
d: | optional dictionary of values |
escape a string for use within SQL
Syntax:
escape_string(string)
string: | the string that is to be escaped |
---|
str: | the escaped string |
---|
escape binary data for use within SQL as type bytea
Syntax:
escape_bytea(datastring)
datastring: | string containing the binary data that is to be escaped |
---|
str: | the escaped string |
---|
unescape bytea data that has been retrieved as text
Syntax:
unescape_bytea(string)
datastring: | the bytea data string that has been retrieved as text |
---|
str: | string containing the binary data |
---|
get query values as list of tuples
Syntax:
getresult()
list: | result values as a list of tuples |
---|
TypeError: | too many (any) parameters |
---|---|
MemoryError: | internal memory error |
get query values as list of dictionaries
Syntax:
dictresult()
list: | result values as a list of dictionaries |
---|
TypeError: | too many (any) parameters |
---|---|
MemoryError: | internal memory error |
get query values as list of named tuples
Syntax:
namedresult()
list: | result values as a list of named tuples |
---|
TypeError: | too many (any) parameters |
---|---|
TypeError: | named tuples not supported |
MemoryError: | internal memory error |
lists fields names of previous query result
Syntax:
listfields()
list: | field names |
---|
TypeError: | too many parameters |
---|
field name/number conversion
Syntax:
fieldname(i)
i: | field number (integer) |
---|
string: | field name |
---|
TypeError: | invalid connection, bad parameter type, or too many parameters |
---|---|
ValueError: | invalid field number |
Syntax:
fieldnum(name)
name: | field name (string) |
---|
integer: | field number |
---|
TypeError: | invalid connection, bad parameter type, or too many parameters |
---|---|
ValueError: | unknown field name |
return number of tuples in query object
Syntax:
ntuples()
integer: | number of tuples in pgqueryobject |
---|
TypeError: | Too many arguments. |
---|
Large objects
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 pgobjects 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 won't deallocate it before the pglarge 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.
See also the PostgreSQL programmer's guide for more information about the large object interface.
opens a large object
Syntax:
open(mode)
mode: | open mode definition (integer) |
---|
TypeError: | invalid connection, bad parameter type, or too many parameters |
---|---|
IOError: | already opened object, or open error |
closes a large object
Syntax:
close()
TypeError: | invalid connection |
---|---|
TypeError: | too many parameters |
IOError: | object is not opened, or close error |
file like large object handling
Syntax:
read(size)
size: | maximal size of the buffer to be read |
---|
sized string: | the read buffer |
---|
TypeError: | invalid connection, invalid object, bad parameter type, or too many parameters |
---|---|
ValueError: | if size is negative |
IOError: | object is not opened, or read error |
Syntax:
write(string)
TypeError: | invalid connection, bad parameter type, or too many parameters |
---|---|
IOError: | object is not opened, or write error |
Syntax:
seek(offset, whence)
offset: | position offset |
---|---|
whence: | positional parameter |
integer: | new position in object |
---|
TypeError: | invalid connection or invalid object, bad parameter type, or too many parameters |
---|---|
IOError: | object is not opened, or seek error |
Syntax:
tell()
integer: | current position in large object |
---|
TypeError: | invalid connection or invalid object |
---|---|
TypeError: | too many parameters |
IOError: | object is not opened, or seek error |
Syntax:
unlink()
TypeError: | invalid connection or invalid object |
---|---|
TypeError: | too many parameters |
IOError: | object is not closed, or unlink error |
gives the large object size
Syntax:
size()
integer: | the large object size |
---|
TypeError: | invalid connection or invalid object |
---|---|
TypeError: | too many parameters |
IOError: | object is not opened, or seek/tell error |
saves a large object to a file
Syntax:
export(name)
name: | file to be created |
---|
TypeError: | invalid connection or invalid object, bad parameter type, or too many parameters |
---|---|
IOError: | object is not closed, or export error |
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
Caution!
Be careful: In multithreaded environments, 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 oid attribute is very interesting because it allow you reuse the OID later, creating the pglarge object with a pgobject getlo() method call.