replit-upgrade-migration

Replit Upgrade & Migration

Current State

!cat .replit 2>/dev/null | head -15 || echo 'No .replit found' !cat replit.nix 2>/dev/null || echo 'No replit.nix found'

Overview

Guide for upgrading Replit environments: Nix channel updates, package version bumps, database migrations (KV to PostgreSQL, dev to prod), deployment type changes, and Node.js/Python runtime upgrades.

Prerequisites

• Existing Replit App with .replit and replit.nix
• Git version control (recommended)
• Backup of critical data before migration

Instructions

Step 1: Upgrade Nix Channel

Nix channels determine available package versions. Upgrade to get newer runtimes.

# .replit — before
[nix]
channel = "stable-23_05"

# .replit — after (2024-2025 stable)
[nix]
channel = "stable-24_05"

After changing the channel, reload the shell (exit Shell tab and re-enter). Then verify:

node --version     # Should show newer version
python3 --version  # Should show newer version

Step 2: Upgrade Node.js or Python Runtime

# replit.nix — update runtime packages

# Before (Node 18)
{ pkgs }: {
  deps = [
    pkgs.nodejs-18_x
    pkgs.nodePackages.typescript
  ];
}

# After (Node 20)
{ pkgs }: {
  deps = [
    pkgs.nodejs-20_x
    pkgs.nodePackages.typescript-language-server
    pkgs.nodePackages.pnpm
  ];
}

# .replit — update modules to match
modules = ["nodejs-20:v8-20230920-bd784b9"]

Verify after upgrade:

node --version         # v20.x.x
npm --version          # 10.x.x
npm test               # Run tests to catch breaking changes

Step 3: Migrate from Replit KV to PostgreSQL

When your app outgrows the 50 MiB KV database limit:

// scripts/migrate-kv-to-postgres.ts
import Database from '@replit/database';
import { Pool } from 'pg';

const kv = new Database();
const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  ssl: { rejectUnauthorized: false },
});

async function migrate() {
  // Create table
  await pool.query(`
    CREATE TABLE IF NOT EXISTS kv_data (
      key TEXT PRIMARY KEY,
      value JSONB NOT NULL,
      migrated_at TIMESTAMPTZ DEFAULT NOW()
    )
  `);

  // Read all KV entries
  const keys = await kv.list();
  console.log(`Migrating ${keys.length} keys...`);

  let migrated = 0;
  let errors = 0;

  for (const key of keys) {
    try {
      const value = await kv.get(key);
      await pool.query(
        'INSERT INTO kv_data (key, value) VALUES ($1, $2) ON CONFLICT (key) DO UPDATE SET value = $2',
        [key, JSON.stringify(value)]
      );
      migrated++;
    } catch (err: any) {
      console.error(`Failed to migrate key "${key}": ${err.message}`);
      errors++;
    }
  }

  console.log(`Migration complete: ${migrated} migrated, ${errors} errors`);
}

migrate().then(() => pool.end());

Step 4: Switch Deployment Type

# .replit — change deployment target

# From Autoscale (scales to zero):
[deployment]
deploymentTarget = "autoscale"
run = ["sh", "-c", "npm start"]

# To Reserved VM (always-on):
[deployment]
deploymentTarget = "cloudrun"
run = ["sh", "-c", "npm start"]

# To Static (frontend only):
[deployment]
deploymentTarget = "static"
publicDir = "dist"

After changing: click "Deploy" to create a new deployment with the new type.

Step 5: Migrate Large Files to Object Storage

// Move large values from KV to Object Storage
import Database from '@replit/database';
import { Client } from '@replit/object-storage';

const kv = new Database();
const storage = new Client();

async function migrateToObjectStorage(prefix: string) {
  const keys = await kv.list(prefix);

  for (const key of keys) {
    const value = await kv.get(key);
    const content = typeof value === 'string' ? value : JSON.stringify(value);

    await storage.uploadFromText(`migrated/${key}`, content);
    await kv.delete(key);
    console.log(`Migrated: ${key}`);
  }
}

Step 6: Pre-Migration Checklist

## Before Any Upgrade
- [ ] Git commit current working state
- [ ] Back up Replit KV data: export all keys to JSON file
- [ ] Back up PostgreSQL: pg_dump or Replit snapshot
- [ ] Note current deployment URL and settings
- [ ] Run full test suite: npm test
- [ ] Document current .replit and replit.nix content

## After Upgrade
- [ ] Reload shell (exit and re-enter Shell tab)
- [ ] Verify runtime versions
- [ ] npm install / pip install (rebuild packages for new runtime)
- [ ] Run full test suite
- [ ] Test in Workspace Webview
- [ ] Deploy and verify production health check
- [ ] Monitor for 24 hours for regressions

Error Handling

Error	Cause	Solution
Package not found after channel upgrade	Package renamed or removed	Search Nix packages: nix-env -qaP | grep name
node-gyp build failure	Native addon incompatible	Update the addon or add Nix system deps
PostgreSQL connection refused	Pool not using SSL	Add ssl: { rejectUnauthorized: false }
Old deployment still running	Didn't redeploy	Click "Deploy" to apply new config

Resources

• Replit App Configuration
• Nix on Replit
• PostgreSQL on Replit
• Deployment Types

Next Steps

For CI integration during upgrades, see replit-ci-integration.