package pq

Source

An opaque handle to a cancel object.

An opaque handle to a connection.

Responsible for handling a notice or warning message given in text form. It is passed the string text of the message (including a trailing newline), plus a user pointer from set_notice_processor.

The default notice processor prints to stderr.

Called when a notice is retrieved from the server or generated internally by libpq. It is passed a Result in the state of Non_Fatal_Error. (This allows the receiver to extract individual fields using result_error_field, or obtain a complete preformatted message using result_error_message or result_verbose_error_message.) The same user pointer passed to set_notice_receiver is passed.

The default notice receiver extracts the message using result_error_message and passes it on to the notice processor.

An opaque handle to a result.

The result structure encapsulates the result returned by the server. libpq application programmers should be careful to maintain the result abstraction. Use the accessor functions to get at the contents. Avoid directly referencing the fields because they are subject to change.

Returns the process ID (PID) of the backend process handling this connection.

The backend PID is useful for debugging purposes and for comparison to NOTIFY messages (which include the PID of the notifying backend process). Note that the PID belongs to the process executing on the database server host, not the local host.

Requests that the server abandon processing of the current command.

If false is returned errbuf is filled with an explanatory error message. errbuf must be a char array of size errbuf_size(the recommended size is 256 bytes).

Frees the storage associated with a Result. Every command result should be freed via clear when it is no longer needed.

You can keep a Result object around for as long as you need it; it does not go away when you issue a new command, nor even if you close the connection. To get rid of it, you must call clear. Failure to do this will result in memory leaks in your application.

Returns the client encoding.

Note that it returns the encoding ID, not a symbolic string. If unsuccessful, it returns -1. To convert an encoding ID to an encoding name, use encoding_to_char.

Returns the command status tag from the SQL command that generated the Result.

Commonly this is just the name of the command, but it might include additional data such as the number of rows processed. The caller should not free the results directly. It will be freed when the associated Result handle is passed to clear.

Returns the number of rows affected by the SQL command.

This function returns a string containing the number of rows affected by the SQL statement that generated the Result. This function can only be used following the execution of a SELECT, CREATE TABLE AS, INSERT, UPDATE, DELETE, MOVE, FETCH or COPY statement, or an EXECUTE of a prepared query that contains an INSERT, UPDATE or DELETE statement. If the command that generated the Result was anything else, an empty string is returned.

The caller should not free the return value directly. It will be freed when the associated Result handle is passed to clear.

Returns the default connection options.

NOTE: After processing the options array, free it by passing it to conninfoFree. If that is not done, a small amount of memory is leaked for each call to conndefaults.

More info

Poll the connection status after one of the 2 functions above succeeds.

More info

Makes a connection to the database server in a nonblocking manner.

More info

Makes a connection to the database server in a nonblocking manner.

More info

Makes a new connection to the database server.

This function opens a new database connection using the parameters taken from the string conninfo.

The passed string can be empty to use all default parameters, or it can contain one or more parameter settings separated by whitespace. Each parameter setting is in the form keyword = value. Spaces around the equal sign are optional. To write an empty value, or a value containing spaces, surround it in single quotes, e.g., keyword = 'a value. Single quotes and backslashes withing the value must be escaped with a backslash, i.e., \' and \\.

Makes a new connection to the database server.

This function opens a new database connection using the parameters taken from two nil-terminated arrays. The first, keywords, is defined as an array of strings, each one being a key word. The second, values, gives the value for each key word.

When expand_dbname is true, the dbname key word value is allowed to be recognized as a conninfo string. See below for details.

The passed arrays can be empty to use all default parameters, or can contain one or more parameter settings. They should be matched in length. Processing will stop with the last non-nil element of the keywords array.

More info

Returns true if the connection authentication method required a password, but none was available.

Returns true if the connection authentication method used GSSAPI.

Returns true if the connection authentication method used a password.

Frees memory allocated by conn_defaults and conninfo_parse.

A simple free_mem will not do for this, since the array contains references to subsidiary strings.

