replit-upgrade-migration

Upgrade Replit Nix channels, migrate between database types, and update deployment targets. Use when upgrading Nix channel versions, migrating from Replit DB to PostgreSQL, switching deployment types, or updating system dependencies. Trigger with phrases like "upgrade replit", "replit nix upgrade", "migrate replit database", "replit version update", "replit channel update".

仓库: jeremylongshore/claude-code-plugins-plus-skills
最近来源活动: 2026年7月17日 22:18
检测到的 SKILL.md 语言: 英语
星标: 2,604
分支: 378

安装方式

默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。

检查来源文件

决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。

返回搜索返回安装

name	replit-upgrade-migration
description	Upgrade Replit Nix channels, migrate between database types, and update deployment targets. Use when upgrading Nix channel versions, migrating from Replit DB to PostgreSQL, switching deployment types, or updating system dependencies. Trigger with phrases like "upgrade replit", "replit nix upgrade", "migrate replit database", "replit version update", "replit channel update".
allowed-tools	Read, Write, Edit, Bash(npm:), Bash(pip:)
version	1.12.0
license	MIT
author	Jeremy Longshore <jeremy@intentsolutions.io>
tags	["saas","replit","migration","nix","upgrade"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

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());

# .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"

// 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}`);
  }
}

## 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	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