pike.git / lib / modules / Sql.pmod / pgsql.pike

version» Context lines:

pike.git/lib/modules/Sql.pmod/pgsql.pike:142:      //! @decl void create()   //! @decl void create(string host, void|string database, void|string user,@   //! void|string password, void|mapping(string:mixed) options)   //!   //! With no arguments, this function initialises (reinitialises if a   //! connection has been set up previously) a connection to the   //! PostgreSQL backend. Since PostgreSQL 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 reason is because you don't have enough privileges + //! the most likely reason is because you don't have sufficient privileges   //! to connect to that database. So use of this particular syntax is   //! discouraged.   //!   //! @param host   //! Should either contain @expr{"hostname"@} or   //! @expr{"hostname:portname"@}. This allows you to specify the TCP/IP   //! port to connect to. If the parameter is @expr{0@} or @expr{""@},   //! it will try to connect to localhost, default port.   //!   //! @param database   //! Specifies the database to connect to. Not specifying this is   //! only supported if the PostgreSQL backend has a default database   //! configured. If you do not want to connect to any live database,   //! you can use @ref{template1@}.   //!   //! @param options   //! Currently supports at least the following:   //! @mapping - //! @member int "use_ssl" + //! @member int use_ssl   //! If the database supports and allows SSL connections, the session   //! will be SSL encrypted, if not, the connection will fallback   //! to plain unencrypted - //! @member int "force_ssl" + //! @member int force_ssl   //! If the database supports and allows SSL connections, the session   //! will be SSL encrypted, if not, the connection will abort - //! @member int "cache_autoprepared_statements" + //! @member int cache_autoprepared_statements   //! If set to zero, it disables the automatic statement prepare and   //! cache logic; caching prepared statements can be problematic   //! when stored procedures and tables are redefined which leave stale   //! references in the already cached prepared statements - //! @member string "client_encoding" + //! @member string client_encoding   //! Character encoding for the client side, it defaults to using   //! the default encoding specified by the database, e.g.: "SQL_ASCII" - //! @member string "standard_conforming_strings" + //! @member string standard_conforming_strings   //! When on, backslashes in strings must not be escaped any longer,   //! @[quote()] automatically adjusts quoting strategy accordingly - //! @member string "escape_string_warning" + //! @member string escape_string_warning   //! When on, a warning is issued if a backslash (\) appears in an   //! ordinary string literal and @[standard_conforming_strings] is off,   //! defaults to on   //! @endmapping   //! For the numerous other options please check the PostgreSQL manual.   //!   //! @note   //! 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 @b{can@} raise exceptions if the db
pike.git/lib/modules/Sql.pmod/pgsql.pike:339:   string get_charset()   { return runtimeparameter->client_encoding;   }      //! @returns   //! Currently active runtimeparameters for   //! the open session; these are initialised by the @ref{options@} parameter   //! during session creation, and then processed and returned by the server.   //! Common values are:   //! @mapping - //! @member string "client_encoding" + //! @member string client_encoding   //! Character encoding for the client side, e.g.: "SQL_ASCII" - //! @member string "server_encoding" + //! @member string server_encoding   //! Character encoding for the server side as determined when the   //! database was created, e.g.: "SQL_ASCII" - //! @member string "DateStyle" + //! @member string DateStyle   //! Date parsing/display, e.g.: "ISO, DMY" - //! @member string "TimeZone" + //! @member string TimeZone   //! Default timezone used by the database, e.g.: "localtime" - //! @member string "standard_conforming_strings" + //! @member string standard_conforming_strings   //! When on, backslashes in strings must not be escaped any longer - //! @member string "session_authorization" + //! @member string session_authorization   //! Displays the authorisationrole which the current session runs under - //! @member string "is_superuser" + //! @member string is_superuser   //! Indicates if the current authorisationrole has database-superuser   //! privileges - //! @member string "integer_datetimes" + //! @member string integer_datetimes   //! Reports wether the database supports 64-bit-integer dates and times - //! @member string "server_version" + //! @member string server_version   //! Shows the server version, e.g.: "8.3.3"   //! @endmapping   //!   //! The values can be changed during a session using SET commands to the   //! database.   //! For other runtimeparameters check the PostgreSQL documentation.   //!   //! @seealso   //! @url{http://search.postgresql.org/search?u=%2Fdocs%2F&q=client+connection+defaults@}   //!   //! @note   //! This function is PostgreSQL-specific, and thus it is not available   //! through the generic SQL-interface.   mapping(string:string) getruntimeparameters() {    return runtimeparameter+([]);   }      //! @returns   //! A set of statistics for the current session:   //! @mapping - //! @member int "warnings_dropped" + //! @member int warnings_dropped   //! Number of warnings/notices generated by the database but not - //! collected by the application by using @[error] after the statements + //! collected by the application by using @[error()] after the statements   //! that generated them. - //! @member int "skipped_describe_count" + //! @member int skipped_describe_count   //! Number of times the driver skipped asking the database to   //! describe the statement parameters because it was already cached. - //! @member int "used_prepared_statements" + //! @member int used_prepared_statements   //! Numer of times prepared statements were used from cache instead of   //! reparsing in the current session. - //! @member int "current_prepared_statements" + //! @member int current_prepared_statements   //! Cache size of currently prepared statements. - //! @member int "current_prepared_statement_hits" + //! @member int current_prepared_statement_hits   //! Sum of the number hits on statements in the current statement cache. - //! @member int "prepared_portal_count" + //! @member int prepared_portal_count   //! Total number of prepared portals generated. - //! @member int "prepared_statement_count" + //! @member int prepared_statement_count   //! Total number of prepared statements generated. - //! @member int "portals_opened_count" + //! @member int portals_opened_count   //! Total number of portals opened, i.e. number of statements issued   //! to the database. - //! @member int "blocked_count" + //! @member int blocked_count   //! Number of times the driver had to (briefly) wait for the database to   //! send additional data. - //! @member int "bytes_received" + //! @member int bytes_received   //! Total number of bytes received from the database so far. - //! @member int "messages_received" + //! @member int messages_received   //! Total number of messages received from the database (one SQL-statement   //! requires multiple messages to be exchanged). - //! @member int "bytes_sent" + //! @member int bytes_sent   //! Total number of bytes sent to the database so far. - //! @member int "packets_sent" + //! @member int packets_sent   //! Total number of packets sent to the database (one packet usually   //! contains multiple messages). - //! @member int "reconnect_count" + //! @member int reconnect_count   //! Number of times the connection to the database has been lost. - //! @member int "portals_in_flight" + //! @member int portals_in_flight   //! Currently still open portals, i.e. running statements.   //! @endmapping   //!   //! @note   //! This function is PostgreSQL-specific, and thus it is not available   //! through the generic SQL-interface.   mapping(string:mixed) getstatistics() {    mapping(string:mixed) stats=([    "warnings_dropped":warningsdropcount,    "skipped_describe_count":skippeddescribe,
pike.git/lib/modules/Sql.pmod/pgsql.pike:474:   //! @note   //! This function is PostgreSQL-specific, and thus it is not available   //! through the generic SQL-interface.   int settimeout(void|int newtimeout) {    int oldtimeout=timeout;    if(!zero_type(newtimeout) && newtimeout>0)    timeout=newtimeout;    return oldtimeout;   }    - //! Returns the old portalbuffersize, sets the new portalbuffersize - //! for buffering partially concurrent queries. + //! @param newportalbuffersize + //! Sets the new portalbuffersize for buffering partially concurrent queries.   //! -  + //! @returns + //! The previous portalbuffersize. + //!   //! @note   //! This function is PostgreSQL-specific, and thus it is not available   //! through the generic SQL-interface.   int setportalbuffersize(void|int newportalbuffersize) {    int oldportalbuffersize=portalbuffersize;    if(!zero_type(newportalbuffersize) && newportalbuffersize>0)    portalbuffersize=newportalbuffersize;    return oldportalbuffersize;   }    - //! Returns the old fetchlimit, sets the new fetchlimit to interleave - //! queries. + //! @param newfetchlimit + //! Sets the new fetchlimit to interleave queries.   //! -  + //! @returns + //! The previous fetchlimit. + //!   //! @note   //! This function is PostgreSQL-specific, and thus it is not available   //! through the generic SQL-interface.   int setfetchlimit(void|int newfetchlimit) {    int oldfetchlimit=_fetchlimit;    if(!zero_type(newfetchlimit) && newfetchlimit>=0)    _fetchlimit=newfetchlimit;    return oldfetchlimit;   }   
pike.git/lib/modules/Sql.pmod/pgsql.pike:1121:   #endif   }      //! 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.   //!   //! @note   //! This function @b{can@} raise exceptions if something goes wrong - //! (backend process not running, not enough permissions..) + //! (backend process not running, insufficient privileges...)   //!   //! @seealso   //! @[create()]   void select_db(string dbname) {    database=dbname;    reconnect();    reconnected=0;   }      //! With PostgreSQL you can LISTEN to NOTIFY events.   //! This function allows you to detect and handle such events.   //!   //! @param condition   //! Name of the notification event we're listening   //! to. A special case is the empty string, which matches all events,   //! and can be used as fallback function which is called only when the   //! specific condition is not handled. Another special case is - //! @[_reconnect] which gets called whenever the connection unexpectedly + //! @ref{_reconnect@} which gets called whenever the connection unexpectedly   //! drops and reconnects to the database.   //!   //! @param notify_cb   //! Function to be called on receiving a notification-event of - //! condition @[condition]. + //! condition @ref{condition@}.   //! The callback function is invoked with   //! @expr{void notify_cb(pid,condition,extrainfo, .. args);@} - //! @[pid] is the process id of the database session that originated - //! the event. @[condition] contains the current condition. - //! @[extrainfo] contains optional extra information specified by + //! @ref{pid@} is the process id of the database session that originated + //! the event. @ref{condition@} contains the current condition. + //! @ref{extrainfo@} contains optional extra information specified by   //! the database. - //! The rest of the arguments to @[notify_cb] are passed - //! verbatim from @[args]. + //! The rest of the arguments to @ref{notify_cb@} are passed + //! verbatim from @ref{args@}.   //! The callback function must return no value.   //!   //! @param selfnotify   //! Normally notify events generated by your own session are ignored. - //! If you want to receive those as well, set @[selfnotify] to one. + //! If you want to receive those as well, set @ref{selfnotify@} to one.   //!   //! @param args - //! Extra arguments to pass to @[notify_cb]. + //! Extra arguments to pass to @ref{notify_cb@}.   //!   //! @note   //! This function is PostgreSQL-specific, and thus it is not available   //! through the generic SQL-interface.   void set_notify_callback(string condition,    void|function(int,string,string,mixed ...:void) notify_cb,void|int selfnotify,    mixed ... args) {    if(!notify_cb)    m_delete(notifylist,condition);    else {
pike.git/lib/modules/Sql.pmod/pgsql.pike:1208:   //! @[big_query()], @[quotebinary()], @[create()]   string quote(string s) {    string r=runtimeparameter->standard_conforming_strings;    if(r && r=="on")    return replace(s, "'", "''");    return replace(s, ({ "'", "\\" }), ({ "''", "\\\\" }) );   }      //! @returns   //! The given string, but escapes/quotes all contained magic characters - //! according to the quoting rules of the current session for binary (bytea) - //! arguments in textual SQL-queries. + //! for binary (bytea) arguments in textual SQL-queries.   //!   //! @note   //! Quoting must not be done for parameters passed in bindings.   //!   //! @seealso   //! @[big_query()], @[quote()]   //!   //! @note   //! This function is PostgreSQL-specific, and thus it is not available   //! through the generic SQL-interface.   string quotebinary(string s) {    return replace(s, ({ "'", "\\", "\0" }), ({ "''", "\\\\", "\\000" }) );   }      //! This function creates a new database (assuming we - //! have enough privileges to do this). + //! have sufficient privileges to do this).   //!   //! @param db   //! Name of the new database.   //!   //! @seealso   //! @[drop_db()]   void create_db(string db) {    big_query("CREATE DATABASE :db",([":db":db]));   }      //! This function destroys a database and all the data it contains (assuming - //! we have enough privileges to do so). It is not possible to delete + //! we have sufficient privileges to do so). It is not possible to delete   //! the database you're currently connected to. You can connect to database   //! @ref{template1@} to avoid connecting to any live database.   //!   //! @param db   //! Name of the database to be deleted.   //!   //! @seealso   //! @[create_db()]   void drop_db(string db) {    big_query("DROP DATABASE :db",([":db":db]));
pike.git/lib/modules/Sql.pmod/pgsql.pike:1308:    ret+=({row[0]});    return ret;   }      //! @returns   //! A mapping, indexed on the column name, of mappings describing   //! the attributes of a table of the current database.   //! The currently defined fields are:   //!   //! @mapping - //! @member int "is_shared" - //! @member string "owner" + //! @member int is_shared + //! @member string owner   //! Tableowner - //! @member string "length" + //! @member string length   //! Size of the columndatatype - //! @member string "text" + //! @member string text   //! A textual description of the internal (to the server) type-name - //! @member mixed "default" + //! @member mixed default   //! Default value for the column - //! @member mixed "schema" + //! @member mixed schema   //! Schema the table belongs to - //! @member mixed "table" + //! @member mixed table   //! Name of the table - //! @member mixed "kind" + //! @member mixed kind   //! Type of table - //! @member mixed "has_index" + //! @member mixed has_index   //! If the table has any indices - //! @member mixed "has_primarykey" + //! @member mixed has_primarykey   //! If the table has a primary key - //! @member mixed "rowcount" + //! @member mixed rowcount   //! Estimated rowcount of the table - //! @member mixed "pagecount" + //! @member mixed pagecount   //! Estimated pagecount of the table   //! @endmapping   //!   //! @param glob   //! If specified, list only the tables with matching names.   //! Setting it to @expr{*@} will include system columns in the list.   array(mapping(string:mixed)) list_fields(void|string table, void|string glob) {    array row, ret=({});    string schema=UNDEFINED;   
pike.git/lib/modules/Sql.pmod/pgsql.pike:1484:    case 'I':return "idle";    case 'T':return "intransaction";    case 'E':return "infailedtransaction";    }    return "";   }      //! @returns   //! The current commitstatus of the connection. Returns either one of:   //! @string - //! @value "idle" - //! @value "intransaction" - //! @value "infailedtransaction" + //! @value idle + //! @value intransaction + //! @value infailedtransaction   //! @endstring   //!   //! @note   //! This function is PostgreSQL-specific, and thus it is not available   //! through the generic SQL-interface.   final string status_commit() {    return trbackendst(backendstatus);   }      final private array(string) closestatement(mapping tp) {
pike.git/lib/modules/Sql.pmod/pgsql.pike:1511:    ret=({"C",_c.plugint32(4+1+sizeof(oldprep)+1),    "S",oldprep,"\0"});    }    return ret;   }      //! @decl Sql.pgsql_util.pgsql_result big_query(string query)   //! @decl Sql.pgsql_util.pgsql_result big_query(string query, mapping bindings)   //!   //! 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. + //! database. If you wish to use the simpler @[Sql.Sql()->query()] function, + //! you need to use the @[Sql.Sql] generic SQL-object.   //! - //! Bindings are supported natively straight through the network. + //! Bindings are supported natively straight across the network.   //! Special bindings supported are:   //! @mapping   //! @member int ":_cache" - //! Forces caching or no caching for the query at hand. + //! Forces caching on or off for the query at hand.   //! @endmapping   //!   //! @returns   //! A @[Sql.pgsql_util.pgsql_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 + //! @[Sql.sql_result] standard interface for accessing data). It is + //! recommended to use @[Sql.Sql()->query()] for simpler queries (because + //! it is easier to handle, but stores all the result in memory), and + //! @[Sql.Sql()->big_query()] for queries you expect to return huge amounts of   //! data (it's harder to handle, but fetches results on demand).   //!   //! @note   //! This function @b{can@} raise exceptions.   //!   //! @note   //! This function supports multiple simultaneous queries (portals) on a single   //! database connection. This is a feature not commonly supported by other   //! database backends.   //!   //! @note   //! This function does not support multiple queries in one querystring.   //! I.e. it allows for but does not require a trailing semicolon, but it - //! simply ignores any commands after the first semicolon. This can be - //! viewed as a limited protection against SQL-injection attacks. + //! simply ignores any commands after the first unquoted semicolon. This can + //! be viewed as a limited protection against SQL-injection attacks.   //!   //! @seealso - //! @[Sql.Sql], @[Sql.sql_result], @[Sql.pgsql_util.pgsql_result] + //! @[big_typed_query()], @[Sql.Sql], @[Sql.sql_result], + //! @[Sql.Sql()->query()], @[Sql.pgsql_util.pgsql_result]   object big_query(string q,void|mapping(string|int:mixed) bindings,    void|int _alltyped) {    string preparedname="";    string portalname="";    int forcecache=-1;    if(stringp(q) && String.width(q)>8)    q=string_to_utf8(q);    array(string|int) paramValues;    array(string) from,to;    if(bindings) {
pike.git/lib/modules/Sql.pmod/pgsql.pike:1818:    { object tportal=_c.portal; // Make copy, because it might dislodge    tportal->fetch_row(1); // upon initial fetch_row()    return tportal;    }   }      //! This is an alias for @[big_query()], since @[big_query()] already supports   //! streaming of multiple simultaneous queries through the same connection.   //!   //! @seealso - //! @[big_query()], @[Sql.Sql], @[Sql.sql_result] + //! @[big_query()], @[big_typed_query()], @[Sql.Sql], @[Sql.sql_result]   object streaming_query(string q,void|mapping(string|int:mixed) bindings) {    return big_query(q,bindings);   }      //! This function returns an object that allows streaming and typed   //! results.   //!   //! @seealso   //! @[big_query()], @[Sql.Sql], @[Sql.sql_result]   object big_typed_query(string q,void|mapping(string|int:mixed) bindings) {    return big_query(q,bindings,1);   }