String-escaping functions

Classes
class	pqxx::binarystring
	Binary data corresponding to PostgreSQL's "BYTEA" binary-string type. More...

Functions
std::string	pqxx::connection::esc (char const text[], std::size_t maxlen) const
	Escape string for use as SQL string literal on this connection. More...
std::string	pqxx::connection::esc (char const text[]) const
	Escape string for use as SQL string literal on this connection. More...
std::string	pqxx::connection::esc (std::string_view text) const
	Escape string for use as SQL string literal on this connection. More...
std::string	pqxx::connection::esc_raw (unsigned char const bin[], std::size_t len) const
	Escape binary string for use as SQL string literal on this connection. More...
std::string	pqxx::connection::esc_raw (std::basic_string_view< std::byte >) const
	Escape binary string for use as SQL string literal on this connection. More...
std::string	pqxx::connection::unesc_raw (zview text) const
	Unescape binary data, e.g. from a table field or notification payload. More...
std::string	pqxx::connection::unesc_raw (char const text[]) const
	Unescape binary data, e.g. from a table field or notification payload. More...
std::basic_string< std::byte >	pqxx::connection::unesc_bin (std::string_view text) const
	Unescape binary data, e.g. from a table field or notification payload. More...
std::string	pqxx::connection::quote_raw (unsigned char const bin[], std::size_t len) const
	Escape and quote a string of binary data. More...
std::string	pqxx::connection::quote_raw (std::basic_string_view< std::byte >) const
	Escape and quote a string of binary data. More...
std::string	pqxx::connection::quote_name (std::string_view identifier) const
	Escape and quote an SQL identifier for use in a query. More...
std::string	pqxx::connection::quote_table (std::string_view name) const
	Escape and quote a table name. More...
std::string	pqxx::connection::quote_table (table_path) const
	Escape and quote a table path. More...
template<PQXX_CHAR_STRINGS_ARG STRINGS>
std::string	pqxx::connection::quote_columns (STRINGS const &columns) const
	Quote and comma-separate a series of column names. More...
template<typename T >
std::string	pqxx::connection::quote (T const &t) const
	Represent object as SQL string, including quoting & escaping. More...
std::string	pqxx::connection::quote (binarystring const &) const
std::string	pqxx::connection::quote (std::basic_string_view< std::byte > bytes) const
	Escape and quote binary data for use as a BYTEA value in SQL statement. More...
std::string	pqxx::connection::esc_like (std::string_view text, char escape_char='\\') const
	Escape string for literal LIKE match. More...
template<typename... ARGS>
auto	pqxx::transaction_base::esc (ARGS &&...args) const
	Escape string for use as SQL string literal in this transaction. More...
template<typename... ARGS>
auto	pqxx::transaction_base::esc_raw (ARGS &&...args) const
	Escape binary data for use as SQL string literal in this transaction. More...
std::string	pqxx::transaction_base::unesc_raw (zview text) const
	Unescape binary data, e.g. from a table field or notification payload. More...
std::basic_string< std::byte >	pqxx::transaction_base::unesc_bin (zview text)
	Unescape binary data, e.g. from a table field or notification payload. More...
std::string	pqxx::transaction_base::unesc_raw (char const *text) const
	Unescape binary data, e.g. from a table field or notification payload. More...
std::basic_string< std::byte >	pqxx::transaction_base::unesc_bin (char const text[])
	Unescape binary data, e.g. from a table field or notification payload. More...
template<typename T >
std::string	pqxx::transaction_base::quote (T const &t) const
	Represent object as SQL string, including quoting & escaping. More...
std::string	pqxx::transaction_base::quote (binarystring const &t) const
std::string	pqxx::transaction_base::quote_raw (unsigned char const bin[], std::size_t len) const
	Binary-escape and quote a binary string for use as an SQL constant. More...
std::string	pqxx::transaction_base::quote_raw (zview bin) const
	Binary-escape and quote a binary string for use as an SQL constant. More...
