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

version» Context lines:

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;