libpqxx 7.4.1: Fixing a build failure on macOS

This is a minor build fix. There are no other fixes, so if you have 7.4.0 and it works, this patch will make no difference to you.

But if 7,.4.0 failed to build on your system, this may well fix it.

libpqxx 7.4.0: "Named constructors," table paths, and more.

Named constructors

Some classes were getting too many constructors. Too much overloading makes for a programming minefield. So these classes are now growing factory functions, also known as named constructors.

For these classes, I would like applications to replace this kind of existing code:

pqxx::stream_to mystream(tx, "mytable");

with this new-style code:

auto mystream(pqxx::stream_to(tx, "mytable"));

Actually there's another change in that line; read on below.

Table paths

Sometimes you need to pass a table name to a libpqxx function. The function will often quote and escape that name internally. But what if the table name includes a schema name, and perhaps even a database name? If we quote the whole thing as one string, it will look to the database as a single weird name, with dots in it. What should happen is that libpqxx quotes each portion (database name, schema name, table name) separately, and puts bare dots between them.

To support that, there's a new way of describing table names: table_path, an alias for std::initializer_list<std::string_view>. Use this instead of strings to specify table names.

So instead of this:

auto mystream(pqxx::stream_to(tx, "mytable"));

...I would prefer you to write this:

auto mystream(pqxx::stream_to(tx, {"mytable"}));

The difference is that a table path is not just a name, it's a sequence of one, two, or three strings. (The last of those being the table name, of course.)

Which means that you can now also write:

auto mystream(pqxx::stream_to(tx, {"myschema", "mytable"}));

The rest

All major changes:

