#Upgrade

This document provides instructions for upgrading Alauda Hyperflux to a newer version.

#Standard Upgrade Steps

For most version upgrades (except for v1.2.0 → v1.2.1 and v1.3.x → v1.4.x), you can simply follow these steps in the ACP console:

1. Upload the new version of the plugin package to the ACP Marketplace. Upload the package in the same way as the initial installation. After the upload is complete, wait for approximately 10–15 minutes for the platform to automatically synchronize the new version information.
2. Verify that the new version is available in the Marketplace. Go to Administrator / Marketplace / Upload Packages. Switch to the Cluster Plugin tab and confirm that the new version number is displayed for the Hyperflux plugin.
3. Execute the upgrade operation on the cluster. Navigate to Administrator / Clusters / Clusters. Find the cluster where the Hyperflux plugin is installed; an upgrade icon will be displayed in the cluster entry. Click to enter the cluster details, and switch to the Features tab. On the Hyperflux plugin card, click the Upgrade button and confirm the operation.
4. Verify the upgrade result. After the upgrade is complete, confirm that the version number has been updated in the Features tab. Verify normal operation through plugin status monitoring or logs.

#Upgrading from v1.3.x to v1.4.x (Embedding Model Switch)

IMPORTANT: v1.4.0 ships a new embedding model (gte-multilingual-base, replacing paraphrase-multilingual-mpnet-base-v2). The vector spaces are not compatible, so the system knowledge base must be re-embedded. The chart does this automatically during the upgrade — but please read this section before applying, especially if you have built a custom knowledge base.

#What the upgrade does automatically

When the new chart rolls out, the init container scans docvec_sys_kb for any legacy mpnet collection that matches a rule in smartdoc.acpKbUpgradeRules (default: ACP 4.1 and ACP 4.2 mpnet collections), then:

1. Acquires a PostgreSQL advisory lock keyed on acpKbDataVersion so a second replica's init exits cleanly.
2. Records the in-flight swap into a kb_swap_state row (so it can recover if the pod is killed mid-swap).
3. Drops the langchain_pg_embedding and langchain_pg_collection tables in docvec_sys_kb.
4. pg_restore the new gte dump from /workspace-smart-doc/dumps/ (warnings about pre-existing extensions/ schemas are tolerated, hard errors abort).
5. Verifies the new collection name landed (SELECT count(*) ... = 1); aborts otherwise.
6. Renames the new collection back to the old collection name so the running server keeps querying the same name. You do not need to change pgconnect.pgCollectionName.
7. Rebuilds the ParadeDB BM25 index if the new dump didn't already ship one (recent gte dumps include it).
8. Stamps schema_migrations with 003_data_swap_<old_collection>_<acpKbDataVersion> and clears the inflight kb_swap_state row.
9. After the swap block returns, an unconditional migration loop re-applies the doc_id btree (001_add_doc_id_index) and the URL-backfill (002_backfill_doc_id_from_url) against the freshly restored table — the swap block clears their stamps so the loop sees them as "not applied" and runs them.

The swap is:

• Idempotent — a chart re-roll without changing acpKbDataVersion is a no-op.
• Crash-safe — pod kill between DROP and RESTORE is recoverable on next start.
• Multi-replica safe — a PostgreSQL advisory lock keyed on acpKbDataVersion serialises the swap.

#Recommended pre-upgrade backup

The swap drops the old collection and replaces it with new data; the old mpnet vectors are not retained. Even though the bundled dumps are reproducible, take a backup of docvec_sys_kb and docvec_user_kb before upgrading so you can roll back if anything goes wrong:

# Get the PostgreSQL pod name (if using the built-in database)
kubectl -n cpaas-system get pod | grep postgre-vec

# Dump both knowledge-base databases. The default password for the built-in PostgreSQL
# instance is `alauda-test`; pg_dump will prompt for it. To suppress the prompt, prefix
# with `PGPASSWORD=alauda-test ` inside the exec.
kubectl -n cpaas-system exec -it <postgre-vec-xxx> -- pg_dump -U postgres -W -Fc \
  -d docvec_sys_kb -f /tmp/docvec_sys_kb.backup.dump
kubectl -n cpaas-system exec -it <postgre-vec-xxx> -- pg_dump -U postgres -W -Fc \
  -d docvec_user_kb -f /tmp/docvec_user_kb.backup.dump

# Copy them to your local machine
kubectl -n cpaas-system cp <postgre-vec-xxx>:/tmp/docvec_sys_kb.backup.dump ./docvec_sys_kb.backup.dump
kubectl -n cpaas-system cp <postgre-vec-xxx>:/tmp/docvec_user_kb.backup.dump ./docvec_user_kb.backup.dump

docvec_user_kb and the chat-history database are not touched by the swap — but a backup is cheap insurance.

