Upgrading

Startup can run Teldrive, River, and RiverPro migrations. Back up PostgreSQL before the new version initializes.

Before upgrading

Migrating from v1

Legacy bots with a zero ID have their ID recovered from the numeric prefix of their BotFather token (bot_id:secret). Tokens are preserved and encrypted with the v2 security.data-key; no Telegram login is needed for this recovery.

Migration preserves existing bots as enabled but does not reconfigure their Telegram channel permissions. After logging in, open Settings → Telegram bots and choose Provision on a bot to verify its token and repair its access to your registered channels. Follow the task in Tasks. Telegram can temporarily restrict admin changes after a fresh login; the task retries these restrictions every hour, for up to 48 hours.

Upgrade checklist

1. Read release notes.
2. Record the current version.
3. Back up PostgreSQL.
4. Verify you still have security.data-key and content-encryption keys.
5. Keep the previous image/binary available.

Use a pinned release tag:

image: ghcr.io/tgdrive/teldrive:X.Y.Z

Compose

docker compose pull teldrive
docker compose run --rm teldrive check
docker compose up -d teldrive
docker compose logs --tail=250 teldrive

check can run migrations, so the backup must exist before it.

Binary install

Keep old and new binaries side by side:

/usr/local/lib/teldrive/teldrive-OLD
/usr/local/lib/teldrive/teldrive-X.Y.Z

Validate before switching:

/usr/local/lib/teldrive/teldrive-X.Y.Z check --config /etc/teldrive/config.toml

Smoke test

Verify:

• /health/live and /health/ready;
• login/session refresh;
• listing, upload, download, rename/move/trash/restore;
• tasks;
• shares, rclone, and bots if used.

Rollback

An older binary may not work against a newer migrated schema. A full rollback may require:

1. stop the new version;
2. restore the pre-upgrade PostgreSQL backup;
3. restore the previous binary/image and matching configuration;
4. run teldrive check before serving traffic.

For multi-instance deployments, coordinate the rollout and avoid unsupported mixed-version operation.

See Backup and restore.