begriffs open source - ai-pg/blob - full-docs/src/sgml/html/datatype-binary.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>8.4. Binary Data Types</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="datatype-character.html" title="8.3. Character Types" /><link rel="next" href="datatype-datetime.html" title="8.5. Date/Time Types" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">8.4. Binary Data Types</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="datatype-character.html" title="8.3. Character Types">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><th width="60%" align="center">Chapter 8. Data Types</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="datatype-datetime.html" title="8.5. Date/Time Types">Next</a></td></tr></table><hr /></div><div class="sect1" id="DATATYPE-BINARY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">8.4. Binary Data Types <a href="#DATATYPE-BINARY" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="datatype-binary.html#DATATYPE-BINARY-BYTEA-HEX-FORMAT">8.4.1. <code class="type">bytea</code> Hex Format</a></span></dt><dt><span class="sect2"><a href="datatype-binary.html#DATATYPE-BINARY-BYTEA-ESCAPE-FORMAT">8.4.2. <code class="type">bytea</code> Escape Format</a></span></dt></dl></div><a id="id-1.5.7.12.2" class="indexterm"></a><a id="id-1.5.7.12.3" class="indexterm"></a><p>
   3     The <code class="type">bytea</code> data type allows storage of binary strings;
   4     see <a class="xref" href="datatype-binary.html#DATATYPE-BINARY-TABLE" title="Table 8.6. Binary Data Types">Table 8.6</a>.
   5    </p><div class="table" id="DATATYPE-BINARY-TABLE"><p class="title"><strong>Table 8.6. Binary Data Types</strong></p><div class="table-contents"><table class="table" summary="Binary Data Types" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /></colgroup><thead><tr><th>Name</th><th>Storage Size</th><th>Description</th></tr></thead><tbody><tr><td><code class="type">bytea</code></td><td>1 or 4 bytes plus the actual binary string</td><td>variable-length binary string</td></tr></tbody></table></div></div><br class="table-break" /><p>
   6     A binary string is a sequence of octets (or bytes).  Binary
   7     strings are distinguished from character strings in two
   8     ways.  First, binary strings specifically allow storing
   9     octets of value zero and other <span class="quote">“<span class="quote">non-printable</span>”</span>
  10     octets (usually, octets outside the decimal range 32 to 126).
  11     Character strings disallow zero octets, and also disallow any
  12     other octet values and sequences of octet values that are invalid
  13     according to the database's selected character set encoding.
  14     Second, operations on binary strings process the actual bytes,
  15     whereas the processing of character strings depends on locale settings.
  16     In short, binary strings are appropriate for storing data that the
  17     programmer thinks of as <span class="quote">“<span class="quote">raw bytes</span>”</span>, whereas character
  18     strings are appropriate for storing text.
  19    </p><p>
  20     The <code class="type">bytea</code> type supports two
  21     formats for input and output: <span class="quote">“<span class="quote">hex</span>”</span> format
  22     and <span class="productname">PostgreSQL</span>'s historical
  23     <span class="quote">“<span class="quote">escape</span>”</span> format.  Both
  24     of these are always accepted on input.  The output format depends
  25     on the configuration parameter <a class="xref" href="runtime-config-client.html#GUC-BYTEA-OUTPUT">bytea_output</a>;
  26     the default is hex.  (Note that the hex format was introduced in
  27     <span class="productname">PostgreSQL</span> 9.0; earlier versions and some
  28     tools don't understand it.)
  29    </p><p>
  30     The <acronym class="acronym">SQL</acronym> standard defines a different binary
  31     string type, called <code class="type">BLOB</code> or <code class="type">BINARY LARGE
  32     OBJECT</code>.  The input format is different from
  33     <code class="type">bytea</code>, but the provided functions and operators are
  34     mostly the same.
  35    </p><div class="sect2" id="DATATYPE-BINARY-BYTEA-HEX-FORMAT"><div class="titlepage"><div><div><h3 class="title">8.4.1. <code class="type">bytea</code> Hex Format <a href="#DATATYPE-BINARY-BYTEA-HEX-FORMAT" class="id_link">#</a></h3></div></div></div><p>
  36     The <span class="quote">“<span class="quote">hex</span>”</span> format encodes binary data as 2 hexadecimal digits
  37     per byte, most significant nibble first.  The entire string is
  38     preceded by the sequence <code class="literal">\x</code> (to distinguish it
  39     from the escape format).  In some contexts, the initial backslash may
  40     need to be escaped by doubling it
  41     (see <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-STRINGS" title="4.1.2.1. String Constants">Section 4.1.2.1</a>).
  42     For input, the hexadecimal digits can
  43     be either upper or lower case, and whitespace is permitted between
  44     digit pairs (but not within a digit pair nor in the starting
  45     <code class="literal">\x</code> sequence).
  46     The hex format is compatible with a wide
  47     range of external applications and protocols, and it tends to be
  48     faster to convert than the escape format, so its use is preferred.
  49    </p><p>
  50     Example:
  51 </p><pre class="programlisting">
  52 SET bytea_output = 'hex';
  53
  54 SELECT '\xDEADBEEF'::bytea;
  55    bytea
  56 ------------
  57  \xdeadbeef
  58 </pre><p>
  59    </p></div><div class="sect2" id="DATATYPE-BINARY-BYTEA-ESCAPE-FORMAT"><div class="titlepage"><div><div><h3 class="title">8.4.2. <code class="type">bytea</code> Escape Format <a href="#DATATYPE-BINARY-BYTEA-ESCAPE-FORMAT" class="id_link">#</a></h3></div></div></div><p>
  60     The <span class="quote">“<span class="quote">escape</span>”</span> format is the traditional
  61     <span class="productname">PostgreSQL</span> format for the <code class="type">bytea</code>
  62     type.  It
  63     takes the approach of representing a binary string as a sequence
  64     of ASCII characters, while converting those bytes that cannot be
  65     represented as an ASCII character into special escape sequences.
  66     If, from the point of view of the application, representing bytes
  67     as characters makes sense, then this representation can be
  68     convenient.  But in practice it is usually confusing because it
  69     fuzzes up the distinction between binary strings and character
  70     strings, and also the particular escape mechanism that was chosen is
  71     somewhat unwieldy.  Therefore, this format should probably be avoided
  72     for most new applications.
  73    </p><p>
  74     When entering <code class="type">bytea</code> values in escape format,
  75     octets of certain
  76     values <span class="emphasis"><em>must</em></span> be escaped, while all octet
  77     values <span class="emphasis"><em>can</em></span> be escaped.  In
  78     general, to escape an octet, convert it into its three-digit
  79     octal value and precede it by a backslash.
  80     Backslash itself (octet decimal value 92) can alternatively be represented by
  81     double backslashes.
  82     <a class="xref" href="datatype-binary.html#DATATYPE-BINARY-SQLESC" title="Table 8.7. bytea Literal Escaped Octets">Table 8.7</a>
  83     shows the characters that must be escaped, and gives the alternative
  84     escape sequences where applicable.
  85    </p><div class="table" id="DATATYPE-BINARY-SQLESC"><p class="title"><strong>Table 8.7. <code class="type">bytea</code> Literal Escaped Octets</strong></p><div class="table-contents"><table class="table" summary="bytea Literal Escaped Octets" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /><col class="col4" /><col class="col5" /></colgroup><thead><tr><th>Decimal Octet Value</th><th>Description</th><th>Escaped Input Representation</th><th>Example</th><th>Hex Representation</th></tr></thead><tbody><tr><td>0</td><td>zero octet</td><td><code class="literal">'\000'</code></td><td><code class="literal">'\000'::bytea</code></td><td><code class="literal">\x00</code></td></tr><tr><td>39</td><td>single quote</td><td><code class="literal">''''</code> or <code class="literal">'\047'</code></td><td><code class="literal">''''::bytea</code></td><td><code class="literal">\x27</code></td></tr><tr><td>92</td><td>backslash</td><td><code class="literal">'\\'</code> or <code class="literal">'\134'</code></td><td><code class="literal">'\\'::bytea</code></td><td><code class="literal">\x5c</code></td></tr><tr><td>0 to 31 and 127 to 255</td><td><span class="quote">“<span class="quote">non-printable</span>”</span> octets</td><td><code class="literal">'\<em class="replaceable"><code>xxx'</code></em></code> (octal value)</td><td><code class="literal">'\001'::bytea</code></td><td><code class="literal">\x01</code></td></tr></tbody></table></div></div><br class="table-break" /><p>
  86     The requirement to escape <span class="emphasis"><em>non-printable</em></span> octets
  87     varies depending on locale settings. In some instances you can get away
  88     with leaving them unescaped.
  89    </p><p>
  90     The reason that single quotes must be doubled, as shown
  91     in <a class="xref" href="datatype-binary.html#DATATYPE-BINARY-SQLESC" title="Table 8.7. bytea Literal Escaped Octets">Table 8.7</a>, is that this
  92     is true for any string literal in an SQL command.  The generic
  93     string-literal parser consumes the outermost single quotes
  94     and reduces any pair of single quotes to one data character.
  95     What the <code class="type">bytea</code> input function sees is just one
  96     single quote, which it treats as a plain data character.
  97     However, the <code class="type">bytea</code> input function treats
  98     backslashes as special, and the other behaviors shown in
  99     <a class="xref" href="datatype-binary.html#DATATYPE-BINARY-SQLESC" title="Table 8.7. bytea Literal Escaped Octets">Table 8.7</a> are implemented by
 100     that function.
 101    </p><p>
 102     In some contexts, backslashes must be doubled compared to what is
 103     shown above, because the generic string-literal parser will also
 104     reduce pairs of backslashes to one data character;
 105     see <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-STRINGS" title="4.1.2.1. String Constants">Section 4.1.2.1</a>.
 106    </p><p>
 107     <code class="type">Bytea</code> octets are output in <code class="literal">hex</code>
 108     format by default.  If you change <a class="xref" href="runtime-config-client.html#GUC-BYTEA-OUTPUT">bytea_output</a>
 109     to <code class="literal">escape</code>,
 110     <span class="quote">“<span class="quote">non-printable</span>”</span> octets are converted to their
 111     equivalent three-digit octal value and preceded by one backslash.
 112     Most <span class="quote">“<span class="quote">printable</span>”</span> octets are output by their standard
 113     representation in the client character set, e.g.:
 114
 115 </p><pre class="programlisting">
 116 SET bytea_output = 'escape';
 117
 118 SELECT 'abc \153\154\155 \052\251\124'::bytea;
 119      bytea
 120 ----------------
 121  abc klm *\251T
 122 </pre><p>
 123
 124     The octet with decimal value 92 (backslash) is doubled in the output.
 125     Details are in <a class="xref" href="datatype-binary.html#DATATYPE-BINARY-RESESC" title="Table 8.8. bytea Output Escaped Octets">Table 8.8</a>.
 126    </p><div class="table" id="DATATYPE-BINARY-RESESC"><p class="title"><strong>Table 8.8. <code class="type">bytea</code> Output Escaped Octets</strong></p><div class="table-contents"><table class="table" summary="bytea Output Escaped Octets" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /><col class="col4" /><col class="col5" /></colgroup><thead><tr><th>Decimal Octet Value</th><th>Description</th><th>Escaped Output Representation</th><th>Example</th><th>Output Result</th></tr></thead><tbody><tr><td>92</td><td>backslash</td><td><code class="literal">\\</code></td><td><code class="literal">'\134'::bytea</code></td><td><code class="literal">\\</code></td></tr><tr><td>0 to 31 and 127 to 255</td><td><span class="quote">“<span class="quote">non-printable</span>”</span> octets</td><td><code class="literal">\<em class="replaceable"><code>xxx</code></em></code> (octal value)</td><td><code class="literal">'\001'::bytea</code></td><td><code class="literal">\001</code></td></tr><tr><td>32 to 126</td><td><span class="quote">“<span class="quote">printable</span>”</span> octets</td><td>client character set representation</td><td><code class="literal">'\176'::bytea</code></td><td><code class="literal">~</code></td></tr></tbody></table></div></div><br class="table-break" /><p>
 127     Depending on the front end to <span class="productname">PostgreSQL</span> you use,
 128     you might have additional work to do in terms of escaping and
 129     unescaping <code class="type">bytea</code> strings. For example, you might also
 130     have to escape line feeds and carriage returns if your interface
 131     automatically translates these.
 132    </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="datatype-character.html" title="8.3. Character Types">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="datatype-datetime.html" title="8.5. Date/Time Types">Next</a></td></tr><tr><td width="40%" align="left" valign="top">8.3. Character Types </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 8.5. Date/Time Types</td></tr></table></div></body></html>