All tables have a rename_field() method, which renames one or more columns in the target. It's a wrapper for SQL's ALTER TABLE ... RENAME COLUMN.

Continuing our story from the previous section, we have a table known in C++ by the name new_points, its value type is point_xz, its target is the SQL table points, the target exists and it conforms to new_points. We even have new_points open. Let's close it again:

new_points.close();

because there's another alteration coming.

Suppose we no longer like the C++ member name z; we now prefer height. In future we would like to be using this value type:

struct point_xh {
    float x;
    float height;
};
QUINCE_MAP_CLASS(point_xh, (x)(height))

and this is the table we want to be using:

table<point_xh> newer_points(db, "points", &point_xh::x);

We can't open newer_points yet because the target doesn't conform to it: one of its columns has the wrong name. Here's the solution:

newer_points.rename_field(new_points->z, newer_points->height);

which says:

(Or we could have written:

new_points.rename_field(new_points->z, newer_points->height);

which does the same thing.)

Now the target conforms to newer_points, so we can call newer_points.open() and proceed.

In this example we passed float mappers to rename_field(), so it renamed a single REAL column; but the mappers can be for any mapped type, as long as it's the same mapped type for both (checked at compile time). If it is a multi-column type, then rename_field() will rename multiple columns.

To defend against programmer error, table.rename_field(old, new) checks (at run time) that either old or new is part of table's value mapper.