libpqxx 8 is ready for you!
===========================
Libpqxx 8 is the library's biggest release ever.
It's been a long trek.  On the one hand it was a parallel journey to the

adoption of C++20.  We're not relying on all the new C++20 features, but

concepts, std::source_location, spans, and ranges are integral parts of the

design.  Also I was hit by a health problem that reduced the amount of work I

could do, and often made it hard for me to trust my own judgment.  Luckily that

happened after most of the important design work was done, or you would not see

this release today.
On the other hand, I've also had help: community members reported bugs and

submitted patches, some of very high quality.  And people helped each other

out, which is awesome to see.  A Copilot subscription on GitHub helped with an

extra layer of code reviews.  It found a lot of typos in comments, but also

some genuine and sometimes subtle mistakes.  (I didn't let it write actual code

though; it gets too many things wrong, some of which I would probably not have

caught in review.  Kernighan's Law applies.)  Other large language models, in

particular Claude, helped a lot in solving configuration problems.
Perhaps most of all, my wonderful former employer Eonics brought together a

Mastermind group where a bunch of us discuss our hobby projects, learn, and

share questions and ideas.  The group often came up with unexpected and helpful

approaches for my problems.  If you have a hobby project, I wholeheartedly

recommend looking for a mastermind group near you!  And if you speak Dutch,

have a look at the Eonics website.  You'll find podcasts,

hack nights, interviews, and much else to make IT work fun.
Thank you
Several people helped.  I'm probably missing somebody, but I wanted to thank...

@tt4g for helping lots of people with their

questions, often before I even see them.
Klaus Silveira @klaussilveira), our

first donor-level sponsor.
Hendrik M. @Tosenaeus, who also sponsors us.
Eonics, CoffeeSprout,

ComPosiX, and the whole Eonics Mastermind team.
Kirit Sælensminde, for discussing features, ideas, and

C++ language changes.
J.H.M. "Ray" Dassen, much missed, who did a lot to help get libpqxx off the

ground, all the way back.
All those who submitted patches, reported problems, or asked for

improvements.

What's changed?
Just about everything has changed at least a little bit.
349 files changed, 28826 insertions(+), 24686 deletions(-)

Most "standard" code using libpqxx will still work without changes, but often

you'll find that there are now better ways to do things.  Functions and classes

that were deprecated three years ago are now gone.  Some other ones are now

deprecated, and will be gone a few years from now.
The API has become better at helping you keep your code memory-safe and

verifiable by static code analysis.  There are fewer raw, C-style pointers.

At the same time some things have become more efficient through the use of

views, especially string_view, and internal simplifications.  Ranges and

spans have made things clearer and simpler.  Concepts have made some things

more flexible.
More details follow.  See the NEWS file for a more complete list with less

detail, or UPGRADING.md for advice on how to deal with breaking changes.
Things that can break with old code
If you're just using 8.0 as a drop-in replacement for an older version in an

existing application, this may be the only useful section for you.
C++20 is now the minimum.  As per the above it's fine if some C++20

features don't work for you yet, but concepts definitely need to work, and

you'll need a bunch of the new C++20 standard library features.
PostgreSQL 11 is now the absolute minimum.  You won't be able to connect to

older servers.  The exact version is a fairly arbitrary choice.  The oldest

version supported upstream is 14, so hopefully 11 is liberal enough.
Exceptions have changed.  The whole class hierarchy is different, so if

you do any detailed catching you'll have to review that.  On the bright side,

libpqxx exceptions are now all derived from pqxx::failure so you may not need

as many catch blocks as before.  Your handler can figure out much of what it

needs by calling the exception's member functions, rather than by knowing its

type.
Rows and fields have changed.  The old row and field classes used to

keep a result object alive in memory, even if you destroyed the result

object.  Now, most of the time you'll get a row_ref or field_ref which does

not do that.  Be careful with lifetimes, but it rarely becomes an issue, and

the new classes are simpler and more efficient.
Result & row iterators have changed.  Indexing an iterator now finally does

what the C++ standard says, even though it's probably less intuitive or useful.

If you previously did i[n], you'd now do (*i)[n].
Comparing results, rows, or fields now compares identity, not contents.  I

doubt anyone ever used what these == operators did.
pqxx::bytes is now an alias for std::vector<std::byte>, not a

std::basic_string<std::byte>.  It's not clear that the fine print in the

standard ever quite allowed the string definition.  Some code will require

small changes at compile time.  If you ever used the c_str() member function,

now you'll use data().  More appropriate for binary data.
The string conversion API has changed.  This is the extensible API that

converts between C++-side objects and their SQL text formats.  If you wrote

your own to support additional types, those should still work; but the newer

API is generally easier, safer, and more efficient if you want to optimise.
A lot of strings no longer have or need a terminating zero.  This includes

the string conversion API.
In some situations, a params will require text encoding information.  In

those situations, pass your connection, transaction, or encoding group as the

first argument to the params constructor.
No longer supports std::filesystem.  Nor does the build try to figure out

whether it needs to link any additional libraries to make it work.
A zview can no longer contain a null pointer.  This used to be valid for

empty strings, but it no longer is.
More classes are now final.
The scripts in tools/ have been revised.  Shell scripts now have a ".sh"

suffix to their name.  Some old tools are gone: rmlo,pqxxthreadsafety,

test_all.py.
The JOHAB encoding is not supported.  As far as we can tell, there is no

single standard for how this encoding was supposed to work, and support on the

server side never fully worked anyway.  It will be removed from PostgreSQL.
Some deprecated items are now gone:

