The BYTEA data type allows storage of binary strings; see Table 7-4.
Table 7-4. Binary Large Object
| Name | Storage Size | Description |
|---|---|---|
| BYTEA | 4 bytes plus the actual binary string | variable-length binary string |
A binary string is a sequence of octets (or bytes). Binary strings are distinguished from characters strings by two characteristics: First, binary strings specifically allow storing octets of value zero and other "non-printable" octets (defined as octets outside the range 32 to 126). Second, operations on binary strings process the actual bytes, whereas the encoding and processing of character strings depends on locale settings.
When entering BYTEA values, octets of certain values must be escaped (but all octet values may be escaped) when used as part of a string literal in an SQL statement. In general, to escape an octet, it is converted into the three-digit octal number equivalent of its decimal octet value, and preceded by two backslashes. Table 7-5 contains the characters which must be escaped, and gives the alternate escape sequences where applicable.
Table 7-5. BYTEA Literal Escaped Octets
| Decimal Octet Value | Description | Escaped Input Representation | Example | Output Representation |
|---|---|---|---|---|
| 0 | zero octet | '\\000' | SELECT '\\000'::BYTEA; | \000 |
| 39 | single quote | '\'' or '\\047' | SELECT '\''::BYTEA; | ' |
| 92 | backslash | '\\\\' or '\\134' | SELECT '\\\\'::BYTEA; | \\ |
| 0 to 31 and 127 to 255 | "non-printable" octets | '\\xxx' (octal value) | SELECT '\\001'::BYTEA; | \001 |
The requirement to escape "non-printable" octets actually varies depending on locale settings. In some instances you can get away with leaving them unescaped. Note that the result in each of the examples in Table 7-5 was exactly one octet in length, even though the output representation of the zero octet and backslash are more than one character.
The reason that you have to write so many backslashes, as shown in Table 7-5, is that an input string written as a string literal must pass through two parse phases in the EnterpriseDB server. The first backslash of each pair is interpreted as an escape character by the string-literal parser and is therefore consumed, leaving the second backslash of the pair. The remaining backslash is then recognized by the BYTEA input function as starting either a three digit octal value or escaping another backslash. For example, a string literal passed to the server as '\\001' becomes \001 after passing through the string-literal parser. The \001 is then sent to the BYTEA input function, where it is converted to a single octet with a decimal value of 1. Note that the apostrophe character is not treated specially by BYTEA, so it follows the normal rules for string literals. (See also Section 3.1.2.1.)
BYTEA octets are also escaped in the output. In general, each "non-printable" octet is converted into its equivalent three-digit octal value and preceded by one backslash. Most "printable" octets are represented by their standard representation in the client character set. The octet with decimal value 92 (backslash) has a special alternative output representation. Details are in Table 7-6.
Table 7-6. BYTEA Output Escaped Octets
| Decimal Octet Value | Description | Escaped Output Representation | Example | Output Result |
|---|---|---|---|---|
| 92 | backslash | \\ | SELECT '\\134'::BYTEA; | \\ |
| 0 to 31 and 127 to 255 | "non-printable" octets | \xxx (octal value) | SELECT '\\001'::BYTEA; | \001 |
| 32 to 126 | "printable" octets | client character set representation | SELECT '\\176'::BYTEA; | ~ |
Depending on the front end to EnterpriseDB you use, you may have additional work to do in terms of escaping and unescaping BYTEA strings. For example, you may also have to escape line feeds and carriage returns if your interface automatically translates these.
The following can be used as synonyms for BYTEA: BINARY, BLOB, BYTE, IMAGE, LONG RAW, RAW (n), and VARBINARY.