std::string	pqxx::transaction_base::quote_name (std::string_view identifier) const
	Escape an SQL identifier for use in a query. More...
std::string	pqxx::transaction_base::esc_like (std::string_view bin, char escape_char='\\') const
	Escape string for literal LIKE match. More...

Detailed Description

Function Documentation

esc() [1/4]

template<typename... ARGS>

auto pqxx::transaction_base::esc

(

ARGS &&...

args

)

const

Escape string for use as SQL string literal in this transaction.

Use these when writing SQL queries that incorporate C++ values as SQL constants.

The functions you see here are just convenience shortcuts to the same functions on the connection object.

esc() [2/4]

std::string pqxx::connection::esc	(	char const	text[],
		std::size_t	maxlen
	)		const

Escape string for use as SQL string literal on this connection.

Warning

This accepts a length, and it does not require a terminating zero byte. But if there is a zero byte, escaping stops there even if it's not at the end of the string!

esc() [3/4]

std::string pqxx::connection::esc

(

char const

text[]

)

const

Escape string for use as SQL string literal on this connection.

References pqxx::binary_cast(), pqxx::internal::esc_bin(), pqxx::internal::size_esc_bin(), and pqxx::text.

esc() [4/4]

std::string pqxx::connection::esc

(

std::string_view

text

)

const

Escape string for use as SQL string literal on this connection.

Warning

This is meant for text strings only. It cannot contain bytes whose value is zero ("nul bytes").

esc_like() [1/2]

std::string pqxx::transaction_base::esc_like	(	std::string_view	bin,
		char	escape_char = '\\'
	)		const

Escape string for literal LIKE match.

esc_like() [2/2]

std::string pqxx::connection::esc_like	(	std::string_view	text,
		char	escape_char = '\\'
	)		const

Escape string for literal LIKE match.

Use this when part of an SQL "LIKE" pattern should match only as a literal string, not as a pattern, even if it contains "%" or "_" characters that would normally act as wildcards.

The string does not get string-escaped or quoted. You do that later.

For instance, let's say you have a string name entered by the user, and you're searching a file column for items that match name followed by a dot and three letters. Even if name contains wildcard characters "%" or "_", you only want those to match literally, so "_" only matches "_" and "%" only matches a single "%".

You do that by "like-escaping" name, appending the wildcard pattern ".___", and finally, escaping and quoting the result for inclusion in your query:

tx.exec(
    "SELECT file FROM item WHERE file LIKE " +
    tx.quote(tx.esc_like(name) + ".___"));

The SQL "LIKE" operator also lets you choose your own escape character. This is supported, but must be a single-byte character.

References pqxx::internal::enc_group(), and pqxx::connection::encoding_id().

esc_raw() [1/3]

template<typename... ARGS>

auto pqxx::transaction_base::esc_raw

(

ARGS &&...

args

)

const

Escape binary data for use as SQL string literal in this transaction.

Raw, binary data is treated differently from regular strings. Binary strings are never interpreted as text, so they may safely include byte values or byte sequences that don't happen to represent valid characters in the character encoding being used.

The binary string does not stop at the first zero byte, as is the case with textual strings. Instead, it may contain zero bytes anywhere. If it happens to contain bytes that look like quote characters, or other things that can disrupt their use in SQL queries, they will be replaced with special escape sequences.

esc_raw() [2/3]

std::string PQXX_COLD pqxx::connection::esc_raw	(	unsigned char const	bin[],
		std::size_t	len
	)		const

Escape binary string for use as SQL string literal on this connection.

References pqxx::binary_cast(), and pqxx::internal::esc_bin().

Referenced by pqxx::connection::quote(), and pqxx::connection::quote_raw().

esc_raw() [3/3]

std::string pqxx::connection::esc_raw

(

std::basic_string_view< std::byte >

bin

)

const

Escape binary string for use as SQL string literal on this connection.

You can also just use esc with a binary string.

References pqxx::internal::esc_bin().

quote() [1/5]

template<typename T >

