Migration Guide

Upgrade instructions and breaking changes for Z3rno releases.

Migration Guide

This guide covers upgrade steps and breaking changes between Z3rno releases.

v0.0.1 to v0.1.0

v0.1.0 has not been released yet. This section will be updated with specific breaking changes and migration steps when the release is finalized.

Database Migration

Z3rno uses Alembic for database schema migrations. After upgrading the server, run:

# If using Docker Compose
docker compose exec server alembic upgrade head

# If running directly
cd z3rno-server
alembic upgrade head

Always back up your database before running migrations in production.

SDK Upgrade

Update the Python SDK:

pip install --upgrade z3rno
# or
uv pip install --upgrade z3rno

Update the TypeScript SDK:

npm install z3rno@latest
# or
pnpm update z3rno

Breaking Changes

Breaking changes follow this format:

Change	Before	After	Migration
Example: method rename	client.search()	client.recall()	Find and replace in your codebase

Subscribe to the GitHub releases to be notified of new versions and breaking changes.

Helm Chart Upgrade

If you deploy via Helm:

# Update the chart repository
helm repo update

# Review changes before applying
helm diff upgrade z3rno z3rno/z3rno -f values.yaml

# Apply the upgrade
helm upgrade z3rno z3rno/z3rno -f values.yaml

Configuration Changes

Check the Configuration Reference for any new or renamed environment variables between versions.

General Upgrade Checklist

1. Read the release notes for your target version
2. Back up your database
3. Update the server (Docker image or binary)
4. Run database migrations (alembic upgrade head)
5. Update SDK versions in your applications
6. Test in a staging environment before production
7. Monitor logs and metrics after the upgrade