# How to Update OmniRoute to the Latest Version: A Step-by-Step Guide

> Easily update OmniRoute to the latest version. Follow our step-by-step guide to pull the release, reinstall dependencies, run migrations, and restart the service for a seamless update.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-08-02

---

**To update OmniRoute to the latest version, pull the current release branch, reinstall Node dependencies with `npm ci`, run database migrations via [`src/lib/db/migrationRunner.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/migrationRunner.ts), and restart the service.**

Upgrading OmniRoute ensures you receive the newest provider integrations, bug fixes, and security patches. The project maintains a **release-branch workflow** centered on the `release/v3.8.50` branch as its current stable line. This guide walks through the exact commands and files involved in the update process according to the `diegosouzapw/OmniRoute` source code.

## Update OmniRoute in Four Steps

### Step 1: Pull the Latest Release Branch

Fetch the remote repository and switch to the newest stable branch. This brings in updated source code, new provider entries, and any critical fixes.

```bash
git fetch origin
git checkout release/v3.8.50
git pull origin release/v3.8.50

```

If you track tags instead of branches, checkout the specific `release/vX.Y.Z` tag that marks the latest stable release.

### Step 2: Refresh Node Dependencies

OmniRoute targets **Node 22 or 24** and uses **ES modules**. Run `npm ci` to install exact versions from [`package-lock.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package-lock.json), ensuring reproducible builds.

```bash
npm ci

```

The [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json) in the repository root defines the engine requirements and dependency tree. Respecting these constraints prevents runtime module errors.

### Step 3: Apply Database Migrations

Each release may add or modify SQLite tables. Execute the migration runner to apply pending schema changes safely within transactions.

```bash
node --import tsx/esm src/lib/db/migrationRunner.ts

```

This script reads SQL files from `db/migrations/` (for example, [`001_initial_schema.sql`](https://github.com/diegosouzapw/OmniRoute/blob/main/001_initial_schema.sql)) and updates the local database schema. All migrations run inside transactions to prevent partial state.

### Step 4: Restart the Service

Once code and database are synchronized, restart your deployment:

```bash
npm run start          # for the Next.js API server

# or

npm run electron:build # for the Electron desktop wrapper

```

## Key Files Involved in OmniRoute Updates

| File | Purpose |
|------|---------|
| [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json) | Declares Node version, scripts, and exact dependency versions |
| [`src/lib/db/migrationRunner.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/migrationRunner.ts) | Entry point that sequentially applies SQL migration files |
| `db/migrations/` | Directory containing versioned migration scripts |
| [`docs/ops/RELEASE_CHECKLIST.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/RELEASE_CHECKLIST.md) | Official step-by-step guide used by maintainers |
| `src/app/api/v1/` | Core Next.js API routes affected by provider or schema changes |

## Verify Your Update

After restarting, confirm the deployment health through these checks:

- API endpoints under `src/app/api/v1/` respond correctly
- Database version matches the latest migration timestamp
- Provider integrations listed in the newest release load without errors

The **Release Checklist** at [`docs/ops/RELEASE_CHECKLIST.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/RELEASE_CHECKLIST.md) documents the exact order of operations, required environment variables, and post-upgrade validation steps used by the maintainers for every release.

## Summary

- **Pull** the `release/v3.8.50` branch (or latest tag) to receive source updates
- **Run `npm ci`** to install locked dependencies for Node 22/24
- **Execute migrations** with `node --import tsx/esm src/lib/db/migrationRunner.ts`
- **Restart** via `npm run start` or `npm run electron:build`
- **Validate** against the Release Checklist to confirm successful upgrade

## Frequently Asked Questions

### How do I know which release branch is current?

Check the default branch on GitHub or the latest tag matching `release/vX.Y.Z`. The `release/v3.8.50` branch is the current stable line as documented in the repository.

### What happens if I skip database migrations?

Skipping migrations leaves your SQLite schema out of sync with the codebase, causing runtime errors when new code references missing tables or columns. Always run [`src/lib/db/migrationRunner.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/migrationRunner.ts) after pulling updates.

### Can I use `npm install` instead of `npm ci`?

`npm ci` is strongly preferred because it strictly follows [`package-lock.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package-lock.json) for reproducible installs. `npm install` may update dependency versions beyond what the release tested, introducing compatibility risks.

### How do I update the Electron desktop version specifically?

Pull the latest branch, run `npm ci`, apply migrations, then execute `npm run electron:build` rather than `npm run start`. The build process packages the updated Next.js API and frontend into the desktop wrapper.