• Work around Visual Studio 2017 bug with [[deprecated]]. (#405, #406)
• Work around eternal Windows bug with max macro yet again. (#101)
• Prepare for C++20 std::ssize().
• Dropped test12, which didn't add much and tried to read null strings.
• Support string conversion for std::monostate. (#409)
• Consistent "named constructors" for stream_to and stream_from.
• New table_path type.
• New connection methods quote_table and quote_columns.
• Lots of deprecated stream constructors.
• pqxx::row::swap() now finally has the deprecated attribute.
• Finally deprecated a bunch of field, row, and result constructors.
• Exposed transaction_focus marker class.

libpqxx 7.3.1: New "large objects" API

This new release replaces the largeobject class and friends with a single, much simpler blob class. Down with complexity! The new API has no streams; I don't think those stream classes really added much over a basic "write these n bytes" API.

The largeobject hierarchy now has the deprecated attribute, so your compiler may warn you when you use it. A lot of other things that were merely documented as deprecated now have that attribute as well.

In other news: the documentation now describes the concept of "transaction focus." This is how libpqxx enforces rules such as "you can't issue a query on a transaction while there's a pipeline open on that transaction," or "you can't have two table streams open on one transaction at once," or "you can't issue queries on a transaction that currently has an active subtransaction."

The errors themselves also got better: if you give your query a name or description —it's entirely optional— then an error message caused by that query can now actually mention that name. This is of no help when your code is running smoothly, but it can make debugging easier.

I'm also dipping a toe in the water of "named constructors." Some classes, particularly stream_from and the new blob, have too many constructors. Overloading can get a bit finicky, and the differences in meaning are not always very clear.

So for instance instead of just constructing a blob, for instance, and passing a "read-only please" argument, you do it like this:

    auto myblob = pqxx::blob::open_r(mytransaction, blob_id);

And similar for read-write or write-only. There is a new named constructor for stream_from as well, though only for the "stream from query" case. For the "stream from table" case, I'm still looking at the overloading possibilities for the list of columns.

libpqxx 7.3.0: no new features, but lots of changes

Sorry, no shiny new features on this one. But a lot of std::string const & parameters are now either std::string_view or (if we're passing them on to the C-level library) pqxx::zview. Depending on how exactly you call those functions, it may speed up your code by eliminating some implicit string constructions and heap buffer allocations. Also some little compile fixes, of course.

Under the hood, though, it's a different story. I broke up the biggest inheritance hierarchy, which included almost all the major classes: the transaction classes, pipeline, streams, and so on. It is now two, much smaller, inheritance hierarchies. It rids us of the one case of virtual inheritance that the library had.

You may hit some minor compile problems with the changed parameter types. If you built your own transaction classes, you'll have to deal with some major changes. In the longer run we're going to drop the ability to plug your own transaction types into the hierarchy, and make more things final.

libpqxx 7.2.1: bug fixes, deprecations, and tweaks

Here's a new patch release. Changes are:

• Fix infinite loop in converting char * to string. (#377)
• Deprecated namedclass.
• Convert an entire row using row::as<type...>().
• Internal rework of field::to() and field::as() functions.
• Some more warning options in maintainer mode.
• Removed the old, DocBook-based tutorial.
• Fixed wrong query and SQLSTATE params to some exceptions. (#378)

Okay, okay, there's one nice new feature there. You can now convert an entire result row to client-side types at once. See row::as().

libpqxx 7.2.0: Another big bang release.

Many things have changed in this release:

• You can now implicitly convert a const std::string & to zview.
• Replaced some overloads for C strings and C++ strings with zview.
• Deprecating binarystring. Use std::basic_string<std::byte> instead!
• Array parser did not recognise escaping in unquoted values.
• Document that string conversions assume non-null values.
• Sketch out concepts-based PQconnectdbParams support. (#343)
• Fixed infinite recursion when using std::optional in stream_to. (#364)
• Catch floating-point negative overflow in check_cast, not underflow.
• Bit more work on CMake build doc. (#318)
• Experimental support basics for composite types. (#355)
• Use stream_from without knowing the number of fields. (#357)
• Global size_buffer function.
• quote() now works for always-null types without conversions defined.
• std::nullopt now converts to an SQL null.
• New type trait: is_unquoted_safe.
• Fixed mktemp invocation that broke on FreeBSD.

For a more complete list, see the NEWS file inside the codebase. Several more bugs were fixed, and there were performance improvements as well.

A few highlights in more detail:

String overloads. Many overloaded functions in libpqxx take "strings" of various kinds: there's C-style strings (char const *), C++ strings (std::string), there's std::string_view, and then there's pqxx::zview — which is a string_view where the creator promises that there's a terminating zero behind it. A bunch of these functions have been simplified and now just take zview. You can now implicitly convert a string to a zview too — but be careful to keep the string alive and unchanged while you may still use the zview!

Arrays. There was an important fix in the array parser, which previously did not support escape sequences in unquoted values. On the other hand, generating SQL arrays using to_string now makes fewer allocations, thanks to an optional new type trait.

Binary data. Another significant change is that binarystring is now deprecated. To work with binary values such as SQL's BYTEA type, represent them on the client side using the std::byte type: represent binary values as std::basic_string<std::byte> or std::basic_string_view<std::byte>. The string conversions know about these types, so you can use from_string() and to_string() to convert these types back and forth between their C++ and SQL forms.

Composite types. There is experimental support for SQL "composite types." You can now convert an incoming field of such types into a series of C++ values using the field's composite_to() method. Likewise there is a helper for representing a series of C++ values as an SQL composite-type object. The best way to use these is probably to write your own C++ type, and write custom string conversions for it. See datatypes.md for more about how to do this. The string conversions can call the existing libpqxx functions for convenience.

Enjoy!

libpqxx 7.1.2: Almost not a patch release

Lots of changes here, some important:

• Document build in BUILDING-configure.md / BUILDING-cmake.md.
• Work around silly clang warning in test_errorhandler.cxx.
• Fix install error with some internal headers. (#322)
• Fix "No object selected" error message in large objects. (#324)
• If error has no SQLSTATE, throw broken_connection. (#280)
• Fix argument order in encrypt_password. (#333, #334)
• Fix underestimate of buffer size for to_string for floats. (#328)

libpqxx 6.4.7: Patch update to last pre-C++17 release

By request, here's an update to the last 6.x release. It fixes a link error where, when building libpqxx as a shared library, you might not have the nullptr_t specialisation of extract_value in stream_from.

This is in response to #340, but it may help others with compilers which don't support C++17.

libpqxx 7.1.1: some tweaks

A big release always reveals some things that need fixing. Here's a few build tweaks, and a fix for a missing file in the install.

libpqxx 7.1.0: A whole new way of querying data

Another big update.

The bad news:

• Any string_traits<TYPE>::size_buffer() must now be noexcept.
• There's an extra data member in nullness: always_null. You'll need to implement to give your type full functionality.

The good news: there's a new way of retrieving data from the database! It's faster, it's easier, it includes conversion to a type of your choice. Using transaction::stream, you can query rows from the database straight into a std::tuple, and so, into local variables:

for (auto const [id, name] : tx.stream<int, std::string_view>("SELECT id, name FROM item"))
    process(id, name);

And in other news...

• stream_from now supports more or less arbitrary queries.
• Instead of a tuple of fields, you can pass stream_to a container as well.
• There is now to_buf support for string literals.
• Streaming data is now more efficient.
• The table name in stream_from is now escaped.
• You can now "convert" strings to std::string_view. Mind your lifetimes!
• A std::variant will now convert to string, if its member types do.
• If a stream_from row fails to convert, you can no longer retry it.
• from_string(field const &) now handles null values properly.
• Obsolete Windows build docs are gone.
• Added row::to(std::tuple<...>) — converts the whole row in one go.
• Unified the test suites. We no longer need test/unit/unit_runner.
• New helper: strip_t<...> to remove a type's constness and reference.
• Replace some custom templating in CMakeFiles with CMake globs.