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:10:
//! //! This module replaces the functionality of the older @[Sql.postgres] //! and @[Postgres.postgres] modules. //! //! This module supports the following features: //! @ul //! @item //! PostgreSQL network protocol version 3, authentication methods //! currently supported are: cleartext, md5 and scram (recommended). //! @item
+
//! Optional asynchronous query interface through callbacks.
+
//! @item
//! Streaming queries which do not buffer the whole resultset in memory. //! @item //! Automatic binary transfers to and from the database for most common //! datatypes (amongst others: integer, text and bytea types). //! @item //! Automatic character set conversion and native wide string support. //! Supports UTF8/Unicode for multibyte characters, and all single-byte //! character sets supported by the database. //! @item //! SQL-injection protection by allowing just one statement per query
pike.git/lib/modules/Sql.pmod/pgsql.pike:45:
//! @endul //! Check the PostgreSQL documentation for further details. //! //! @note //! Multiple simultaneous queries on the same database connection is a //! feature that none of the other database drivers for Pike support. //! So, although it's efficient, its use will make switching database drivers //! difficult. //! //! @seealso
-
//! @[Sql.Sql], @[Sql.postgres],
@url{http
://www.postgresql.org/docs/@}
+
//! @[Sql.Sql], @[Sql.postgres],
+
//!
@url{https
://www.postgresql.org/docs/
current/static/
@}
#pike __REAL_VERSION__ #pragma dynamic_dot #require constant(Thread.Thread) #include "pgsql.h" #define ERROR(X ...) predef::error(X) inherit __builtin.Sql.Connection;
pike.git/lib/modules/Sql.pmod/pgsql.pike:84:
switch(type) { case 'O': res = sprintf(DRIVERNAME"(%s@%s:%d/%s,%d,%d)", proxy.user, proxy.host, proxy.port, proxy.database, proxy.c?->socket && proxy.c->socket->query_fd(), proxy.backendpid); break; } return res; }
-
//! With no arguments, this function initialises
(reinitialises if
a
-
//!
connection
has been set up previously) a connection
to the
+
//! With no arguments, this function initialises 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 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
pike.git/lib/modules/Sql.pmod/pgsql.pike:119:
//! 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" //! If the database supports and allows SSL connections, the session //! will be SSL encrypted, if not, the connection will abort. //! @member int "text_query" //! Send queries to and retrieve results from the database using text //! instead of the, generally more efficient, default native binary method. //! Turning this on will allow multiple statements per query separated
-
//! by semicolons.
+
//! by semicolons
(not recommended)
.
//! @member int "sync_parse" //! Set it to zero to turn synchronous parsing off for statements. //! Setting this to off can cause surprises because statements could //! be parsed before the previous statements have been executed //! (e.g. references to temporary tables created in the preceding //! statement), //! but it can speed up parsing due to increased parallelism. //! @member int "cache_autoprepared_statements" //! If set to zero, it disables the automatic statement prepare and //! cache logic; caching prepared statements can be problematic
pike.git/lib/modules/Sql.pmod/pgsql.pike:147:
//! When on, backslashes in strings must not be escaped any longer, //! @[quote()] automatically adjusts quoting strategy accordingly. //! @member string "escape_string_warning" //! When on, a warning is issued if a backslash (\) appears in an //! ordinary string literal and @expr{"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,
+
//! 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 //! server doesn't respond, if the database doesn't exist or is not //! accessible to you. //!
-
+
//! @note
+
//! It is possible that the exception from a failed connect
+
//! will not be triggered on this call (because the connect
+
//! proceeds asynchronously in the background), but on the first
+
//! attempt to actually use the database instead.
+
//!
//! @seealso //! @[Postgres.postgres], @[Sql.Sql], @[select_db()],
-
//!
@url{http
://www.postgresql.org/
search
/
?u=%2Fdocs%2Fcurrent%2F&q=client+connection+search_path@}
+
//!
@url{https
://www.postgresql.org/
docs
/
current/static/runtime-config-client.html@}
protected void create(void|string host, void|string database, void|string user, void|string pass, void|mapping(string:mixed) options) { string spass = pass && pass != "" ? Standards.IDNA.to_ascii(pass) : pass; if(pass) { String.secure(pass); pass = "CENSORED"; } proxy = .pgsql_util.proxy(host, database, user && user != "" ? Standards.IDNA.to_ascii(user, 1) : user,
pike.git/lib/modules/Sql.pmod/pgsql.pike:194:
//! To clear the error, set it to @expr{1@}. //! //! @seealso //! @[big_query()] /*semi*/final string error(void|int clear) { throwdelayederror(this); return proxy.geterror(clear); } //! This function returns a string describing what host are we talking to,
-
//! and how (TCP/IP or UNIX
sockets
).
+
//! and how (TCP/IP or UNIX
socket
).
//! //! @seealso //! @[server_info()] /*semi*/final string host_info() { return proxy.host_info(); } //! Returns true if the connection seems to be open. //! //! @note //! This function only checks that there's an open connection, //! and that the other end hasn't closed it yet. No data is //! sent over the connection. //! //! For a more reliable check of whether the connection
-
//! is alive, please use @[ping()].
+
//! is alive, please use @[ping()]
instead
.
//! //! @seealso //! @[ping()] /*semi*/final int is_open() { return proxy.is_open(); } //! Check whether the connection is alive. //! //! @returns
pike.git/lib/modules/Sql.pmod/pgsql.pike:255:
} //! Changes the connection charset. When set to @expr{"UTF8"@}, the query, //! parameters and results can be Pike-native wide strings. //! //! @param charset //! A PostgreSQL charset name. //! //! @seealso //! @[get_charset()], @[create()],
-
//!
@url{http
://www.postgresql.org/
search
/
?u=%2Fdocs%2Fcurrent%2F&q=character+sets@}
+
//!
@url{https
://www.postgresql.org/
docs
/
current/static/multibyte.html@}
/*semi*/final void set_charset(string charset) { if(charset) big_query(sprintf("SET CLIENT_ENCODING TO '%s'", quote(charset))); } //! @returns //! The PostgreSQL name for the current connection charset. //! //! @seealso //! @[set_charset()], @[getruntimeparameters()],
-
//!
@url{http
://www.postgresql.org/
search
/
?u=%2Fdocs%2Fcurrent%2F&q=character+sets@}
+
//!
@url{https
://www.postgresql.org/
docs
/
current/static/multibyte.html@}
/*semi*/final string get_charset() { return getruntimeparameters()[CLIENT_ENCODING]; } //! @returns //! Currently active runtimeparameters for //! the open session; these are initialised by the @tt{options@} parameter //! during session creation, and then processed and returned by the server. //! Common values are: //! @mapping
pike.git/lib/modules/Sql.pmod/pgsql.pike:305:
//! Reports wether the database supports 64-bit-integer dates and times. //! @member string "server_version" //! Shows the server version, e.g. @expr{"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
://www.postgresql.org/
search
/
?u=%2Fdocs%2Fcurrent%2F&q=client+connection+search_path@}
+
//!
@url{https
://www.postgresql.org/
docs
/
current/static/runtime-config-client.html@}
//! //! @note //! This function is PostgreSQL-specific. /*semi*/final mapping(string:string) getruntimeparameters() { waitauthready(); return proxy.runtimeparameter + ([]); } //! @returns //! A set of statistics for the current session:
pike.git/lib/modules/Sql.pmod/pgsql.pike:867:
} private inline string int2hex(int i) { return String.int2hex(i); } private inline void throwdelayederror(object parent) { .pgsql_util.throwdelayederror(parent); }
-
//! This is the only provided interface which allows you to query the
-
//! database.
If
you
wish
to
use
the
simpler
@[
Sql.Sql()->
query()]
function,
-
//! you need to use the @[Sql
.
Sql] generic SQL-object.
+
//! This is the only provided
direct
interface which allows you to query the
+
//! database.
A
simpler
synchronous
interface
can
be
used through
@[query()].
//! //! Bindings are supported natively straight across the network. //! Special bindings supported are: //! @mapping //! @member int ":_cache" //! Forces caching on or off for the query at hand. //! @member int ":_text" //! Forces text mode in communication with the database for queries on or off //! for the query at hand. Potentially more efficient than the default //! binary method for simple queries with small or no result sets.
pike.git/lib/modules/Sql.pmod/pgsql.pike:901:
//! @note //! The bindings-parameter passed to this function must remain unaltered //! until the parameters have been sent to the database. The driver //! currently does not expose this moment, but to avoid a race condition //! it is sufficient to keep them unaltered until the first resultrow //! has been fetched (or EOF is reached, in case of no resultrows). //! //! @returns //! A @[Sql.pgsql_util.sql_result] object (which conforms to the //! @[Sql.sql_result] standard interface for accessing data). It is
-
//! recommended to use @[
Sql.Sql()->
query()] for simpler queries (because
+
//! recommended to use @[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
+
//! @[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, by default, 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 unquoted semicolon. This can //! be viewed as a limited protection against SQL-injection attacks. //! To make it support multiple queries in one querystring, use the
-
//! @ref{:_text@} option.
+
//! @ref{:_text@} option
(not recommended)
.
//! //! @seealso //! @[big_typed_query()], @[Sql.Sql], @[Sql.sql_result],
-
//! @[
Sql.Sql()->
query()], @[Sql.pgsql_util.sql_result]
+
//! @[query()], @[Sql.pgsql_util.sql_result]
/*semi*/final .pgsql_util.sql_result big_query(string q, void|mapping(string|int:mixed) bindings, void|int _alltyped) { throwdelayederror(this); string preparedname = ""; mapping(string:mixed) options = proxy.options; .pgsql_util.conxion c = proxy.c; int forcecache = -1, forcetext = options.text_query; int syncparse = zero_type(options.sync_parse) ? -1 : options.sync_parse;