NAME
	Sql.sql - Generic interface to SQL databases (ALPHA)

DESCRIPTION
	Sql.sql is a program in the Sql module. It enables access
	to SQL databases from within Pike.

NOTA BENE
	To use this module you need at least one specific SQL-module e.g.
	Mysql.mysql or Msql.msql.

KEYWORDS
	sql, database

SEE ALSO
	Mysql.mysql, Msql.msql


============================================================================
NAME
	create - connect to an SQL database
 
SYNTAX
	#include <sql.h>

	object(sql) sql();
	or
	object(sql) sql(object obj);
	or
	object(sql) sql(object obj, string database);
	or
	object(sql) sql(string hostname);
	or
	object(sql) sql(string hostname, string database);
	or
	object(sql) sql(string hostname, string database, string user);
	or
	object(sql) sql(string hostname,string database,
	                string user, string password);

DESCRIPTION
	To access a database, you must first connect to it. This is
	done with the function sql().
	
	If the first argument is an object, access to the SQL-database will
	go through that object.

	Otherwise all currently available programs named /precompiled/sql/*
	will be tried in turn to get a successfull connection.

	If hostname is "" or 0 (zero) access to the SQL-database will be
	done through a UNIX-domain socket. Otherwise communication will
	be through TCP/IP or similar to the named host.

	If database is not "" or 0 (zero) that database will be selected.

	user and password are used for access-control to the SQL-database.

EXAMPLE
	/* Connect to the database "test" and dump the table "db" */

	#include <sql.h>
	#include <mysql.h>

	int main()
	{
	  /* First: Do it with the first available SQL-server */

	  object(sql) sql_connection = sql(0, "test");

	  write(sprintf("sql: %O\n",
                        sql_connection->query("select * from db")));

	  /* Second: Use the Mysql-server */
	  sql_connection = sql(mysql(), "test");

	  write(sprintf("mysql: %O\n",
                        sql_connection->query("select * from db")));
	}

SEE ALSO
	sql->query


============================================================================
NAME
	error - report the last error from the underlying SQL module

SYNTAX
	#include <sql.h>

	string sql->error();

DESCRIPTION
	When a SQL-method fails you may get a decription of why with
	this function.


============================================================================
NAME
	select_db - select database

SYNTAX
	#include <sql.h>

	void select_db(string database);

DESCRIPTION
	Most SQL-servers can hold several databases. You select which one
	you want to access with this function.

SEE ALSO
	Sql, sql->create_db, sql->drop_db


============================================================================
NAME
	query - make an SQL query

SYNTAX
	#include <sql.h>

	int|array(mapping(string:mixed)) sql->query(string q);

DESCRIPTION
	This function sends an SQL query to the underlying SQL-server. The
	result is returned as an array of mappings indexed on the name of
	the columns. Returns 0 if the query didn't return any result (e.g.
	INSERT or similar).

SEE ALSO
	sql->big_query


============================================================================
NAME
	big_query - make an SQL query (advanced version)

SYNTAX
	#include <sql.h>

	object(sql_result) sql->big_query(string q);

DESCRIPTION
	This function sends an SQL query to the underlying SQL-server. The
	result is returned as a Sql.sql_result object. This allows for
	having results larger than the available memory, and returning some
	more info on the result. Returns 0 if the query didn't return any
	result (e.g. INSERT or similar).

SEE ALSO
	sql->query, Sql.sql_result


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

SYNTAX
	#include <sql.h>

	void sql->create_db(string database)

DESCRIPTION
	This function attempts to create a new database in the SQL-server.

SEE ALSO
	sql->select_db, sql->drop_db


============================================================================
NAME
	drop_db - drop a database

SYNTAX
	#include <sql.h>

	void sql->drop_db(string database)

DESCRIPTION
	This function attempts to drop the named database from the
	SQL-server.

SEE ALSO
	sql->select_db, sql->create_db


============================================================================
NAME
	shutdown - shutdown the SQL server

SYNTAX
	#include <sql.h>

	void sql->shutdown();

DESCRIPTION
	This function attempts to shutdown the SQL-server.

SEE ALSO
	sql->reload


============================================================================
NAME
	reload - reload the tables

SYNTAX
	#include <sql.h>

	void sql->reload();

DESCRIPTION
	If possible the tables will be reloaded by the SQL-server.

SEE ALSO
	sql->shutdown


============================================================================
NAME
	server_info - give information about the current SQL server

SYNTAX
	#include <sql.h>

	string sql->server_info();

DESCRIPTION
	This function returns version information about the SQL-server.

SEE ALSO
	sql->host_info


============================================================================
NAME
	host_info - give information about the SQL-server connection

SYNTAX
	#include <sql.h>

	string sql->host_info();

DESCRIPTION
	This function returns a string describing the connection to the
	SQL-server.

SEE ALSO
	sql->server_info


============================================================================
NAME
	list_dbs - list available databases from this SQL server

SYNTAX
	#include <sql.h>

	array(mapping(string:string)) list_dbs();
	or
	array(mapping(string:string)) list_dbs(string wild);

DESCRIPTION
	Returns an array with mappings containing the names of the
	databases in this SQL-server.

	If wild is specified, only those matching it are returned.

NOTA BENE
	Might be better to return just an array(string), and skip the
	mapping part.

SEE ALSO
	sql->list_tables, sql->list_fields


============================================================================
NAME
	list_tables - list available tables in this database

SYNTAX
	#include <sql.h>

	array(mapping(string:string)) list_tables();
	or
	array(mapping(string:string)) list_tables();

DESCRIPTION
	Returns an array with mappings containing the names of the
	tables in the current database.

	If wild is specified, only those matching it are returned.

NOTA BENE
	Might be better to return just an array(string), and skip the
	mapping part.

SEE ALSO
	sql->list_dbs, sql->list_fields


============================================================================
NAME
	list_fields - list names of all fields in a table

SYNTAX
	#include <sql.h>

	array(mapping(string:mixed)) list_fields(string table);
	or
	array(mapping(string:mixed)) list_fields(string table, string wild);

DESCRIPTION
	Returns an array of mappings containing data about the fields
	in the specified table.

	If wild is specified, only those fields matching it are returned.

	The mappings contain at least the following entries:

	 "name":	string	The name of the field.
	 "table":	string	The name of the table.
	 "default":	mixed	The default value for the field.
	 "type":	string	The type of the field.

NOTA BENE
	Might be better to return just an array(string), and skip the
	mapping part.

SEE ALSO
	sql->list_dbs, sql->list_tables,
	sql_result->fetch_fields

