pg_escape_bytea

pg_escape_bytea — Escape a binary string for use in an SQL string constant with bytea (byte array) columns

Synopsis

pg_escape_bytea binary_string

Description

pg_escape_bytea returns its argument with added characters which makes it safe for use in single-quoted SQL string constants. Unlike pg_escape_string, which works on text strings, pg_escape_bytea is meant for arbitrary binary data meant to be stored or used with PostgreSQL bytea (byte array) columns. This command allows arbitrary binary data to be safely sent through the PostgreSQL query mechanism in a text mode query. (An alternative to escaping and unescaping binary data is to use binary mode prepared queries. See pg_exec_prepared.)

Arguments

binary_string

The binary string data to escape. This is just a regular Tcl string, except that it can contain arbitrary byte values.

Return Value

The escaped data string. When placed in single quotes, it can safely be used in SQL statements.

Notes

This command uses or emulates the PostgreSQL libpq function PQescapeBytea.

See also pg_unescape_bytea, but note that these commands are not inverses of each other. pg_escape_bytea creates output that is meant to go through two levels of parsing by the database: one when parsing SQL, and one when processing the bytea data type. For example, a single backslash in the input string is translated to four backslashes. pg_unescape_bytea undoes one level of escaping.

The pgin.tcl implementation of this command is slow. Consider using binary prepared queries instead, to avoid having to escape and unescape your binary data.

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

See Section 5.9, “Example - Bytea Escaping - Picture Viewer, Part 1 - Store Pictures” for an example.