Returns parsed connection options from the provided connection string.

No defaults are inserted.

If errmsg is not nil, then errmsg^ is set to nil on success, else to an allocated error string explaining the problem. (It is also possible for errmsg^ to be nil and the result to be nil, this indicates out-of-memory.).

NOTE: After processing the options array , free it by passing it to conninfoFree. If that is not done, some memory is leaked for each callto conninfoParse. Conversely, if an error occurs and errmsg is not nil, be sure to free the error string using freemem.

More info

If input is available from the server, consume it.

This normally returns true, indicating "no error", but returns false if there was some kind of trouble (in which case error_message can be consulted).

Note that the result does not say whether any input data was actually collected. After calling this, the application can check is_busy and/or notifies to see if their state has changed.

This can be called even if the application is not prepared to deal with the result or notification just yet. The function will read available data and save it in a buffer, thereby causing a select read-ready indication to go away.

The application can thus use consume_input to clear the select condition immediately, and then examine the results at leisure.

Makes a copy of the Result object. The copy is not linked to the source result in any way and clear must be called when it is no longer needed.

Returns nil on failure.

This is not intended to make an exact copy. The returned result is always put into Tuples_Ok status, and does not copy any error message in the source. (It does copy the command status string, however.) The flags argument determines what else is copied.

Returns the database name of the connection.

Submits a request to obtain information about the specified portal, and waits for completion.

