Updating AkasicDB¶

This guide explains how to update AkasicDB within the same major version, using v2.0.0 → v2.0.1 as an example.

Install the target release distribution and restart the server, then run the following two commands in order in each database containing AkasicDB.

ALTER EXTENSION akasicdb UPDATE;
SELECT akasicdb_admin.update();

ALTER EXTENSION updates AkasicDB to the installed distribution's default version and installs or updates the management function for that release. akasicdb_admin.update() updates internal components to match the AkasicDB release installed in the database. Both commands must succeed for the update to be complete.

Applicable Versions¶

This procedure applies when the currently installed AkasicDB version and the target version have the same major version.

For a fresh installation, follow Installation. A database newly installed with the target release already includes that release's components and does not need the update commands above.

Before updating, check the release's WAL compatibility, replication and recovery requirements, and downgrade support. See the release notes for details.

Updating from v2.0.0 to a later patch version

When updating from v2.0.0 to a later patch version, the vector engine's WAL resource manager ID changes from 128 to 160. PostgreSQL must be shut down cleanly using the existing binaries before installing the new distribution.

Historical WAL written by v2.0.0 is not converted automatically. Crash recovery requiring replay of WAL with ID 128, physical replication and PITR transitions, and downgrading to older binaries are outside the scope of this update procedure.

Before Updating¶

Connect to the database you want to update and check the PostgreSQL version and installed extension versions.

SHOW server_version;

SELECT current_database();

SELECT extname, extversion
FROM pg_catalog.pg_extension
ORDER BY extname;

Confirm that the current versions of AkasicDB and the components being updated are supported starting versions for the target release.

Identify the databases to update and the existing data directory, configuration, and license paths. Prepare backups according to your operational procedures. Stop application writes during the update.

Update each database

The pg_extension query shows the state of the database you are currently connected to. Check and update each database containing AkasicDB.

If the cluster was initialized with akasicdb-initdb or a Docker image and AkasicDB is also installed in the default database and template, include postgres and template1. After updating template1, databases subsequently created from that template inherit the updated extension versions. Existing databases must each be updated separately.

Install the Target Release and Restart the Server¶

Shut down PostgreSQL cleanly using the existing binaries and confirm that shutdown has completed.
Install the target AkasicDB release distribution for the same PostgreSQL major version and edition as the existing server. Apply the complete distribution, including libraries, control files, installation SQL files, and update SQL files.
Start PostgreSQL using the existing data directory and configuration.

Distribution	Procedure
Binary package	With the server stopped, install the target release package and start the server using the new binaries.
Docker image	Shut down the existing server cleanly, then recreate the container with the target release image for the same PostgreSQL major version and edition. Preserve the existing data volume and configuration and license mounts.

This update uses the existing cluster, so do not run initdb again. See Installation for installation paths and runtime environment settings.

Replacing distribution files or a Docker image alone does not change extension versions in existing databases. Docker deployments that reuse an existing data volume also require the SQL steps below. Docker initialization scripts run only when the data directory is empty.

Update Each Database¶

Connect to the database you want to update using an account with administrative privileges. When using psql, we recommend configuring it to stop on errors as shown below. Adjust the connection details for your environment.

psql -X -v ON_ERROR_STOP=1 -h 127.0.0.1 -p 5432 -U postgres -d mydb

Check that the installed distribution's default version matches your target version.

SELECT name, default_version, installed_version
FROM pg_catalog.pg_available_extensions
WHERE name = 'akasicdb';

default_version is the default version specified in the installed control file, and installed_version is the extension version in the current database. If default_version matches your target version, run the following two commands in order.

ALTER EXTENSION akasicdb UPDATE;
SELECT akasicdb_admin.update();

Each command performs the following work.

Command	Result
`ALTER EXTENSION akasicdb UPDATE`	Updates AkasicDB to the installed distribution's default version and installs or updates the `akasicdb_admin.update()` function for that release. Internal components are updated by the next command.
`SELECT akasicdb_admin.update()`	Checks component versions and binary state against the installed AkasicDB release's requirements, updates internal components, and verifies their final versions.

After the first command succeeds, run the second command. The management function updates internal extensions, so you do not need to run update SQL for each component yourself.

Call akasicdb_admin.update() without arguments. If the internal components are already at their target versions for the same release and the binary checks pass, the function succeeds without making changes.

Why the commands run in order

PostgreSQL does not allow an extension update script to update another extension. The first command defines the management function for the release. The next command calls it after the extension script has finished executing.

You can also specify the target version directly in SQL. For example, when updating to v2.0.1, write the first command as follows.

ALTER EXTENSION akasicdb UPDATE TO '2.0.1';

Verify Completion¶

After both commands have executed and their changes have been committed, check extension versions in each database.

SELECT extname, extversion
FROM pg_catalog.pg_extension
ORDER BY extname;

Confirm that AkasicDB is at the target version and that each updated internal component is at the version specified by that release. Target versions can differ between components, and components outside the update's scope may retain their existing versions.

Check that queries against existing data and key searches using indexes work correctly. Resume application writes after updating and checking all target databases.