[zmij]

Summary

Add StructView<T, Members...> for reading and writing a selected subset of fields of a C++ structure.

This allows application structures to be used directly with PostgreSQL even when a query operates on only part of the structure. The selected members are specified at compile time using member pointers.

The same view can be used for both reading and writing:

using StoredUser = StructView<
    User,
    &User::id,
    &User::name,
    &User::email>;

auto user = result.AsSingleRow<StoredUser>(kRowTag);

transaction.Execute(
    "UPDATE users SET name = $1, email = $2 WHERE id = $3",
    StructView<User, &User::name, &User::email, &User::id>{user});

With no members specified, StructView<T> represents the complete structure using Boost.PFR.

Reading stored fields into a larger application structure

Application structures often contain fields that are not stored in a particular database table. Previously, direct row conversion required the PostgreSQL row to match the complete structure.

For example:

struct User {
    std::int64_t id;
    std::string name;
    std::string email;

    // Computed or populated elsewhere
    Permissions permissions;
    std::vector<Team> teams;
};

while the database stores only:

SELECT id, name, email
FROM users

The stored projection can now be described directly:

using StoredUser = StructView<
    User,
    &User::id,
    &User::name,
    &User::email>;

auto users = result.AsContainer<std::vector<StoredUser>>(kRowTag);  // std::vector<User>

The selected fields are populated from the PostgreSQL row, while the remaining members keep their default values. A container of views is rebound to a container of the underlying structure, allocator included.

This avoids introducing database-specific DTOs or manually copying query results into the application's existing types.

Partial updates

The same mechanism can select exactly the members used as query arguments:

using UserNameUpdate = StructView<
    User,
    &User::name,
    &User::email,
    &User::id>;

transaction.Execute(
    "UPDATE users "
    "SET name = $1, email = $2 "
    "WHERE id = $3",
    UserNameUpdate{user});

The structure remains the source of the arguments, while the view explicitly defines their order and which members participate in the query.

Ad-hoc projections can be used directly when introducing a named type is unnecessary:

transaction.Execute(
    "UPDATE users SET name = $1 WHERE id = $2",
    StructView<User, &User::name, &User::id>{user});

MakeStructView deduces the structure from the argument, so only the members have to be written out:

transaction.Execute(
    "UPDATE users SET name = $1 WHERE id = $2",
    MakeStructView<&User::name, &User::id>(user));

Queries using a single structure member

Views are also useful when only one member of an existing object is required:

transaction.Execute(
    "DELETE FROM users WHERE id = $1",
    StructView<User, &User::id>{user});

There is no need to extract user.id separately or introduce another argument representation.

Full structures

An empty member list means the complete structure:

StructView<User>

and uses Boost.PFR structural introspection.

This makes full and partial structural mappings use the same abstraction:

StructView<User>                         // all fields
StructView<User, &User::id>              // id only
StructView<User, &User::name, &User::id> // selected fields

Decomposed and bulk execution of containers

ExecuteDecompose and ExecuteDecomposeBulk send a container of structures column by column, one array parameter per member. A view now selects which members become those columns, and in which order. The container keeps holding the original structures, and the view is applied to each element:

std::vector<User> users = ...;

// The view type named explicitly
using UserIdName = StructView<User, &User::id, &User::name>;
transaction.ExecuteDecompose(
    "INSERT INTO users(id, name) SELECT * FROM unnest($1, $2)",
    StructViewContainer<UserIdName>(users));

// The structure deduced from the container, only the members named
transaction.ExecuteDecomposeBulk(
    "INSERT INTO users(email, id) SELECT * FROM unnest($1, $2)",
    MakeViewContainer<&User::email, &User::id>(users),
    chunk_rows);

// Every member, through the cluster
cluster.ExecuteDecompose(
    ClusterHostType::kMaster,
    "SELECT * FROM unnest($1, $2, $3)",
    MakeViewContainer<>(users));

Supported calls:

Call	Transaction	Cluster
ExecuteDecompose (with and without command control)	yes	yes
ExecuteDecomposeBulk (with and without command control)	yes	not provided
ExecuteBulk	rejected at compile time	not provided

• StructViewContainer<View>(container) and MakeViewContainer<Members...>(container) are helper functions returning a borrowing wrapper, so the wrapper must not outlive the container. C++20 class template argument deduction can't take the view explicitly and also deduce the container, which is why these are functions.
• ExecuteBulk sends each chunk as a single array of the element type. A subset of a structure's members has no PostgreSQL type to map to, so passing a view container fails to compile with a hint to use ExecuteDecomposeBulk.
• Cluster has no bulk variants, as before: bulk runs several statements and needs a transaction around them.

The column-splitting helpers now project through the view, with StructView<value_type> as the default. As a result, plain ExecuteDecompose and ExecuteDecomposeBulk also accept containers of structures with an intrusive Introspect(). Previously they were limited to Boost.PFR aggregates.

Motivation

Queries rarely map one-to-one to complete application structures. Application types may contain computed or transient data, while updates and deletes often operate on only a handful of fields.

StructView makes these projections explicit without requiring:

• query-specific DTOs;
• manual extraction of individual structure members;
• intermediate JSON or other serialization representations;
• runtime field-name mappings.

Member pointers keep the mapping compile-time checked and refactoring-friendly, while Boost.PFR provides the full-structure case without additional declarations.

---

Note: by creating a PR or an issue you automatically agree to the CLA. See CONTRIBUTING.md. Feel free to remove this note, the agreement holds.