pike.git
/
lib
/
modules
/
Sql.pmod
/
pgsql.pike
version
»
Context lines:
10
20
40
80
file
none
3
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); }