Method Sql.pgsql()->big_query()

Method big_query

final .pgsql_util.sql_result big_query(string q, void|mapping(string|int:mixed) bindings, void|int _alltyped)

Description

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:

`":_cache" : int`	Forces caching on or off for the query at hand.
`":_text" : int`	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. Note that this mode causes all but the first query result of a list of semicolon separated statements to be discarded.
`":_sync" : int`	Forces synchronous parsing on or 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.
`":_debug" : int`	Sets the debuglevel for query tracing.

Note

The parameters referenced via the bindings-parameter-mapping 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 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 data (it's harder to handle, but fetches results on demand).

Note

This function 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 :_text option (not recommended).