WordPress-databasemigrering: WP-CLI, backup og serialiserte data

Er flyttingen samtidig en ombygging, kan du lese mer om migrering til Astro og Next.js.

Den vanligste situasjonen er velkjent: siden er bygget på et utviklingsdomene som dev.kunde.no og skal i produksjon på kunde.no. Det er nettopp der en rask SQL-erstatning gjør mest skade.

#1. Hvorfor SQL REPLACE ødelegger serialiserte data i WordPress

WordPress lagrer mange innstillinger, widgetoppsett og temaegenskaper i tabellen wp_options (og i wp_postmeta, wp_usermeta og wp_termmeta) som serialiserte arrays eller objekter. En serialisert PHP-streng angir datatypen og lengden i byte for hver strengverdi.

#Hvordan en serialisert PHP-streng lagrer lengden

Se på denne serialiserte strengen, som lagrer en domeneinnstilling: s:22:"https://old-domain.com";

I denne strukturen:

• s angir at typen er en streng.
• 22 sier at verdien er nøyaktig 22 byte lang.
• "https://old-domain.com" er selve verdien.

Et array med temainnstillinger og en logo-URL ser slik ut etter serialisering: a:2:{s:11:"theme_color";s:4:"blue";s:8:"logo_url";s:28:"http://dev.site.com/logo.png";}

Hver nøkkel og hver verdi har sin lengde: theme_color er 11 byte, logo_url er 8, og URL-en er 28.

#Hvorfor feil strenglengde får WordPress til å forkaste innstillingen

Kjører du en vanlig SQL REPLACE for å bytte domene, for eksempel fra old-domain.com til my-new-company-domain.com, skriver spørringen om verdien, men lar lengdemarkøren stå: s:22:"https://my-new-company-domain.com";