std::string pqxx::transaction_base::quote

(

T const &

t

)

const

Represent object as SQL string, including quoting & escaping.

Nulls are recognized and represented as SQL nulls.

quote() [2/5]

std::string pqxx::transaction_base::quote

(

binarystring const &

t

)

const

References pqxx::binarystring::bytes_view().

quote() [3/5]

template<typename T >

std::string pqxx::connection::quote

(

T const &

t

)

const

Represent object as SQL string, including quoting & escaping.

Recognises nulls and represents them as SQL nulls. They get no quotes.

References pqxx::is_null(), and pqxx::to_string().

Referenced by pqxx::connection::quote(), and pqxx::transaction_base::quote_raw().

quote() [4/5]

std::string PQXX_COLD pqxx::connection::quote

(

binarystring const &

b

)

const

References pqxx::binarystring::bytes_view(), and pqxx::connection::quote().

quote() [5/5]

std::string pqxx::connection::quote

(

std::basic_string_view< std::byte >

bytes

)

const

Escape and quote binary data for use as a BYTEA value in SQL statement.

References pqxx::connection::esc_raw().

quote_columns()

template<PQXX_CHAR_STRINGS_ARG STRINGS>

std::string pqxx::connection::quote_columns

(

STRINGS const &

columns

)

const

Quote and comma-separate a series of column names.

Use this to save a bit of work in cases where you repeatedly need to pass the same list of column names, e.g. with stream_to and stream_from. Some functions that need to quote the columns list internally, will have a "raw" alternative which let you do the quoting yourself. It's a bit of extra work, but it can in rare cases let you eliminate some duplicate work in quoting them repeatedly.

References pqxx::internal::as_c_string(), pqxx::check_version(), pqxx::connection::connection(), and pqxx::separated_list().

Referenced by pqxx::stream_to::table().

quote_name() [1/2]

std::string pqxx::transaction_base::quote_name

(

std::string_view

identifier

)

const

Escape an SQL identifier for use in a query.

Referenced by pqxx::stream_from::stream_from(), and pqxx::stream_to::stream_to().

quote_name() [2/2]

std::string pqxx::connection::quote_name

(

std::string_view

identifier

)

const

Escape and quote an SQL identifier for use in a query.

Referenced by pqxx::connection::get_var(), pqxx::connection::get_variable(), pqxx::connection::quote_table(), pqxx::connection::set_variable(), pqxx::connection::trace(), and pqxx::connection::unprepare().

quote_raw() [1/4]

std::string pqxx::transaction_base::quote_raw	(	unsigned char const	bin[],
		std::size_t	len
	)		const

Binary-escape and quote a binary string for use as an SQL constant.

References pqxx::binary_cast().

quote_raw() [2/4]

std::string PQXX_COLD pqxx::transaction_base::quote_raw

(

zview

bin

)

const

Binary-escape and quote a binary string for use as an SQL constant.

References pqxx::binary_cast(), pqxx::transaction_base::conn(), and pqxx::connection::quote().

quote_raw() [3/4]

std::string PQXX_COLD pqxx::connection::quote_raw	(	unsigned char const	bin[],
		std::size_t	len
	)		const

Escape and quote a string of binary data.

References pqxx::binary_cast(), and pqxx::connection::esc_raw().

quote_raw() [4/4]

std::string pqxx::connection::quote_raw

(

std::basic_string_view< std::byte >

bytes

)

const

Escape and quote a string of binary data.

References pqxx::connection::esc_raw().

quote_table() [1/2]

std::string pqxx::connection::quote_table

(

std::string_view

name

)

const

Escape and quote a table name.

When passing just a table name, this is just another name for quote_name.

References pqxx::connection::quote_name().

Referenced by pqxx::stream_from::stream_from().

quote_table() [2/2]

std::string pqxx::connection::quote_table

(

table_path

path

)

const

Escape and quote a table path.

A table path consists of a table name, optionally prefixed by a schema name; and if both are given, they are in turn optionally prefixed by a database name.

