pg_unescape_bytea

pg_unescape_bytea — Unescape a string returned by an SQL query on a bytea (byte array) column, recovering the original binary string.

Synopsis

pg_unescape_bytea string

Description

pg_unescape_bytea recovers a binary string from the escaped data returned by PostgreSQL when a bytea (byte array) column is queries. This command returns the original data from a bytea column which was inserted (for example) after being escaped with pg_escape_bytea. (An alternative to escaping and unescaping binary data is to use binary mode prepared queries. See pg_exec_prepared.)

Arguments

string

The string to unescape. This should be the result of a query on a bytea column. Other uses are undefined (see notes).

Return Value

The unescaped binary data string. This is a regular Tcl string, which can contain arbitrary byte values.

Notes

This command uses or emulates the PostgreSQL libpq function PQunescapeBytea.

See also pg_escape_bytea. Note that pg_escape_bytea and pg_unescape_bytea are not inverses of each other. For example, pg_escape_bytea turns the byte value 1 into the 5 character sequence \\001. pg_unescape_bytea turns the 4 character sequence \001 into the byte value 1. This asymmetry is due to the fact that SQL statements undergo an extra level of parsing with bytea columns.

Caution

The pgin.tcl implementation of this command is not an accurate emulation of the libpq function. This was done for performance reasons. Correct results will always be returned for data that results from a query on a bytea column (that is, any data output by the byteaout backend function). Results are undefined for other uses. For example, give the two byte sequence \a (which will never be output by PostgreSQL for a bytea column), PQunescapeBytea will return the single character 'a', but pg_unescape_bytea will return the byte value 7 (because Tcl unescapes \a to ASCII bell).

This command was added in pgtclng-1.5.2 and in pgintcl-2.2.0.

See Section 5.10, “Example - Bytea Escaping - Picture Viewer, Part 2 - View Pictures” for an example.