Class Postgres.postgres

Inheritance graph

Description

This is an interface to the Postgres (Postgres95, PostgreSQL) database server using libpq.

This module may or may not be available on your Pike, depending on whether or not the appropriate include and library files could be found at compile-time. Note that you do not need to have a Postgres server running on your host to use this module: you can connect to the database over a TCP/IP socket.

Note

Please notice that unless you wish to specifically connect to a Postgres server, you'd better use the Sql.Sql, which is a server-independent sql-server-class. The interfaces to all existing sql-classes are consistent. Using Sql.Sql ensures that your Pike applications will run with any supported SQL server without changing a single line of code, at least for most common (and simple) operations.

The program Postgres.postgres provides the raw interface to the database. Many functions are not available for this program. Therefore, its use is DEPRECATED. It is included in this documentation only for completeness' sake. Use Sql.postgres instead, or even better Sql.Sql

Note

This driver is based on libpq and is DEPRECATED. There is a newer driver called Sql.pgsql which is faster and more robust than this driver and does not depend on any libraries.

Note

There is no testsuite for this module, since to test anything would require a working Postgres server. You can try to use the included scripts in the "pike/src/modules/Postgres/extras" directory but you'll probably have to patch them to reflect your site's settings.

The behavior of the Postgres C API also depends on certain environment variables defined in the environment of the pike interpreter.

`"PGHOST"`	Sets the name of the default host to connect to. It defaults to `"localhost"`.
`"PGHOSTADDR"`	Set the numeric IP address to connect to. This may be set instead of or in addition to PGHOST to avoid DNS lookups.
`"PGPORT"`	Sets the default port or unix domain socket file extension to connect to, otherwise it will use compile-time defaults (that is: the time you compiled the postgres library, not the Pike driver).
`"PGDATABASE"`	Sets the default database to connect to.
`"PGUSER"`	Sets the default username used to connect to the database.
`"PGPASSWORD"`	Set the default password used to connect to the database. This is not recommended for security reasons, some operating systems allow non-root users to see process environment variables. Use your ~/.pgpass file instead.
`"PGSERVICE"`	Sets the service name to be looked up in pg_service.conf. This is a shorter way to set all the parameters.
`"PGSSLMODE"`	This determines how SSL connections will be negotiated. If set to disable, it will require an unencrypted connection; allow will negotiate a non-SSL connection, and if it fails try an SSL connection; prefer will attempt SSL connections first, falling back to non-SSL if SSL fails; and require will force an SSL connection or cause an error if SSL is not available.
`"PGOPTIONS"`	Sets some extra flags for the frontend-backend connection. do not set unless you're sure of what you're doing.
`"PGREALM"`	Sets the Kerberos realm for authentication, if it is different from the local realm. PostgreSQL will attempt to authenticate with servers for this realm and use seperate ticket files to avoid conflicts with local ticket files. This variable is only used if Keberos authentication is selected in PostgreSQL.
`"PGTTY"`	Sets the file to be used for Postgres frontend debugging. Do not use, unless you're sure of what you're doing. This variable is ignored in recent versions of PostgreSQL.

Refer to the libpq documentation for further details.

Variable version: string Postgres.postgres.version
Description: Should you need to report a bug to the author, please submit along with the report the driver version number, as returned by this call.

Method create

Postgres.postgres Postgres.postgres()
Postgres.postgres Postgres.postgres(string host, void|string database, void|int port)

Description

With no arguments, this function initializes (reinitializes if a connection had been previously set up) a connection to the Postgres backend. Since Postgres requires a database to be selected, it will try to connect to the default database. The connection may fail however for a variety of reasons, in this case the most likely of all is because you don't have enough authority to connect to that database. So use of this particular syntax is discouraged.

The host argument allows you to connect to databases residing on different hosts. If it is 0 or "", it will try to connect to localhost.

The database argument specifies the database to connect to. If 0 or "", it will try to connect to the default database.

Note

Notice that this function can raise exceptions if the db server doesn't respond, if the database doesn't exist or is not accessible by you.

You don't need bothering about syncronizing the connection to the database: it is automatically closed (and the database is sync-ed) when the object is destroyed.

See also

Sql.postgres, Sql.Sql, select_db