First, you need to run in the same user session as you call the maapi_init_upgrade() from. You either want to associate with an already existing user session from where you will init the upgrade, or you start a new session from where you init the upgrade.
As the ConfD UG describes in the subchapter preceding your quote, i.e. “Preparing for the Upgrade”:
The upgrade.c program in the example controls the upgrade procedure. It can be run either standalone or via a osCommand specification in the clispec. In both cases it must connect a MAAPI socket and associate it with a user session. When running from the CLI, it must use the user session id provided by the environment variable CONFD_MAAPI_USID for this, otherwise it can start a new user session:
static int set_usess(int sock)
{
char *user = "admin";
const char *groups[] = {"admin"};
char *context = "system";
struct confd_ip ip;
/* must use usid from CLI to be allowed to run across upgrade */
if ((usid_env = getenv("CONFD_MAAPI_USID")) != NULL) {
return maapi_set_user_session(sock, atoi(usid_env));
} else {
ip.af = AF_INET;
inet_pton(AF_INET, "127.0.0.1", &ip.ip.v4);
return maapi_start_user_session(sock, user, context, groups, 1,
&ip, CONFD_PROTO_TCP);
}
}
For a reference implementation, see the ConfD in_service_upgrade example:
$CONFD_DIR/examples.confd/in_service_upgrade/with_helper/upgrade.c
Then after maapi_preform_upgrade() and before maapi_commit_upgrade() you need to attach to the ConfD upgrade transaction using maapi_attach_init() to read/write to/from the old/new schema.
As the ConfD UG describes in the subchapter following your quote, i.e. “Committing the Upgrade”:
When maapi_perform_upgrade() has completed successfully, we must call maapi_commit_upgrade() to tell ConfD to make the upgrade permanent. This will also tell CDB to commit its upgrade transaction, and we may need to take some actions for this before the call:
• If the upgrade requires that an external program modifies some CDB data, it must be done at this point, using maapi_attach_init() as described in the CDB chapter.
…
From the confd_lib_maapi man page:
int maapi_attach_init(int sock, int *thandle);
This function is used to attach the MAAPI socket to the special transaction available in phase0 used for CDB initialization and upgrade. The function is also used if we need to modify CDB data during in-service data model upgrade (see the “In-service Data Model Upgrade” chapter in the User Guide). The transaction handle, which is used in subsequent calls to MAAPI, is filled in by the function upon successful return. See the CDB chapter in the User Guide.
See $CONFD_DIR/examples.confd/cdb_upgrade/using_maapi/server_upgrade.c
for an example of using maapi_attach_init()
...
maapi_attach_init(ms, &th);
maapi_set_namespace(ms, th, servers__ns);
/* Loop over servers and set default values for new elems */
maapi_init_cursor(ms, th, &mc, "/servers/server");
maapi_get_next(&mc);
while (mc.n != 0) {
maapi_set_elem2(ms, th,
"0.0.0.0", "/servers/server{%x}/proxy", &mc.keys[0]);
maapi_set_elem2(ms, th,
"true", "/servers/server{%x}/enabled", &mc.keys[0]);
maapi_get_next(&mc);
}
maapi_destroy_cursor(&mc);
...