NAME
	Sql.postgres - Postgres (Postgres95, PgSQL) Server interface

AUTHOR
	Francesco Chemolli <kinkie@kame.usr.dsi.unimi.it>

DESCRIPTION
	This is an interface to the Postgres (Postgres95, pgsql) database server.
	This module may or may not be availible on your Pike, depending
	whether 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

	Please notice that unless you wish to specifically connect to a Postgres
	server, you'd better use the Sql.sql program instead.
	I and Henrik Grubbstrm have (hopefully) designed 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 (well, except server-specific SQL extensions).

	The program Postgres.postgres provides the _RAW_ interface
	to the database. Many functions are _NOT_ availible
	for that program. Therefore, its use is DEPRECATED.

SEE ALSO
	Sql.sql, Postgres.postgres, Sql.postgres_result

============================================================================
NAME
	create - (re)inititalize connection and select database

SYNTAX
	object Sql.postgres ();
	or
	object Sql.postgres (void|string host, void|string database, void|string username, void|string password);
	or
	void Sql.postgres->create(void|string host, void|string database, void|string username, void|string password);

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 can have the syntax "hostname" or "hostname:portname".
	This allows to specify the TCP/IP port to connect to. If it is 0 or "", it
	will try to connect to localhost, default port.

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

	The username and password arguments are silently ignored, since the Postgres
	C API doesn't allow to connect to the server as any user different than the
	user running the interface.

NOTA BENE
	You need to have a database selected before using the sql-object, 
	otherwise you'll get exceptions when you try to query it.
	Also 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
	Postgres.postgres, Sql.sql, postgres->select_db

============================================================================
NAME
	select_db - connect to a database

SYNTAX
	void select_db (string dbname);

DESCRIPTION
	This function allows you to connect to a database. Due to restrictions
	of the Postgres frontend-backend protocol, you always have to be connected
	to a database, so in fact this function just allows you to connect
	to a different database on the same server.

NOTA BENE
	This function CAN raise exceptions if something goes wrong (backend process
	not running, not enough permissions..)

SEE ALSO
	postgres->create

============================================================================
NAME
	big_query - Query the database

SYNTAX
	object (Sql.postgres_result) big_query (string sqlquery);