This allows an application to obtain info about a previously created portal. (libpq does not provide any direct access to portals, but you can use this function to inspect the properties of a cursor created with a DECLARE CURSOR SQL statement. This is only supported in protocol 3.0 and later; it will fail when using protocol 2.0.

portal_name can be empty or nil to reference the unnamed portal, otherwise it must be the name of an existing portal. On success, result status OK will be returned. The functions n_fields, f_name, f_type etc can be applied to the result to obtain info about the result columns.

Submits a request to obtain information about the specified prepared statement, and waits for completion.

This allows an application to obtain information about a previously prepared statement. This is supported in protocol 3.0 and later; it will fail when using protocol 2.0.

stmt_name can be empty or nil to reference the unnamed statement, otherwise it must be the name of an existing prepared statement. On success, result status OK will be returned. The functions n_params and param_types can be applied to this result to obtain info about the parameters of the prepared statement, and the function n_fields, f_name, f_type etc provide info about the result columns.

Converts an encoding ID to a string name.

Prepares the encrypted form of a PostgreSQL password.

This function is intended to be used by client applications that wish to send commands like ALTER USER joe PASSWORD 'pwd'. It is good practice not to send the original cleartext password in such a command, because it might be exposed in command logs, activity displays, and so on. Instead, use this function to convert the password to encrypted form before it is sent.

The passwd and user arguments are the cleartext password, and the SQL name of the user it is for. algorithm specifies the encryption algorithm to use to encrypt the password. Currently supported algorithms are md5 and scram-sha-256 (on and off are also accepted as aliases for md5, for compatibility with older server versions). Note that support for scram-sha-256 was introduced in PostgreSQL version 10, and will not work correctly with older server versions. If algorithm is NULL, this function will query the server for the current value of the password_encryption setting. That can block, and will fail if the current transaction is aborted, or if the connection is busy executing another query. If you wish to use the default algorithm for the server but want to avoid blocking, query password_encryption yourself before calling PQencryptPasswordConn, and pass that value as the algorithm.

NOTE: The return value is a string allocated by malloc. Use PQfreemem to free the result when done with it.

The caller can assume the string doesn't contain any special characters that would require escaping. On error, returns NULL, and a suitable message is stored in the connection object.

Causes a connection to enter pipeline mode. Returns false if the connection is not idle, or is waiting for input. This does not actually send anything to the server.

Returns the error message most recently generated by an operation on the connection.

The returned string does not need to be freed, note that the string is overwritten between function calls so you can't keep it around after calling another function.

Escapes binary data for use within an SQL command with the type bytea. As with escape_string_conn this is only used when inserting data directly into an SQL command string.

Special characters are either escaped using hex or backslash escaping, see Section 8.4 for more info.

A terminating zero byte is not required and should not be counted in the length parameter.

The to_length point to a variable that will hold the resultant escaped length (including zero byte).

This function allocates and the result should be freed with free_mem.

The string will NOT automatically be surrounded by single quotes.

On error, this returns nil and the Conn will have an error set.

Escapes a string for use as an SQL identifier, such as a table, column, or function name. This is useful when a user-supplied identifier might contain special characters that would otherwise not be interpreted as part of the identifier by the SQL parser, or when the identifier might contain upper case characters whose case should be preserved.

This function allocates and the result should be freed with free_mem.

A terminating zero byte is not required and should not be counted in the length parameter.

The return value has special characters escaped and contains a zero byte. The string will also be surrounded by double quotes.

On error, this returns nil and the Conn will have an error set.

Escapes a string for use within an SQL command. This is useful when inserting data values as literal constants in SQL commands. Certain characters (such as qoutes or backslashes) must be escaped to prevent them from being interpreted specially by the SQL parser.

This function allocates and the result should be freed with free_mem.

A terminating zero byte is not required and should not be counted in the length parameter.

The return value has special characters escaped and contains a zero byte. The single quotes that must surround PostgreSQL string literals are included in the result string.

On error, this returns nil and the Conn will have an error set.

Note that it is not necessary nor correct to do escaping when a data value is passed as a separate parameter in exec_params or its sibling routines.

Escapes string literals, much like escape_literal but the caller is responsible for providing an appropriately sized buffer. Furthermore, it does not surround the string with single quotes.

A terminating zero byte is not required and should not be counted in the length parameter.

The returned value is the amount of bytes (excluding zero byte) written into to.

If the err parameter is not nil it is used to indicate error condition, true means an error occurred. A suitable message is stored in the Conn object.

NOTE: the length of to must be at least 1+length*2 or the operation is undefined behavior.

Submits a command to the server and waits for the result.

Returns a Result pointer or nil (when out of memory or inability to send to server). The result_status function should be called to check the return value for any errors. The error_message function can be used to get more information about the errors.

The command string can include multiple SQL commands (seperated by semicolons). Multiple queries sent in a single exec call are processed in a single transaction, unless there are explicit BEGIN/COMMIT commands included in the query string to divide it into multiple transactions. Note however that the returned Result struct describes only the result of the last command executed. Should one of the commands fail, processing of the string stops with it and the returned Result describes the error condition.

Submits a command to the server and waits for the result, with the ability to pass parameters separately from the SQL command text.

exec_params is like exec, but offers additional functionality; parameter values can be specified separately from the command string proper, and query results can be requested in either text or binary format. exec_params is supported only in protocol 3.0 and later connections; It will fail when using protocol 2.0.

The primary advantage over exec is that parameter values can be separated from the command string, thus avoiding the need for tedious and error-prone quoting and escaping.

NOTE: Unlike exec it allows at most one SQL command in the given string. (There can be semicolons in it, but not more than one nonempty command.) This is a limitation of the underlying protocol, but has some usefulness as an extra defense against SQL-injection attacks.

INFO: Specifying parameter types via OIDs is tedious, particularly if you prefer not to hard-wire particular OID values into your program. However, you can avoid doing so even in cases where the server by itself cannot determine the type of the parameter, or chooses a different type than you want. In the SQL command text, attach an explicit cast to the parameter symbol to show what data type you will send. For example: SELECT * FROM mytable WHERE x = $1::bigint; This forces the parameter $1 to be treated as bigint, whereas by default it would be assigned the same type as x. Forcing the parameter type decision, either this way or by specifying a numeric type OID, is strongly recommended when sending parameters values in binary format, because binary format has less redundancy than text format and so there is less chance that the server will detect a type mismatch mistake for you.

Inputs:
conn: The connection object to send the command through.

command: The SQL command string to be executed. If parameters are used, they are referred to in the comand string as $1, $2, etc.

n_params: The number of parameters supplied; it is the length of the arrays param_types, param_values, param_lengths, and param_formats.

param_types: Specifies, by OID, the data types to be assigned to the parameter symbols. If param_types is nil, or any particular element in the array is zero, the server infers the data type for the parameter symbol in the same way it would do for an untyped literal string.

param_values: Specifies the actual values of the parameters. A nil pointer in this array means the corresponding parameter is nil; otherwise the pointer points to a zero-terminated text string (for text formats) or binary data in the format expected by the server (for binary format).

param_lengths: Specifies the actual data lengths of binary-format parameters. It is ignored for nil parameters and text-format parameters. The array pointer can be nil when there are no binary parameters.

param_formats: Specifies whether parameters are text (put a zero in the array entry for the corresponding parameter) or binary (put a one in the array entry for the corresponding parameter). If the array pointer is nil then all parameters are presumed to be text strings.

result_format: Specify zero to obtain results in text format, or one to obtain results in binary format. (There is not currently a provision to obtain different result columns in different formats, although that is possible in the underlying protocol.)

Sends a request to execute a prepared statement with given parameters and waits for the result.

exec_prepared is like exec_params, but the command to be executed is specified by naming a previously-prepared statement, instead of giving a query string. This feature allows commands that will be used repeatedly to be parsed and planned just once, rather than each time they are executed. The statement must have been prepared previously in the current session. This is supported in protocol 3.0 and later connections; it will fail when using protocol version 2.0.

The parameters are identical to exec_params, except that the name of the prepared statement is given instead of a query string, and the param_types parameter is not present (it is not needed since the prepared statement's parameter types were determined when it was created).

Causes a connection to exit pipeline mode if it is currently in pipeline mode and has an empty queue and no pending results. Returns false if above is not true or if there is an error on the pipeline that first needs clearing.

Returns the format code indicating the format of the given column. Column numbers start at 0.

Returns the type modifier of the column associated with the given column number. Column numbers start at 0.

The interpretation of modifier values is type-specific; they typically indicate precision or size limits. The value -1 is used to indicate "no information available". Most data types do not use modifiers, in which case the value is always -1.

Returns the column name associated with the given column number. Column numbers start at 0. The caller should not free the result directly. It will be freed when the associated Result is passed to clear.

nil is returned if the column number is out of range.

Returns the column number associated with the given column name.

-1 is returned if the given name does not match any column.

The given name is treated like an identifier in an SQL command, it is downcased unless double-qouted.

Returns the size in bytes of the column associated with the given column number. Column numbers start at 0.

This returns the space allocated for this column in a database row, in other words the size of the server's internal representation of the data type. (Accordingly, it is not really very useful to clients.) A negative value indicates the data type is variable-length.

Returns an OID of the table from which the given column was fetched. Column numbers start at 0.

INVALID_OID is returned if the column number is out of range, or if the specified column is not a simple reference to a table column, or when using pre-3.0 protocol. You can query the system table pg_class to determine exactly which table is referenced.

Returns the column number (within its table) of the column making up the specified query result column. Query-result column numbers start at 0, but table columns have nonzero numbers.

Zero is returned if the column number is out of range, or if the specified column is not a simple reference to a table column, or when using pre-3.0 protocol.

Returns the data type associated with the given column number. The integer returned is the internal OID number of the type. Column numbers start at 0.

You can query the system table pg_type to obtain the names and properties of the various data types. The OIDs of the built-in data types are defined in the src/include/catalog/pg_type.h header.

Closes the connection to the server. Also frees memory used by the Conn object.

Note that even if the server connection attempt fails (as indicated by status), the application should call finish to free the memory used by the Conn object. The conn pointer must not be used again after finish has been called.

Fires a PGEVT_RESULTCREATE event for each event procedure registered in the Result object.

Attempts to flush any queued output data to the server.

Frees the data structure created by get_cancel.

Frees memory allocated by libpq.

It is particularly important that this function, rather than the default free, be used on Windows. This is because allocating memory in a DLL and releasing it in the application works only if multithreaded/single-threaded, release/debug, and static/dynamic flags are the same for the DLL and the application. On non-Windows platforms, this function is the same as the default free.

Creates a data structure containing the information needed to cancel a command issued through a particular db connection.

Caller must free with free_cancel.

Receives data from the server during COPY_OUT state.

Returned one row at a time.

Successful return involves allocation of a chunk of memory to hold the data. The buffer parameter must be non-nil. buffer^ is set to point to the allocated memory, or to nil. A non-nil buffer should be freed by the caller with free_mem.

The return value is the length of the allocated buffer. Zero is returned for in progress COPY's when async is set to true. -1 is returned when the COPY is done, call get_result to obtain the final result. -2 is returned when an error occurred, consult error_message for the reason.

When async, this will not block waiting for input, when 0 is returned, wait for read-ready and then call consume_input before calling get_copy_data again.

Tests the field for a null value. Row and column numbers start at 0.

Returns the actual length of the field value in bytes. Row and column numbers start at 0.

This is the actual data length for the particular data value, the size of the objects pointed to by get_value. For text data format this is the same as strlen(). For binary format this is essential information. Note that one should not rely on f_size to obtain the actual data length.

Waits for the next result from a prior asynchronous call and returns it. A nil pointer is returned when the command is complete and there will be no more results.

This must be called repeatedly until it returns a nil pointer, indicating that the command is done. Each non-nil result from this should be processed using the same Result procedures previously described. Don't forget to free each result with clear when done with it.

Note that this will block only if a command is active and the necessary response data has not yet been ready to read by consume_input.

NOTE: even when result_status indicates a fatal error, get_result should be called until it returns a nil pointer to allow libpq to process the error information completely.

Using send_query and get_result solves one of exec's problems; if a command string contains multiple SQL commands, the results of those commands can be obtained individually.

In pipeline mode, this will return normally unless an error occurs; for any subsequent query sent after the one that caused the error until (and excluding) the next synchronization point, a special result of type Pipeline_Aborted will be returned, and a null pointer will be returned after it. When the pipeline synchronization point is reached, a result of type Pipeline_Sync will be returned. The result of the next query after the synchronization point follows immediately (that is, no null pointer is returned after the synchronization point.)

Returns a single field value of one row of a Result. Row and column numbers start at 0. The caller should not free the result directly. It will be freed when the associated Result handle is passed to clear.

For data in text format, the value returned is a null-terminated character string representation of the field value. For data in binary format, the value is in the binary representation determined by the data type's typsend and typreceive functions. (The value is actually followed by a zero byte in this case too, but that is not ordinarily useful, since the value is likely to contain embedded nulls.)

An empty string is returned if the field value is nil, See get_is_null to distinguish null values from empty-string values.

The pointer returned by get_value points to storage that is part of the Result structure. One should not modify the data it points to, and one must explicitly copy the data into other storage if it is to be used past the lifetime of the Result itself.

Returns the host of the connection.

Returns the server IP address of the active connection. This can be the address that a host name resolved to, or an IP address provided through the hostaddr parameter.

Returns the conn's instance_data associated with procedure func, or nil if there is none.

Returns true if a command is busy, that is, get_result would block waiting for input. If false is returned get_result can be safely called without blocking.

This will not itself attempt to read data from the server; therefore consume_input must be invoked first, or the busy state will never end.

Returns the version of libpq that is being used.

The result is formed by multiplying the library's major version number by 10_000 and adding the minor version number. For example, version 10.1 will be returned as 100001, and version 11.0 will be returned as 110000.

Prior to version 10. PostgreSQL used three-part version numbers in which the first two parts together represented the major version. For those versions, this function uses two digits for each part; for example version 9.1.5 will be returned as 90105, and version 9.2.0 will be returned as 90200.

Therefore, for purposes of determining feature compatibility, applications should divide the result by 100, not 10_000, to determine a logical major version number. In all release series, only the last two digits differ between minor releases (bug-fix releases).

Constructs an empty Result object with the given status.

This is libpq's internal function to allocate and initialize an empty Result object. This function returns NULL if memory could not be allocated. It is exported because some applications find it useful to generate result objects (particularly objects with error status) themselves. If conn is not null and status indicates an error, the current error message of the specified connection is copied into the Result. Also, if conn is not null, any event procedures registered in the connection are copied into the Result. (They do not get PGEVT_RESULTCREATE calls, but see fire_result_create_events.) Note that clear should eventually be called on the object, just as with a Result returned by libpq itself.

Returns the number of columns (fields) in each row of the query result.

Returns the number of parameters of a prepared statement.

Returns the number of rows (tuples) in the query result. Because it returns an integer result, large result sets might overflow the return value.

Returns the next notification from a list of unhandled notification messages received from the server.

Returns the OID of the inserted row, if the SQL command was an INSERT that inserted exactly one row into a table that has OIDs, or a EXECUTE of a prepared query containing a suitable INSERT statement. Otherwise, this function returns INVALID_OID. This function will also return INVALID_OID if the table affected by the INSERT statement does not contain OIDs.

Returns the command-line options passed in the connection request.

Returns the data type of the indicated statement parameter. Parameter numbers start at 0.

Looks up a current parameter setting of the server.

More Info

Returns the password of the connection.

Reports the status of the server. It accepts a connection parameter identical to those of connectdb described above. It is not, however, necessary to supply correct user name, password, or database name value to obtain the server status.

Reports the status of the server. It accepts connection parameters identical to those of connectdbParams, described above. It is not, however, necessary to supply correct user name, password, or database name values to obtain the server status.

Returns the current pipeline mode status of the connection.

Makes a sync point in the pipeline by sending a sync message and flushing. This serves as a delimiter of an implicit transaction and an error recovery point.

Returns the port of the connection.

Submits a request to create a prepared statement with the given parameters, and waits for completion.

Creates a prepared statement for later execution with exec_prepared. This feature allows commands that will be used repeatedly to be parsed and planned just once, rather than each time they are executed. This is supported only in protocol 3.0 and later; it will fail when using protocol 2.0.

The function creates a prepared statement named stmt_name from the query string, which must contain a single SQL command. stmt_name can be "" to create an unnamed statement, in which case any pre-existing unnamed statement is automatically replaced; otherwise it is an error if the statement name is already defined in the current session. If any parameters are used, they are referred to in the query as $1, $2, etc. n_params is the number of parameters for which types are pre-specified in param_types. (The pointer can be nil when n_params is 0.) param_types specifies, by OID` the data types to be assigned to the parameter symbols. If param_types is nil, or any particular element in the array is 0, the server assigns a data type to the parameter symbol in the same way it would do for an untyped literal string. Also, the query can use parameter symbols with numbers higher than n_params; data types will be inferred for these symbols as well. (See describe_prepared for a means to find out what data types were inferred.)

As with exec, the result is nil when the request was not able to be sent at all. Use error_message for more info on errors.

Prepared statements for use with exec_prepared can also be created by executing SQL PREPARE statements. Also, although there is no libpq function for deleting a prepared statement, the SQL DEALLOCATE statement can be used for that purpose.

Prints out all the rows and, optionally, the column names to the specified output stream.

NOTE: All data is assumed to be in text format.

Interrogates the frontend/backend protocol being used.

More Info

Sends data to the server during COPY_IN state.

Sends end-of-data indication to the server during COPY_IN state.

Ends the COPY_IN operation if errormsg is nil. If it is not nil then the COPY is forced to fail with the given errormsg as the reason.

Returns .Queued if the termination message was sent; or in nonblocking mode, this may only indicate that the termination message was successfully queued. (in nonblocking mode, to be certain that the data has been sent, you should next wait for write-ready and call flush, repeating until it returns false.

Registers an event callback procedure with libpq.

An event procedure must be registered once on each Conn you want to receive events about. There is no limit, other than memory, on the number of event procedures that can be registered with a connection.

The func argument will be called when a libpq event is fired. Its memory address is also used to lookup instance_data. The name argument is used to refer to the event procedure in error messages. This value cannot be nil or a zero-length string. The name string is copied into the Conn, so what is passed need not be long-lived. The pass_through pointer is passed to the func whenever an event occurs.

Converts the enumerated type returned by result_status into a string constant describing the status code. The caller should not free the result.

Resets the communication channel to the server.

This function will close the connection to the server and attempt to reestablish a new connection to the same server, using all the same parameters previously used. This might be useful for error recovery if a working connection is lost.

If resetStart returned true, poll the status using this function.

Resets the communication channel to the server, in a nonblocking manner.

More info

Allocate subsidiary storage for a Result object.

Any memory allocated with this function will be freed when res is cleared.

Returns an individual field of an error report.

field_code is an error field identifier. nil is returned if the Result is not an errro or warning result, or does not include the specified field. Field values will normally not include a trailing newline. The caller should not free the result. It will be freed when the associated Result handle is passed to clear.

Returns the error message associated with the command, or an empty string if there was no error.

If there was an error, the returned string will include a trailing newline. The caller should NOT free the result directly. It will be freed when the associated Result handle is passed to clear.

Immediately following exec or get_result, error_message (on the connection) will return the same string as this function. However, a Result will retain its error message until destroyed, whereas the connection's error message will change when subsequent operations are done. Use this function when you want to know the status associated with a particular Result; use error_message when you want to know the status from the latest operation on the connection.

Returns the result's instance_data associated with func, or nil if there is none.

Retrieves the number of bytes allocated for a Result object.

This value is the sum of all malloc requests associated with the Result object, that is all the space that will be freed by clear. This information can be useful for managing memory consumption.

Sets the result's instance_data for func to data. Fails if func is not registered on the Conn. Beware that any storage represented by data will not be accounted for by result_memory_size, unless it is allocated using result_alloc. (Doing so is recommendable because it eliminates the need to free such storage explicitly when the result is destroyed.)

Returns the result status of the command.

If the result status is Tuples_OK, then the functions described below can be used to retrieve the rows returned by the query. Note that a SELECT command that happens to retrieve zero rows still shows Tuples_OK, Command_OK is for commands that can never return rows (INSERT, UPDATE, etc.). A response of Empty_Query might indicate a bug in the client software.

A result of Non_Fatal_Error will never be returned directly by exec or other query execution functions; results of this kind are instead passed to the notice processor.

Returns a reformatted error message associated with a Result object.

NOTE: The caller must free the returned string.

More info

Submits a request to obtain information about the specified portal, without waiting for completion.

This is an asynchronous version of describe_portal.

After a successful call, call get_result one or more times to determine whether the server successfully created the prepared statement.

Submits a request to obtain information about the specified prepared statement, without waiting for completion.

This is an asynchronous version of describe_prepared.

After a successful call, call get_result one or more times to determine whether the server successfully created the prepared statement.

Sends a request for the server to flush the output buffer.

The server flushes its output buffer automatically as a result of pipeline_sync being called, or on any request when not in pipeline mode; this function is useful to cause the server to flush its output buffer in pipeline mode without establishing a synchronization point. Note that the request is not itself flushed to the server automatically; use flush if necessary.

Sends a request to create a prepared statement with the given parameters, without waiting for completion.

This is an asynchronous version of prepare and parameters are handled identically.

After a successful call, call get_result one or more times to determine whether the server successfully created the prepared statement.

Submits a command to the server without waiting for the results. If false is returned (error), use error_message for more information about the failure.

After a successful call, call get_result one or more times to obtain results. send_query can not be called again on this connection until get_result has returned nil (indicating done).

Submits a command and separate parameters to the server without waiting for the results.

This is equivalent to send_query except that query parameters can be specified separately from the query string. This function's parameters are handled identically to exec_params.

Submits a request to execute a prepared statement with the given parameters, without waiting for the results.

This is similar to send_query_params, but the command to be executed is specified by naming a previously-prepared statement, instead of giving a query string. The function's parameters are handled identically to exec_prepared.

Returns an integer representing the backend version.

More Info

Sets the client encoding.

Determines the handling of CONTEXT fields in messages returned by error_message and result_error_message.

Returns the connection's previous settings.

Setting this only changes next Result objects, not current ones. But you can use result_verbose_error_message if you want to print a previous error with different visibility.

Determines the verbosity of messages returned by error_message and result_error_message.

Returns the connection's previous settings.

Setting the verbosity only changes next Result objects, not current ones. But you can use result_verbose_error_message if you want to print a previous error with different verbosity.

Sets the connection Conn's instance_data for procedure func to data. Fails if func is not registered on the Conn.

Sets the nonblocking status of the connection.

Returns 0 if OK, -1 if error.

NOTE: exec does not honor nonblocking mode.

Sets or examines the current notice processor for a connection.

Returns the previous notice processor. If you supply a nil pointer processor, the current processor is returned but not overwritten (basically a getter).

Sets or examines the current notice receiver for a connection.

Returns the previous notice receiver. If you supply a nil pointer receiver, the current receiver is returned but not overwritten (basically a getter).

Sets the attributes of a Result object.

Select single-row mode for the currently executing query.

This function can only be called immediately after send_query or one of its sibling functions, before any other operation on the connection such as consume_input or get_result. If called at the correct time, the function activates single-row mode for the current query and returns 1. Otherwise the mode stays unchanged and the function returns 0. In any case, the mode reverts to normal after completion of the current query.

More info

Controls the tracing behavior of the client/server communication.

NOTE: this function must be called after trace.

Sets a tuple field value of a Result object.

Makes a new connection to the database server.

This is the predecessor of connectdb with a fixed set of parameters. It has the same functionality except that the missing parameters will always take on default values. write nil or an empty string for any one of the fixed parameters that is to be defaulted.

If the dbName contains an = sign, it is taken as a conninfo string in exactly the same way as if it had been passed to connectdb, and the remaining parameters are then applied as above.

Obtains the file descriptor number of the connection socket to the server. A valid descriptor will be greater than or equal to 0; a result of -1 indicates that no server connection is currently open. (This will not change during normal operation, but could change during connection setup or reset.)

Returns SSL-related information about the connection.

The list of available attributes

Returns an array of SSL attribute names that can be used in ssl_attribute.

Returns true if the connection uses SSL.

More info

Returns a pointer to an SSL-implementation-specific object describing the connection.

The available names depend on the SSL implementation, for OpenSSL there is one struct available under "OpenSSL".

Returns the status of the connection.

More Info

Enables tracing of the client/server communication to a debugging file stream.

Each line consists of: an optional timestamp, a direction (F for client to server, B for server to client), message length, message type, and message contents.

Non-message content fields are separated by a tab. Message contents are separated by a space. Protocol strings are enclosed in double quotes, while strings used as data values are enclosed in single quotes. Non-printable chars are printed as hexadecimal escapes. Further message-type-specific detail can be found in Section 55.7.

Returns the current in-transaction status of the server.

WARN: PQtransactionStatus will give incorrect results when using a PostgreSQL 7.3 server that has the parameter autocommit set to off. The server-side autocommit feature has been deprecated and does not exist in later server versions.

Converts a string/escaped version of bytea data into binary data -- the reverse of escape_bytea_conn. This is needed when retrieving bytea data in text format, but not when retrieving it in binary format.

This function allocates and the result should be freed with free_mem.

This conversion is not exactly the inverse of escape_bytea_conn, because the string is not expected to be "escaped" when received from get_value. In particular this means there is no need for string quoting considerations, and so no need for Conn parameter.

Disables the tracing started by trace.

Returns the user name of the connection.