Den nye verdien er 33 byte lang, men markøren sier fortsatt 22. Når WordPress leser raden, sendes den gjennom maybe_unserialize(). PHP leser 22 byte (https://my-new-company), venter et avsluttende anførselstegn, finner en bindestrek i stedet, og unserialize() returnerer false. Innstillingen temaet eller utvidelsen forventet kommer tilbake som false, så temaet faller tilbake til standardverdiene, widgets forsvinner og noen utvidelser ber om lisensnøklene sine på nytt.

Det samme skjer motsatt vei. Erstatter du dev.site.com med site.com i logoeksempelet, får du en URL på 24 byte under en markør som fortsatt sier 28, og hele arrayet blir uleselig, ikke bare logoen.

En erstatning overlever en vanlig SQL REPLACE bare når den gamle og den nye strengen har nøyaktig samme lengde, og det er en tilfeldighet, ikke en metode.

#Serialiserte objekter og __PHP_Incomplete_Class

Hvis en serialisert streng representerer et objekt: O:31:"WPPoland\Database\CustomObject":1:{...}

kobler PHP det lagrede klassenavnet til en klasse som er lastet under kjøring. Er klassen ikke lastet når verdien deserialiseres (for eksempel fordi utvidelsen som definerer den er deaktivert, eller fordi migreringen ga navnerommet nytt navn), lager PHP en plassholder av typen __PHP_Incomplete_Class i stedet. Metodene dens kan ikke kalles, og kode som forventer det ekte objektet feiler. Verktøy som forstår serialisering, deserialiserer og serialiserer slike verdier på nytt; de gir ikke klasser nye navn.

#2. Hvordan bytte WordPress-domene med WP-CLI

WP-CLI har kommandoen search-replace. Den offisielle referansen sier at den “håndterer serialiserte PHP-data på en intelligent måte og endrer ikke verdiene til primærnøkler” (WP-CLI-kommandoreferansen, egen oversettelse). Dette er standardmetoden for å oppdatere URL-er i WordPress-databasen.

#Trinn 1: eksporter en backup av databasen

Før du rører en eneste rad, eksporterer du en fullstendig SQL-backup:

# Eksporter databasen til en SQL-fil
wp db export backup-pre-domain-migration.sql

Sjekk samtidig at PHP-versjonen på den nye serveren samsvarer med den gamle, slik at utvidelser og temaet oppfører seg likt etter flyttingen.

#Trinn 2: kjør search-replace som prøvekjøring

Kjør kommandoen med --dry-run først. Ifølge referansen vil den “kjøre hele søk og erstatt-operasjonen og vise en rapport, men ikke lagre endringer i databasen” (egen oversettelse).

# Prøvekjøring: rapporter hva som ville blitt endret, skriv ingenting
wp search-replace 'https://old-domain.com' 'https://new-domain.com' --all-tables-with-prefix --skip-columns=guid --dry-run

Rapporten er en tabell med kolonnene Table, Column, Replacements og Type, én rad per kolonne som inneholder treff, etterfulgt av en linje som Success: 245 replacements to be made. (tallene avhenger helt av nettstedet ditt). Kolonnen Type viser SQL eller PHP: hvilken motor som behandlet den kolonnen.

#Hva —precise faktisk gjør

Referansen beskriver --precise slik: “Tving bruk av PHP (i stedet for SQL) for alle kolonner” (egen oversettelse). Som standard “bruker kommandoen raske SQL-spørringer, men bytter automatisk til PHP for kolonner som inneholder serialiserte data” (egen oversettelse). Du trenger altså ikke --precise for å beskytte serialiserte verdier; WP-CLI oppdager dem allerede. Bruk --precise når du vil ha PHP-behandling overalt, for eksempel når du ikke stoler på gjenkjenningen i en kolonne med uvanlig innhold, og godta at kjøringen tar lengre tid.

#Hvilke tabeller: standard, —all-tables og —all-tables-with-prefix

Som standard bruker kommandoen bare tabellene som er registrert i objektet $wpdb, altså kjernetabellene pluss utvidelsestabeller som er registrert der. To flagg utvider omfanget:

Mange utvidelser lager egne tabeller uten å registrere dem i $wpdb, så en standardkjøring kan overse URL-er som er lagret der. --all-tables-with-prefix er den tryggere måten å ta dem med på. Bruk --all-tables bare når databasen tilhører dette ene nettstedet: deler to WordPress-installasjoner database med ulike prefikser, skriver --all-tables om URL-ene til det andre nettstedet også.

#Hvorfor du bør hoppe over guid-kolonnen

WordPress-dokumentasjonen om flytting av nettsted er utvetydig om kolonnen guid i wp_posts: “Endre aldri, under noen omstendigheter, innholdet i GUID-kolonnen” (Moving WordPress, developer.wordpress.org, egen oversettelse). Samme side forklarer at feedlesere bruker GUID til å vite om de allerede har vist et innlegg, så “endrer du GUID, vil mange feedlesere plutselig vise innholdet ditt” på nytt (egen oversettelse). WP-CLI-referansen bruker nettopp dette tilfellet som eksempel på å hoppe over en kolonne: --skip-columns=guid.

#Trinn 3: kjør erstatningen

Ser rapporten fra prøvekjøringen riktig ut, kjører du samme kommando uten --dry-run. --skip-columns godtar også navn med tabell foran (table.column), og --skip-tables utelater hele tabeller, noe som hjelper på store databaser med loggtabeller:

# Kjør, behold GUID-er, ta med uregistrerte utvidelsestabeller med nettstedets prefiks
wp search-replace 'https://old-domain.com' 'https://new-domain.com' --all-tables-with-prefix --skip-columns=guid

Vil du lage en migrert SQL-fil uten å røre den aktive databasen, bruker du --export, som skriver “transformerte data som en SQL-fil i stedet for å lagre erstatningene i databasen” (egen oversettelse):

wp search-replace 'https://old-domain.com' 'https://new-domain.com' --skip-columns=guid --export=migrated.sql

#Trinn 4: rett opp blandet innhold etter overgang til HTTPS

Flyttes nettstedet samtidig fra HTTP til HTTPS, kjører du en ekstra runde for hardkodede usikre referanser:

# Erstatt gamle HTTP-lenker med HTTPS-lenker på det nye domenet
wp search-replace 'http://old-domain.com' 'https://new-domain.com' --all-tables-with-prefix --skip-columns=guid

#Trinn 5: tøm permalenker og objektcache

Etter en vellykket kjøring skriver WP-CLI selv ut Please remember to flush your persistent object cache with wp cache flush når en objektcache er aktiv. Gjør det, generer omskrivingsreglene på nytt og bekreft de lagrede URL-ene:

wp rewrite flush
wp cache flush
wp option get home
wp option get siteurl

Uten WP-CLI gir det samme resultat å åpne Innstillinger > Permalenker og klikke “Lagre endringer”. Bruker du Redis eller en sidecache, tømmer du den også.

#Domenebytte i WordPress multisite

På multisite legger du til --network for å gå gjennom “alle tabellene som er registrert i $wpdb i en multisite-installasjon” (egen oversettelse). Moving WordPress-veiledningen legger til manuelle kontroller som kommandoen ikke erstatter: “gå uansett manuelt gjennom både wp_site og wp_blogs” (egen oversettelse), og gå gjennom hver options-tabell per nettsted (wp_2_options, wp_3_options og så videre) for verdiene home, siteurl og fileupload_url. Kolonnen domain i disse nettverkstabellene inneholder bare vertsnavnet, så et søk etter https://old-domain.com treffer den ikke. Oppdater også nettverkskonstantene som skjermen for nettverksoppsett ba deg legge til i wp-config.php. Veiledningens egne instruksjoner for å endre nettstedets URL “gjelder bare enkeltinstallasjoner av WordPress” (egen oversettelse).

#3. Sett WP_HOME og WP_SITEURL i wp-config.php

Inneholder databasen fortsatt det gamle domenet, men du må laste nettstedet under det nye, kan du overstyre begge verdiene i wp-config.php. Dokumentasjonen for wp-config.php sier at WP_SITEURL “overstyrer verdien for siteurl i tabellen wp_options” og at WP_HOME overstyrer verdien for home, “men endrer den ikke i databasen” (egen oversettelse). Verdien home er adressen besøkende skriver inn; siteurl er adressen der kjernefilene ligger. Begge bør inneholde https:// og ikke ha skråstrek på slutten.

#Midlertidige URL-overstyringer i wp-config.php på staging

Overstyringen endrer ruting og URL-er til ressurser, ikke de lagrede radene. Lenker i innleggsinnhold, innleggsmetadata og innstillinger for utvidelser peker fortsatt til det gamle domenet til du kjører search-replace. Dokumentasjonen advarer også om at “URL-en går tilbake til den gamle verdien i databasen hvis denne linjen noen gang fjernes fra wp-config” (egen oversettelse). Bruk konstantene som en vei inn i dashbordet, og kjør hele erstatningen før lansering:

// Overstyr de lagrede URL-ene mens databasen fortsatt har det gamle domenet
define( 'WP_HOME', 'https://new-domain.com' );
define( 'WP_SITEURL', 'https://new-domain.com' );

Så lenge konstantene er definert, kan de to URL-feltene under Innstillinger > Generelt ikke redigeres, fordi verdiene er hardkodet.

#Sett nettstedets URL ut fra gjeldende vertsnavn

Dokumentasjonen viser en dynamisk variant basert på $_SERVER['HTTP_HOST'], nyttig når samme kodebase kjører lokalt, på staging og i produksjon:

define( 'WP_HOME', 'https://' . $_SERVER['HTTP_HOST'] );
define( 'WP_SITEURL', 'https://' . $_SERVER['HTTP_HOST'] );

Den kommer med en advarsel: HTTP_HOST “opprettes dynamisk av PHP ut fra verdien i HTTP HOST-headeren i forespørselen, og kan dermed åpne for sårbarheter med filinkludering” (egen oversettelse). Når Apache kjører med UseCanonicalName On, kommer SERVER_NAME i stedet fra serverkonfigurasjonen, og dokumentasjonen kaller det det tryggere valget i det tilfellet. På en offentlig produksjonsserver bør du foretrekke en fast verdi eller en tillatelsesliste over verter.

#Andre måter å endre nettstedets URL på: wp option update, RELOCATE og functions.php

WordPress-veiledningen Moving WordPress lister flere måter å endre de to lagrede verdiene på:

• WP-CLI: wp option update home 'https://example.com' og wp option update siteurl 'https://example.com'. Dette skriver verdiene til wp_options og endrer ingenting annet.
• functions.php: legg midlertidig til update_option( 'siteurl', ... ) og update_option( 'home', ... ) i det aktive temaet, last nettstedet noen ganger og fjern deretter koden. Veiledningen sier rett ut: “Ikke la denne koden ligge i functions.php” (egen oversettelse).
• RELOCATE: legg til define( 'RELOCATE', true ); i wp-config.php, logg inn via wp-login.php på den nye adressen, sjekk begge feltene under Innstillinger > Generelt og fjern linjen. Veiledningen kaller det usikkert å la den stå, og påpeker at den bare oppdaterer nettstedets URL, så andre referanser trenger fortsatt search-replace.
• Direkte redigering i databasen: etter en backup redigerer du radene siteurl og home i options-tabellen i phpMyAdmin (tabellprefikset kan være et annet enn wp_).

Ingen av disse rører URL-er i innholdet, og derfor er search-replace i del 2 fortsatt hovedsteget.

#4. Search-replace uten SSH: Better Search Replace og Search Replace DB

WordPress-veiledningen for migrering nevner to alternativer til WP-CLI for verter uten skalltilgang.

#Utvidelsen Better Search Replace

Når du fortsatt kommer inn i dashbordet, lister utvidelsen Better Search Replace “støtte for serialisering i alle tabeller” blant funksjonene sine (egen oversettelse) og legger siden sin under menyen Verktøy:

1. Installer og aktiver utvidelsen, og åpne Verktøy > Better Search Replace.
2. Skriv den gamle URL-en i søkefeltet og den nye i erstatningsfeltet.
3. Velg tabellene som skal behandles.
4. La prøvekjøringen være slått på i første runde (det har vært standard siden versjon 1.0.1), og se hvor mange felt som ville blitt endret.
5. Slå av prøvekjøringen og kjør på nytt.

Den kjører i PHP-forespørsler, så på svært store tabeller kan den treffe vertens grense for kjøretid, og den hjelper ikke når dashbordet allerede viderekobler til det gamle domenet.

#Skriptet Search Replace DB fra interconnect/it

Når verken WP-CLI eller dashbordet er tilgjengelig, viser veiledningen til skriptet fra interconnect/it “for å trygt endre alle forekomster av det gamle domenet eller den gamle stien til den nye” (egen oversettelse), med advarselen om å “bare bruke dette alternativet hvis du er komfortabel med databaseadministrasjon” (egen oversettelse). Last det opp til en mappe med tilfeldig navn, kjør prøvekjøringen og deretter erstatningen, og slett mappen rett etterpå: alle som finner den, kan lese og skrive om databasen.

#5. PHP-skript for search-replace i serialiserte data

Trenger du erstatningen i din egen PHP-kode (for eksempel i en deploy-pipeline uten WP-CLI), går denne klassen rekursivt gjennom arrays og objekter, erstatter strenger og serialiserer på nytt, slik at PHP selv regner ut lengdemarkørene.

Opprett den som scripts/class-serialization-replace.php:

<?php
declare(strict_types=1);

namespace WPPoland\Database\Migrator;

class SerializationAwareReplacer {

    private string $search;
    private string $replace;

    public function __construct( string $search, string $replace ) {
        $this->search  = $search;
        $this->replace = $replace;
    }

    /**
     * Inngangspunkt for rekursivt søk og erstatt av strenger i data.
     */
    public function process( $data ) {
        if ( is_string( $data ) ) {
            // Sjekk om strengen er serialisert
            if ( $this->is_serialized_string( $data ) ) {
                $unserialized = unserialize( $data );
                if ( false !== $unserialized ) {
                    return serialize( $this->process( $unserialized ) );
                }
            }
            return str_replace( $this->search, $this->replace, $data );
        }

        if ( is_array( $data ) ) {
            $cleaned = [];
            foreach ( $data as $key => $value ) {
                $cleaned[ $key ] = $this->process( $value );
            }
            return $cleaned;
        }

        if ( is_object( $data ) ) {
            $cleaned = clone $data;
            foreach ( get_object_vars( $data ) as $key => $value ) {
                $cleaned->$key = $this->process( $value );
            }
            return $cleaned;
        }

        return $data;
    }

    /**
     * Sjekker om en streng er serialisert.
     */
    private function is_serialized_string( string $string ): bool {
        $string = trim( $string );
        if ( 'N;' === $string ) {
            return true;
        }
        if ( strlen( $string ) < 4 ) {
            return false;
        }
        if ( ':' !== $string[1] ) {
            return false;
        }
        $last_char = substr( $string, -1 );
        if ( ';' !== $last_char && '}' !== $last_char ) {
            return false;
        }
        $token = $string[0];
        switch ( $token ) {
            case 's':
                if ( '"' !== substr( $string, -2, 1 ) ) {
                    return false;
                }
                return true;
            case 'a':
            case 'O':
                return (bool) preg_match( "/^{$token}:[0-9]+:/s", $string );
            case 'b':
            case 'i':
            case 'd':
                return (bool) preg_match( "/^{$token}:[0-9.E-]+;\$/", $string );
        }
        return false;
    }
}

get_object_vars() returnerer egenskapene som er tilgjengelige fra kallende omfang, her altså bare de offentlige, så private og beskyttede egenskaper i objekter passerer uendret. Inne i WordPress gjør kjernefunksjonene is_serialized() og maybe_unserialize() gjenkjenningen for deg; WP-CLI er fortsatt det testede alternativet.

#6. Viderekoble det gamle domenet med 301-regler

Googles dokumentasjon om flytting av nettsted med URL-endringer ber om permanente viderekoblinger på serversiden, “som 301 og 308” (egen oversettelse), fra hver gammel URL til den tilsvarende nye. Dokumentasjonen om viderekoblinger forklarer at for disse permanente kodene “bruker indekseringsprosessen viderekoblingen som et signal om at målet for viderekoblingen bør være kanonisk” (egen oversettelse); midlertidige koder (302, 303, 307) sender ikke det signalet.

#Nginx-viderekobling med 301 som beholder forespørsels-URI-en

Behold stien og spørrestrengen med $request_uri. Googles veiledning for flytting av nettsted fraråder å sende mange gamle URL-er til én urelatert side, som den nye forsiden; en kobling side til side er det regelen nedenfor gir:

server {
    listen 80;
    listen 443 ssl;
    server_name old-domain.com www.old-domain.com;

    # ssl_certificate og ssl_certificate_key for det gamle domenet legges her

    # Permanent viderekobling som beholder sti og spørrestreng
    return 301 https://new-domain.com$request_uri;
}

Det gamle domenet trenger fortsatt et gyldig sertifikat: en HTTPS-forespørsel mot det feiler under TLS-håndtrykket før Nginx rekker å sende viderekoblingen.

#Apache .htaccess-viderekobling med 301 til nytt domene

Legg disse reglene øverst i .htaccess på det gamle domenet:

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteCond %{HTTP_HOST} ^(?:www\.)?old-domain\.com$ [NC]
  RewriteRule ^(.*)$ https://new-domain.com/$1 [R=301,L]
</IfModule>

Dokumentasjonen for mod_rewrite i Apache sier at “spørrestrengen som standard sendes videre uendret” (egen oversettelse), så ?page=2 overlever viderekoblingen.

#Viderekobling i kanten med Cloudflare Worker

Går det gamle domenet gjennom Cloudflare som proxy, kan en Worker svare med viderekoblingen uten å nå opprinnelsesserveren. Dette følger modulsyntaksen i Cloudflares eget eksempel på viderekobling:

export default {
  async fetch(request) {
    const base = "https://new-domain.com";
    const { pathname, search } = new URL(request.url);
    return Response.redirect(`${base}${pathname}${search}`, 301);
  },
};

#7. Sjekkliste for SEO-migrering og oppsett i Google Search Console

#Slik bruker du verktøyet for adressebytte i Search Console

Googles hjelpeside for verktøyet for adressebytte setter disse vilkårene:

1. Eierskap: “Du må være eier av både den gamle og den nye egenskapen i Search Console” (egen oversettelse).
2. Bare domenenivå: verktøyet “kan bare brukes på egenskaper på domenenivå”, og det “flytter ingen underdomener under det angitte domenet (inkludert www)” (egen oversettelse). Send egne forespørsler for www- og ikke-www-varianter som er i bruk eller har vært brukt.
3. Viderekobling først: sett opp en 301-viderekobling fra den gamle forsiden til den nye forsiden, og fra de andre sidene. Verktøyet sjekker at du eier begge nettstedene og at noen sider returnerer 301-viderekoblinger.
4. Kjør det: åpne den gamle egenskapen, gå til Innstillinger, velg adressebytte og velg den nye egenskapen.
5. Nettstedskart: send inn det nye XML-nettstedskartet. Googles veiledning for flytting av nettsted sier at advarsler om URL-er som viderekobles i det gamle nettstedskartet, er forventet mens begge er sendt inn.

Verktøyet trengs ikke ved overgang fra HTTP til HTTPS, ved bytte mellom www og ikke-www på samme domene, eller ved endringer i stier innenfor ett domene.

#Hva annet som må oppdateres på det nye domenet

Veiledningen for flytting av nettsted lister endringene på nettstedet som hører til viderekoblingene:

• Oppdater interne lenker slik at de peker direkte til de nye URL-ene, ikke via en viderekobling.
• Gi hver nye URL en kanonisk tagg som peker til seg selv.
• Bruker du hreflang, “sørg for å oppdatere annotasjonene slik at de bruker de nye URL-ene” (egen oversettelse).
• Sjekk at robots.txt på det nye domenet ikke fortsatt har en Disallow: / fra staging.

#8. Hvor lenge viderekoblingene bør stå etter domenebytte i WordPress

Google oppgir to tall. Hjelpesiden for adressebytte sier at videresendingen av signaler fortsetter “i 180 dager etter at du starter migreringen i Search Console” (egen oversettelse), og ber deg beholde viderekoblingene i minst 180 dager, “lenger hvis du fortsatt ser trafikk til dem fra Google Søk” (egen oversettelse). Veiledningen for flytting av nettsted går lenger: behold viderekoblingene så lenge som mulig, generelt i minst ett år. Å fornye registreringen av det gamle domenet er en del av dette, fordi viderekoblingene slutter å virke den dagen domenet utløper.

Om tidsbruken sier samme veiledning at et mellomstort nettsted “kan ta noen uker eller mer” (egen oversettelse) før Google gradvis viser de nye URL-ene, og at større nettsteder tar lengre tid. Svingninger i rangeringen i den perioden er forventet, så vurder flyttingen ut fra data i Search Console over uker, ikke dager.

#9. Hvorfor WordPress fortsatt viderekobler til det gamle domenet etter migrering

Fortsetter nettstedet å sende deg til den gamle adressen etter erstatningen, sjekker du disse stedene i denne rekkefølgen:

• wp-config.php: en glemt WP_HOME- eller WP_SITEURL-konstant med den gamle verdien overstyrer databasen.
• wp_options: kjør wp option get home og wp option get siteurl, eller les de to radene i phpMyAdmin.
• .htaccess og serverkonfigurasjon: noen sikkerhets- og viderekoblingsutvidelser skriver viderekoblingsregler der, og en gammel server-blokk kan fortsatt finnes.
• Cache: sidecache, objektcache (wp cache flush), et CDN og nettleserens egen cache av en tidligere 301 kan alle levere det gamle målet.

#10. Sjekkliste for domenebytte i WordPress

Bruk denne sjekklisten for dine WordPress-migreringer:

• Ta backup av databasen og hele filsystemet, inkludert wp-content/uploads.
• Sett opp den nye verten og installer SSL-sertifikater for det nye domenet, og behold et gyldig sertifikat på det gamle.
• Sjekk at PHP-versjonen på den nye serveren samsvarer med den gamle.
• Importer databasen og oppdater tilgangsdataene i wp-config.php.
• Kjør wp search-replace med --dry-run og --skip-columns=guid, og gå gjennom rapporten.
• Kjør erstatningen for både HTTPS- og HTTP-variantene.
• Fjern midlertidige WP_HOME-, WP_SITEURL- eller RELOCATE-linjer som ikke lenger trengs.
• Tøm omskrivingsregler og cache, og sjekk deretter home og siteurl.
• Sett opp 301-viderekoblinger side til side på det gamle domenet.
• Oppdater kanoniske tagger, hreflang-annotasjoner og interne lenker.
• Send inn adressebyttet i Search Console og det nye nettstedskartet.
• Behold viderekoblingene og registreringen av det gamle domenet i minst ett år.

Trenger du hjelp til å migrere WordPress-databasen eller sette opp viderekoblingsregler på servernivå? Som WordPress-utvikler kan jeg gå gjennom databasen, gjennomføre migreringen og sette opp Search Console. Kontakt meg for å snakke om prosjektet ditt.