binarystring (use blob instead).
connection_base (use just connection, it's the same thing).
encrypt_password() (use the equivalents in connection).
dynamic_params (use params instead).
transaction_base::unesc_raw() (use unesc_bin() instead).
transaction_base::quote_raw() (use quote(bytes_view) instead).
Some field constructors.
Row slicing.  Has anyone ever used this?

Querying continues to evolve
Querying data has been growing simpler and more regular for a while now.  But

I'll summarise how the 8.0 way of querying differs from the old ways.
Passing statement parameters: You no longer call separate exec(),

exec_params(), or exec_prepared().  Instead, you just call exec(), and

in addition to the query, pass a params object if the statement needs

parameters.  If the query is a prepared statement rather than SQL text, you

use its name, wrapped in a pqxx::prepped object:
tx.exec(
    pqxx::prepped{"my_query"},
    pqxx::params{1, 23, "param");
Executing, querying, streaming: These are the three models for executing a

query, and where possible they look similar.  "Executing" a query is the

classic exec() function, and it returns a pqxx::result.  "Querying" works

very similar, but you pass template arguments to state which types of result

columns you expect, and then you iterate over the return value.  "Streaming"

looks a lot like querying but is optimised for large data sets: it's slower for

small numbers of rows but faster for large numbers.  (Sadly a streaming query

can not take parameters.)
Expected result sizes: If you want to make sure that a query returns a

specific number of rows, you no longer use exec0(), exec1(), or exec_n();

you just use exec() and then call a member function on the result such as

no_rows(), one_row(), or expected_rows().  There are similar functions

for the number of columns.
Various new features
This is not a complete list!  There's more than I can fit in here.  You'll

have to explore the documentation or the code to find them all.
Here are some major ones:
Example code.  There is now an examples/ directory containing source for

various toy applications.  There will be more in the future.  Unlike the tests,

these examples are entirely meant for you, to illustrate what you can do with

libpqxx.  But unlike the documentation, they get compiled and run along with

the test, so they won't fall out of date.
Source locations & stack traces: A libpqxx exception can now tell you the

associated std::source_location and, if your compiler supports it, a full

std::stacktrace.
Easier SQL arrays: Single-dimensional SQL arrays are now super easy, barely

an inconvenience.  You can now pass a std::vector<double> as a statement

parameter and libpqxx will convert it to an SQL array.  You can stream a

std::array<std::string> directly out of an SQL array in a query, read a

result field of SQL array type as a std::inplace_vector<int>, and so on.

Multi-dimensional arrays are a bit harder, but not much: the pqxx::array

class does all the parsing for you.
Generic binary data: Where you need to pass binary data to a libpqxx

function, you can now generally pass any contiguous block of std::byte.
Result & row iterators are now proper random access iterators.  This may

allow some algorithms to work more efficiently.
Encoding groups.  Sometimes when dealing with text, libpqxx needs to know

its encoding.  It doesn't need to know the exact encoding, but it does need

enough information to be able to tell, for example, a closing quote in an SQL

string from a byte in a multibyte character that happens to have the exact same

value.  There is an enum to describe the different basic encoding schemes, and

it is now part of the public API.
Combine connection strings and connection parameters.  You could already

create a connection based on a connection string, or on key/value parameters.

Now you can pass both.
Nicer connection::port_number() to replace connection::port().  The old

function returned a C string, thanks to the underlying C API.  The useful

information is "either a number, or nothing."  The new function returns

std::optional<int> as you'd expect.
If available, uses C++ Reflection to obtain type names.  This replaces a

bunch of string constants that triggered false-positive alerts in some

verification tools such as Valgrind.
Build improvements
The build has also seen some improvement:
Minimum C++ version.  If you're building as C++20, you no longer need to

pass an explicit option like -std=c++20 on the compiler command line.  Both

the CMake build and the configure build now default to C++20 if nothing is

specified.
Unity builds.  This style of build combines multiple C++ translation units

into a single huge C++ file.  This enables some cross-module optimisation, but

(under the right circumstances) can also speed up the build.  This is now

supported in the CMake build.
More parallelism in configure build.  A new, "flattened" hierarchy of

"make" targets reduces unused CPU time while compiling.  The tests are now in a

single directory.
Various MSVC fixes.  There were some compilation problems, and lots of

warnings, with Microsoft Visual Studio in particular.  There was even an error

(apparently due to a compiler bug) in the 2026 edition.  Fixed.
Test against ASCII-only databases.  The regular libpqxx CI tests run

against databases that support full Unicode.  But some users test against

ASCII-only databases, which broke the more advanced tests.  The tests will now

skip those checks if the database does not support Unicode.
Handy function to render a std::source_location as text.  Called

source_loc(), this produces a more or less standard format that IDEs seem to

parse well, but which humans can also read.
Only one generated config header.  When you configured a build, it used to

generate several config-*.h headers in your build tree's include/pqxx/

directory.  Now it's only config-compiler.h.  And it contains only relevant

macros, prefixed with "PQXX", even in the CMake build.
If you like it
Libpqxx represents decades of FTE work, mostly done in my spare time.  If

you would like to support this, please consider sponsoring by a small amount

that you can spare:

Through GitHub: https://github.com/sponsors/jtv
Through Buy Me A Coffee: https://buymeacoffee.com/pqxx

This helps me pay for the costs of maintaining and publishing the library, and

if enough people contribute, I'd like to do something nice for those who

contribute their time, insights, and effort by supporting fellow users or

submitting patches.

View the full release notes at https://github.com/jtv/libpqxx/releases/tag/8.0.0.