DESCRIPTION
	This is the only provided interface which allows you to query the
	database. If you wish to use the simpler "query" function, you need to
	use the Sql.sql generic sql-object.

	It returns a postgres_result object (which conforms to the Sql.sql_result
	standard interface for accessing data). I recommend using query() for
	simpler queries (because it is easier to handle, but stores all the result
	in memory), and big_query for queries you expect to return huge amounts
	of data (it's harder to handle, but fectches results on demand).

NOTA BENE
	This function _CAN_ raise exceptions. 

SEE ALSO
	Sql.sql, Sql.sql_result

============================================================================
NAME
	error - tell what the last server error was.

SYNTAX
	string error();

DESCRIPTION
	This function returns the textual description of the last server-related
	error. Returns 0 if no error has occurred yet. It is not cleared upon
	reading (can be invoked multiple times, will return the same result
	until a new error occurs).

SEE ALSO
	postgres->big_query

============================================================================
NAME
	list_dbs - list all databases availible on the server

SYNTAX
	string * list_dbs ();
	or
	string * list_dbs (string glob);

DESCRIPTION
	Lists all the databases availible on the server.
	If glob is specified, lists only those databases matching it.

============================================================================
NAME
	list_tables - lists all the tables of the current database

SYNTAX
	string * list_tables ();
	or
	string * list_tables (string glob);

DESCRIPTION
	Returns an array containing the names of all the tables in the currently
	selected database.
 	If a glob is specified, it will return only those tables
 	whose name matches it.

============================================================================
NAME
	list_fields - describe the fields of a table in the database

SYNTAX
	mapping(string:mapping(string:mixed)) list_fields(string table);
	or
	mapping(string:mapping(string:mixed)) list_fields(string table, string glob);

DESCRIPTION
	Returns a mapping, indexed on the column name, of mappings describing the
	attributes of a table of the current database.
	If a glob is specified, will return descriptions only of the columns matching
	it.

	The current fields are (but WILL change for better manageability and interface
	compliancy):

		int "has_rules"

		int "is_shared"

		string "expires" : a string representing an internal date.

		string "owner" : it's the textual representation of a Postgres uid.

		string "length" : don't know really why it's a string... this is how it's
		  internally represented though..

		string "text": a textual description of the internal (to the server) type-name

		mixed "default"

============================================================================
NAME
	server_info - returns information on the type of connection

SYNTAX
	string server_info();

DESCRIPTION
	This function returns a string describing the server we are talking
	to. It has the form "servername/serverversion" (like the HTTP protocol
	description) and is most useful in conjunction with the generic SQL-server
	module.

SEE ALSO
	Sql.sql

============================================================================
NAME
	host_info - describe the connection we're using

SYNTAX
	string host_info();

DESCRIPTION
 	This function returns a string describing what host are we talking to,
 	and how (TCP/IP or UNIX sockets).

============================================================================
NAME
	create_db - create a new database

SYNTAX
	void create_db(string dbname);

DESCRIPTION
	This function creates a new database with the given name (assuming we
	have enough permissions to do this).

SEE ALSO
	postgres->drop_db

============================================================================
NAME
	drop_db - destroy a database

SYNTAX
	void drop_db(string dbname);

DESCRIPTION
	This function destroys a database and all the data it contains (assuming
	we have enough permissions to do so). USE WITH CAUTION!

SEE ALSO
	postgres->create_db

============================================================================
NAME
	reset - resets a connection

SYNTAX
	void reset();

DESCRIPTION
	This function resets the connection to the backend. Can be used for
	a variety of reasons, for example to detect the status of a connection.

NOTA BENE
	This function is Postgres-specific, and thus it is not availible
	through the generic SQL-interface.

============================================================================
NAME
	set_notify_callback - sets a notification callback for SQL events

SYNTAX
	void set_notify_callback ();
	or
	void set_notify_callback (function f);
	or
	void set_notify_callback (function f, int|float polling_interval);

DESCRIPTION
	With Postgres you can associate events and notifications to tables.
	This function allows you to detect and handle such events.

	With no arguments, resets and removes any callback you might have
	put previously, and any polling cycle.

	With one argument, sets the notification callback (there can be only
	one for each sqlobject). 
	
	With two arguments, sets a notification callback and sets a polling
	cycle.

	The polling cycle is necessary because of the way notifications are
	delivered, that is piggyback with a query result. This means that
	if you don't do any query, you'll receive no notification. The polling
	cycle starts a call_out cycle which will do an empty query when
	the specified interval expires, so that pending notifications 
	may be delivered.

	The callback function must return no value, and takes a string argument,
	which will be the name of the table on which the notification event
	has occured. In future versions, support for user-specified arguments
	will be added.
	
NOTA BENE
	The polling cycle can be run only if your process is in "event-driven mode"
	(that is, if 'main' has returned a negative number).

	This function is Postgres-specific, and thus it is not availible
	through the generic SQL-interface.

============================================================================
NAME
	version - show the version of the Postgres driver.

SYNTAX
	string 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.

============================================================================
EXTERNAL INFLUENCES on the module.
	These ones do not depend on my implementation really, they're just part
	of the Postgres C API. They take the form of certain environment variables
	which, if defined in the environment of the pike interpreter, influence
	the interface's behavior. 

	PGHOST: sets the name of the default host to connect to. It defaults
		to "localhost"
	
	PGOPTIONS: sets some extra flags for the frontend-backend connection.
	  DO NOT SET unless you're sure of what you're doing.
	
	PGPORT: sets the default port to connect to, otherwise it will use
	  compile-time defaults (that is: the time you compiled the postgres
		library, not the Pike driver).

	PGTTY: sets the file to be used for Postgres frontend debugging.
	  Do not use, unless you're sure of what you're doing.

	PGDATABASE: sets the default database to connect to.

	PGREALM: sets the default realm for Kerberos authentication. I never used
		this, so I can't help you.

	Refer to the Postgres documentation for further details.

NOTES
	I didn't make any testsuite for this module, since to test anything it would
	require a working Postgres server, and I can't make any assumption
	on those... You can try to use the included scripts (they're in the
	"pike/src/modules/Postgres/extras" directory
	but you'll probably have to patch them to reflect your site's settings.

	Also note that THIS MODULE USES BLOCKING I/O to connect to the server.
	Postgres is quite slow, and so you might want to consider this
	particular aspect. It is (at least should be) thread-safe, and so it can be used
	in a multithread environment.

THANKS
	Many thanks to Henrik Grubbstrm, without whose help this piece of
	code couldn't be nearly as complete as it is.
	Also thanks to Frederik Hubinette, for designing such a nice language
	as Pike.

COPYRIGHT
	This code and documentation are copyright 1997 Francesco Chemolli 
	<kinkie@kame.usr.dsi.unimi.it>.
	It may be copied, modified, redistributed under the terms of the
	GNU General Public License, version 2.
	
	This program is distributed in the hope that it will be useful,
	but WITHOUT ANY WARRANTY; without even the implied warranty of
	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
	GNU General Public License for more details.

	You should have received a copy of the GNU General Public License
	along with the Pike source. If not, write to the Free Software
	Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

	The Pike programming language is copyright Frederik Hubinette, and is
	distributed under the terms of the GNU General Public License. For furhter
	information, please consult the Pike WWW site, at http://pike.roxen.com/