Each portion of the path (database name, schema name, table name) will be quoted separately, and they will be joined together by dots. So for example, myschema.mytable will become "myschema"."mytable".

References pqxx::connection::quote_name(), and pqxx::separated_list().

unesc_bin() [1/3]

std::basic_string<std::byte> pqxx::transaction_base::unesc_bin

(

zview

text

)

Unescape binary data, e.g. from a table field or notification payload.

Takes a binary string as escaped by PostgreSQL, and returns a restored copy of the original binary data.

unesc_bin() [2/3]

std::basic_string<std::byte> pqxx::transaction_base::unesc_bin

(

char const

text[]

)

Unescape binary data, e.g. from a table field or notification payload.

Takes a binary string as escaped by PostgreSQL, and returns a restored copy of the original binary data.

unesc_bin() [3/3]

std::basic_string<std::byte> pqxx::connection::unesc_bin

(

std::string_view

text

)

const

Unescape binary data, e.g. from a table field or notification payload.

Takes a binary string as escaped by PostgreSQL, and returns a restored copy of the original binary data.

(The data must be encoded in PostgreSQL's "hex" format. The legacy "bytea" escape format, used prior to PostgreSQL 9.0, is no longer supported.)

References pqxx::internal::size_unesc_bin(), and pqxx::internal::unesc_bin().

unesc_raw() [1/4]

std::string pqxx::transaction_base::unesc_raw

(

zview

text

)

const

Unescape binary data, e.g. from a table field or notification payload.

Takes a binary string as escaped by PostgreSQL, and returns a restored copy of the original binary data.

Start a block of deprecated code which may call other deprecated code.

Most compilers will emit warnings when deprecated code is invoked from non-deprecated code. But some compilers (notably gcc) will always emit the warning, even when the calling code is also deprecated.

This header starts a block where those warnings are suppressed. It can be included inside a code block.

Always match the #include with a closing #include of "ignore-deprecated-post.hxx". To avoid mistakes, keep the enclosed area as small as possible.

End a code block started by "ignore-deprecated-pre.hxx".

unesc_raw() [2/4]

std::string pqxx::transaction_base::unesc_raw

(

char const *

text

)

const

Unescape binary data, e.g. from a table field or notification payload.

Takes a binary string as escaped by PostgreSQL, and returns a restored copy of the original binary data.

Start a block of deprecated code which may call other deprecated code.

Most compilers will emit warnings when deprecated code is invoked from non-deprecated code. But some compilers (notably gcc) will always emit the warning, even when the calling code is also deprecated.

This header starts a block where those warnings are suppressed. It can be included inside a code block.

Always match the #include with a closing #include of "ignore-deprecated-post.hxx". To avoid mistakes, keep the enclosed area as small as possible.

End a code block started by "ignore-deprecated-pre.hxx".

unesc_raw() [3/4]

std::string pqxx::connection::unesc_raw

(

zview

text

)

const

Unescape binary data, e.g. from a table field or notification payload.

Takes a binary string as escaped by PostgreSQL, and returns a restored copy of the original binary data.

Start a block of deprecated code which may call other deprecated code.

Most compilers will emit warnings when deprecated code is invoked from non-deprecated code. But some compilers (notably gcc) will always emit the warning, even when the calling code is also deprecated.

This header starts a block where those warnings are suppressed. It can be included inside a code block.

Always match the #include with a closing #include of "ignore-deprecated-post.hxx". To avoid mistakes, keep the enclosed area as small as possible.

End a code block started by "ignore-deprecated-pre.hxx".

References pqxx::zview::c_str().

unesc_raw() [4/4]

std::string PQXX_COLD pqxx::connection::unesc_raw

(

char const

text[]

)

const

Unescape binary data, e.g. from a table field or notification payload.

Takes a binary string as escaped by PostgreSQL, and returns a restored copy of the original binary data.

References pqxx::internal::size_unesc_bin(), pqxx::text, and pqxx::internal::unesc_bin().