- linkend="sql-syntax-strings">.
+ object file, an SQL command, or text in a procedural language.
functions.
- the function definition must be escaped by doubling them.
strings, bit strings, and numbers.
Constants can also be specified with explicit types, which can
enable more accurate representation and more efficient handling by
- the system. The implicit constants are described below; explicit
- constants are discussed afterwards.
+ the system. These alternatives are discussed in the following
+ subsections.
escaping
-
-
-
PostgreSQL provides two ways to
- specify a string constant. The first way is to enclose the
- sequence of characters that constitute the string in single
- quotes ('), e.g. 'This is a
- string'. This method of specifying a string constant
- is defined by the SQL standard. The standard-compliant way of
- embedding single-quotes these kinds of string constants is by
- typing two adjacent single quotes, e.g. 'Dianne''s
- house'. In addition,
-
PostgreSQL allows single quotes
- to be escaped with a backslash (\),
- e.g. 'Dianne\'s horse'.
-
-
- While this syntax for specifying string constants is usually
- convenient, it can be difficult to comprehend the content of the
- string if it consists of many single quotes, each of which must
- be doubled. To allows more readable queries in these situations,
-
PostgreSQL allows another way to
- specify string constants known as dollar
- quoting. A string constant specified via dollar quoting
- consists of a dollar sign ($), an optional
- tag
of zero or more characters, another dollar
- sign, an arbitrary sequence of characters that makes up the
- string content, a dollar sign, the same tag that began this
- dollar quote, and a dollar sign. For example, here are two
- different ways to specify the previous example using dollar
- quoting:
-$$Dianne's horse$$
-$SomeTag$Dianne's horse$SomeTag$
-
- Note that inside the dollar-quoted string, single quotes can be
- used without needing to be escaped.
-
-
- Dollar quotes are case sensitive, so $tag$String
- content$tag$ is valid, but $TAG$String
- content$tag$ is not. Also, dollar quotes can
- nest. For example:
-CREATE OR REPLACE FUNCTION has_bad_chars(text) RETURNS boolean AS
-$function$
-BEGIN
- RETURN ($1 ~ $q$[\t\r\n\v|\\]$q$);
-END;
-$function$ LANGUAGE plpgsql;
-
- Note that nesting requires a different tag for each nested
- dollar quote, as shown above. Furthermore, nested dollar quotes
- can only be used when the content of the string that is being
- quoted will be re-parsed by
PostgreSQL.-
-
- Dollar quoting is not defined by the SQL standard, but it is
- often a more convenient way to write long string literals (such
- as procedural function definitions) than the standard-compliant
- single quote syntax. Which quoting technique is most appropriate
- for a particular circumstance is a decision that is left to the
- user.
-
+ A string constant in SQL is an arbitrary sequence of characters
+ bounded by single quotes ('), for example
+ 'This is a string'. The standard-compliant way of
+ writing a single-quote character within a string constant is to
+ write two adjacent single quotes, e.g.
+ 'Dianne''s horse'.
+
PostgreSQL also allows single quotes
+ to be escaped with a backslash (\), so for
+ example the same string could be written
+ 'Dianne\'s horse'.
+
- C-style backslash escapes are also available:
+ Another
PostgreSQL extension is that
+ C-style backslash escapes are available:
\b is a backspace, \f is a
form feed, \n is a newline,
\r is a carriage return, \t
that the byte sequences you create are valid characters in the
server character set encoding.) Any other character following a
backslash is taken literally. Thus, to include a backslash in a
- string constant, type two backslashes.
+ string constant, write two backslashes.
+
+
Dollar-Quoted String Constants
+
+
+
+
+ While the standard syntax for specifying string constants is usually
+ convenient, it can be difficult to understand when the desired string
+ contains many single quotes or backslashes, since each of those must
+ be doubled. To allow more readable queries in such situations,
+
PostgreSQL provides another way, called
+ dollar quoting
, to write string constants.
+ A dollar-quoted string constant
+ consists of a dollar sign ($), an optional
+ tag
of zero or more characters, another dollar
+ sign, an arbitrary sequence of characters that makes up the
+ string content, a dollar sign, the same tag that began this
+ dollar quote, and a dollar sign. For example, here are two
+ different ways to specify the string Dianne's horse
+ using dollar quoting:
+$$Dianne's horse$$
+$SomeTag$Dianne's horse$SomeTag$
+
+ Notice that inside the dollar-quoted string, single quotes can be
+ used without needing to be escaped. Indeed, no characters inside
+ a dollar-quoted string are ever escaped: the string content is always
+ written literally. Backslashes are not special, and neither are
+ dollar signs, unless they are part of a sequence matching the opening
+ tag.
+
+
+ It is possible to nest dollar-quoted string constants by choosing
+ different tags at each nesting level. This is most commonly used in
+ writing function definitions. For example:
+$function$
+BEGIN
+ RETURN ($1 ~ $q$[\t\r\n\v\\]$q$);
+END;
+$function$
+
+ Here, the sequence $q$[\t\r\n\v\\]$q$ represents a
+ dollar-quoted literal string [\t\r\n\v\\], which will
+ be recognized when the function body is executed by
+
PostgreSQL. But since the sequence does not match+ the outer dollar quoting delimiter $function$, it is
+ just some more characters within the constant so far as the outer
+ string is concerned.
+
+
+ The tag, if any, of a dollar-quoted string follows the same rules
+ as an unquoted identifier, except that it cannot contain a dollar sign.
+ Tags are case sensitive, so $tag$String content$tag$
+ is correct, but $TAG$String content$tag$ is not.
+
+
+ A dollar-quoted string that follows a keyword or identifier must
+ be separated from it by whitespace; otherwise the dollar quoting
+ delimiter would be taken as part of the preceding identifier.
+
+
+ Dollar quoting is not part of the SQL standard, but it is often a more
+ convenient way to write complicated string literals than the
+ standard-compliant single quote syntax. It is particularly useful when
+ representing string constants inside other constants, as is often needed
+ in procedural function definitions. With single-quote syntax, each
+ backslash in the above example would have to be written as four
+ backslashes, which would be reduced to two backslashes in parsing the
+ original string constant, and then to one when the inner string constant
+ is re-parsed during function execution.
+
+
+
Bit-String Constants
- Bit-string constants look like string constants with a
+ Bit-string constants look like regular string constants with a
B (upper or lower case) immediately before the
opening quote (no intervening whitespace), e.g.,
B'1001'. The only characters allowed within
Both forms of bit-string constant can be continued
across lines in the same way as regular string constants.
+ Dollar quoting cannot be used in a bit-string constant.
- In addition, there are several special constant values that are
- accepted as numeric constants. The float4 and
- float8 types allow the following special constants:
-
-Infinity
--Infinity
-NaN
-
- These represent the IEEE 754 special values
- infinity
, negative infinity
, and
- not-a-number
, respectively. The
- numeric type only allows NaN, whereas
- the integral types do not allow any of these constants. Note that
- these constants are recognized in a case-insensitive manner.
-
-
value fits in type integer (32 bits); otherwise it is
presumed to be type bigint if its
value fits in type bigint (64 bits); otherwise it is
- taken to be type numeric. Constants that contain decimal
+ taken to be type numeric. Constants that contain decimal
points and/or exponents are always initially presumed to be type
numeric.
REAL '1.23' -- string style
1.23::REAL -- PostgreSQL (historical) style
-
-
+
+ These are actually just special cases of the general casting
+ notations discussed next.
+
+
Constants of Other Types
'string'::type
CAST ( 'string' AS type )
- The string's text is passed to the input conversion
+ The string constant's text is passed to the input conversion
routine for the type called type. The
result is a constant of the indicated type. The explicit type
cast may be omitted if there is no ambiguity as to the type the
- constant must be (for example, when it is passed as an argument
- to a non-overloaded function), in which case it is automatically
- coerced.
+ constant must be (for example, when it is assigned directly to a
+ table column), in which case it is automatically coerced.
+
+
+ The string constant can be written using either regular SQL
+ notation or dollar-quoting.
projects / postgresql.git / commitdiff