#Execute the upgrade

Follow the Standard Upgrade Steps above. The init container will run the swap automatically the first time a smart-doc pod restarts on the new version.

#Verify the upgrade

Tail the init container log and confirm the swap completed:

kubectl -n cpaas-system logs -l app=smart-doc -c init-database | grep '\[upgrade\]'

A successful swap prints lines like:

[upgrade] swap docvec_mpnet_acp_4_1_1215 (in docvec_sys_kb) -> dump docvec_gte_acp_4_1_20260508.dump; final name=docvec_gte_cs2000_20260410
[upgrade] 003_data_swap_docvec_mpnet_acp_4_1_1215_20260508-gte-acp-4-x applied.

A re-roll after the swap has completed prints no [upgrade] line at all — the rule scan finds no matching collection (the OLD name was renamed to pgconnect.pgCollectionName during step 6) and the swap block exits silently. Absence of a log line on subsequent rolls is the expected post-swap state.

The [upgrade] ... already applied, skipping. line is reserved for a recovery scenario: a kb_swap_state row exists for a stamp that has already been applied (e.g., a pod was killed after the stamp landed but before the inflight row was cleared). It is not the normal idempotent re-roll output.

Once the smart-doc pod becomes Ready, run a representative question through the chat UI to confirm answers are grounded in the new corpus.

#Special case: you maintain a custom knowledge base

If you previously followed Build a Custom Knowledge Base on the v1.3.x mpnet model, the vectors in your custom collection are not compatible with the v1.4.0 server. You must:

1. Before the upgrade: rebuild your custom KB with gte-multilingual-base (see the linked guide).
2. Replace the bundled acpKbUpgradeRules with a single rule for your custom collection:

   smartdoc:
     acpKbDataVersion: "20260512-custom-gte"  # bump to re-arm the swap
     acpKbUpgradeRules: |
       <your_mpnet_collection_name>  <your-gte-collection-name>.dump  <your-gte-collection-name>
   The bundled ACP rules don't apply here — a custom-KB deployment already replaced those collections in v1.3.x, so the bundled OLD names won't match. Leaving them in the rule list is harmless but cluttered.
3. Apply the upgrade.

NOTE: The init container processes only the first rule whose OLD collection is found in docvec_sys_kb per run, then exits the swap block. The DROP-and-restore wipes the entire langchain_pg_collection table, so the chart only supports one system-KB collection at a time. If you need to keep both your custom corpus and the bundled ACP corpus, ingest them in the same prepare run (see the build-custom-kb guide's Caveats) and ship a single combined dump.

If you skip step 1, the chart will still upgrade, but retrieval against the stale custom collection will return zero hits and answers will fall back to "I don't have enough information".

#Upgrading from v1.2.0 to v1.2.1 (Special Case)

IMPORTANT: Upgrading from v1.2.0 to v1.2.1 will cause the knowledge base to be re-initialized. You must manually back up and restore your database to prevent data loss.

#Step 1: Backup Knowledge Base

Before performing the upgrade, execute the following commands:

# Get the PostgreSQL pod name (if using the built-in database)
kubectl -n cpaas-system get pod | grep postgre-vec

# Dump the database to a file
kubectl -n cpaas-system exec -it <postgre-vec-xxx> -- pg_dump -U postgres -d <your-database-name> -F c -f /tmp/hyperflux_backup.dump

# Copy the dump file to your local machine
kubectl -n cpaas-system cp <postgre-vec-xxx>:/tmp/hyperflux_backup.dump ./hyperflux_backup.dump

#Step 2: Execute Upgrade

Follow the Standard Upgrade Steps described above to upgrade the plugin version through the ACP console.

#Step 3: Restore Knowledge Base

After the upgrade is complete, restore your data:

# Get the new PostgreSQL pod name
kubectl -n cpaas-system get pod | grep postgre-vec

# Copy the backup dump file back to the pod
kubectl -n cpaas-system cp ./hyperflux_backup.dump <postgre-vec-xxx>:/tmp/hyperflux_backup.dump

# Restore the database from the dump file
kubectl -n cpaas-system exec -it <postgre-vec-xxx> -- pg_restore -U postgres -d <your-database-name> /tmp/hyperflux_backup.dump

# (Optional) Update configuration if your database/collection name changed
kubectl -n cpaas-system edit configmap smart-doc-config
# Update `PG_CONN_DB` and `PG_COLLECTION_NAME` fields if necessary.
# (Env-var rename: `PG_CONN_DB` was split into `PG_SYS_KB_DB` / `PG_HISTORY_DB` /
#  `PG_USER_KB_DB` in later versions. For a v1.4.x upgrade, see the embedding-switch
#  section above instead — the chart handles the data swap automatically.)

Wait for the Alauda Hyperflux pods to restart and verify that the knowledge base has been restored successfully.