# Executar uma pesquisa e substituição na base de dados do WordPress

Source: https://support.kapsulehost.com/pt-pt/wordpress-search-replace

O WordPress guarda URLs absolutos em dezenas de tabelas da base de dados, pelo que uma mudança de domínio ou uma passagem para SSL deixa endereços antigos espalhados por publicações, opções e definições de plugins: uma pesquisa e substituição é a forma de os limpar em segurança. Este guia explica as duas formas suportadas de o fazer no KPanel, porque é que um terceiro método comum corrompe os dados e como verificar o resultado.

## Quando precisa de uma

- Ao passar de `http://` para `https://` depois de ativar o SSL.
- Ao mudar de domínio, por exemplo de `old-brand.co.nz` para `new-brand.co.nz`.
- Depois de enviar o staging para produção, quando o nome de anfitrião de staging ainda está gravado na base de dados.
- Ao desativar um antigo servidor de recursos e redirecionar todos os URLs de imagens de uma só vez.
- Para corrigir um erro repetido em muitas publicações, como um número de telefone antigo ou o nome de um produto descontinuado.

> **Warning:** Uma pesquisa e substituição reescreve linhas em todas as tabelas ao mesmo tempo e não existe forma de anular linha a linha. Faça uma cópia de segurança antes de começar, sempre, mesmo para uma alteração que pareça trivial. O KPanel cria uma automaticamente quando usa as ferramentas integradas descritas abaixo, mas se executar o comando por si próprio, a responsabilidade é sua. Consulte [Fazer uma cópia de segurança](https://support.kapsulehost.com/pt-pt/taking-a-backup).

## Porque não pode simplesmente executar um REPLACE de SQL

Este é o erro mais prejudicial no trabalho com bases de dados WordPress, por isso vale a pena compreendê-lo antes de escolher um método.

O WordPress guarda as definições de plugins, as opções de temas e os dados de widgets como strings serializadas de PHP. Uma string serializada regista o comprimento de cada valor que contém, desta forma:

```
a:1:{s:3:"url";s:26:"http://old-domain.co.nz/x";}
```

Esse `s:26` diz que o URL tem 26 caracteres. Substitua `http://` por `https://` com um `REPLACE()` simples de SQL e o texto passa a ter 27 caracteres, enquanto o comprimento guardado continua a indicar 26. O PHP recusa-se então a desserializar a opção inteira, e a definição volta silenciosamente a ficar vazia. As definições do personalizador do tema desaparecem, os sliders perdem os seus diapositivos, as licenças de plugins anulam o próprio registo.

O search-replace do WP-CLI que o KPanel executa desserializa cada valor, faz a substituição no seu interior e volta a serializá-lo com os comprimentos corrigidos. É por isso que é o único método documentado aqui.

> **Important:** Nunca execute `UPDATE wp_options SET option_value = REPLACE(...)` ou o equivalente no phpMyAdmin numa base de dados WordPress. Parece que funcionou, indica linhas afetadas e destrói discretamente todas as definições serializadas em que tocou. Não há forma de reparar isto a não ser restaurar uma cópia de segurança.

## Método 1: O cartão Search & Replace

Esta é a escolha certa para quase toda a gente. Está disponível em todos os planos WordPress.

1. Inicie sessão no [KPanel](https://kpanel.kapsulehost.com) e clique em **Websites** na barra lateral esquerda.
2. Clique no site.
3. Abra o separador **WordPress** e depois a secção **Ações rápidas**.
4. Encontre o cartão **Search & Replace** e clique em **Configurar**.
5. Introduza o texto existente em **Procurar (valor antigo)**.
6. Introduza o novo texto em **Substituir por**.
7. Deixe **Simulação (apenas pré-visualização, sem alterações)** assinalado e clique em **Pré-visualizar**.

![Cartão Search and Replace nas Quick Actions do KPanel](https://support.kapsulehost.com/help/screenshots/wordpress-search-replace.d3d0a573.webp)

A simulação indica quantas substituições seriam feitas e divide a contagem por tabela e coluna, para que possa ver exatamente onde a alteração iria incidir antes de a confirmar.

Quando a pré-visualização estiver correta:

1. Desmarque **Simulação**.
2. Clique em **Executar**.
3. Confirme a caixa de diálogo.

É feita automaticamente uma cópia de segurança completa antes de a substituição começar, e a execução abrange todas as tabelas, incluindo as criadas por plugins.

> **Tip:** Pesquise a string mais específica possível. Substituir `old-domain.co.nz` também reescreve `mail.old-domain.co.nz` e `staging.old-domain.co.nz`, o que raramente é o que pretende. Incluir o esquema, como em `https://old-domain.co.nz`, mantém a correspondência precisa.

## Método 2: WP-CLI a partir da consola

A consola dá-lhe o mesmo motor com mais controlo sobre as opções. É uma das secções que aparecem nos planos geridos; noutros planos, a barra de separadores mostra em vez disso uma ligação **+8 on Managed**.

Abra o site, depois **WordPress**, depois **Consola**. A linha de comandos já começa com `wp`, por isso escreva apenas o resto do comando.

Primeiro, pré-visualize:

```
search-replace 'http://old-domain.co.nz' 'https://old-domain.co.nz' --all-tables --dry-run
```

Depois, execute-o a sério:

```
search-replace 'http://old-domain.co.nz' 'https://old-domain.co.nz' --all-tables
```

> **Warning:** A consola não faz uma cópia de segurança por si. A cópia de segurança automática antes da execução só acontece quando usa o cartão Search & Replace do Método 1. Se executar o comando aqui, faça primeiro uma cópia de segurança por si próprio a partir da página **Cópias de segurança** do site.

Opções úteis:

| Opção | O que faz |
|---|---|
| `--all-tables` | Inclui tabelas personalizadas criadas por plugins, e não apenas as tabelas principais do WordPress |
| `--dry-run` | Indica o que mudaria e não escreve nada |
| `--precise` | Usa PHP em vez de SQL para a substituição. É mais lento, mas lida com estruturas serializadas complicadas |
| `--skip-columns=guid` | Não altera os GUID das publicações (ver abaixo) |
| `--report-changed-only` | Reduz o resultado às tabelas que realmente mudaram |

### Uma nota sobre os GUID

Todas as publicações do WordPress têm uma coluna `guid`. Apesar de parecer um URL, é um identificador e não uma ligação, e os leitores de feeds usam-no para saber se já viram um item. Reescrevê-lo pode fazer com que todas as publicações do seu feed voltem a aparecer como novas.

Reescreva os GUID quando estiver a mudar de domínio de forma permanente e a começar do zero. Ignore-os com `--skip-columns=guid` quando estiver apenas a passar de HTTP para HTTPS no mesmo domínio.

## Mudar de domínio: use antes o cartão Site URL

Se o objetivo é mudar o site para um novo domínio, não comece pela pesquisa e substituição. O cartão **Change Site URL**, na mesma secção **Ações rápidas**, atualiza as opções `siteurl` e `home` e executa a substituição em todas as tabelas numa única operação, pela ordem correta. Fazê-lo ao contrário pode deixar o WordPress incapaz de carregar a sua própria administração.

## Depois da substituição

Percorra esta lista antes de dar o trabalho por concluído.

1. **Limpe a cache.** Na secção **Ações rápidas**, execute **Flush Cache**. Se o site usar a cache de página completa, limpe-a em **WordPress**, depois **Caching**.
2. **Limpe as regras de reescrita.** Execute **Flush Rewrites** na mesma secção, ou abra **Definições**, depois **Ligações permanentes** no wp-admin e clique em **Guardar alterações** sem mudar nada.
3. **Limpe a cache do CDN**, se o site o usar, em **Desempenho**, depois **Kapsule CDN**. Consulte [Limpar a cache do Kapsule CDN](https://support.kapsulehost.com/pt-pt/cdn-cache-purge).
4. **Carregue o site numa janela privada**, para que a cache do seu navegador não o induza em erro.
5. **Verifique o cadeado.** Um cadeado em falta ou com aviso após uma passagem para SSL significa que ficaram URLs para trás: [Resolver avisos de conteúdo misto](https://support.kapsulehost.com/pt-pt/ssl-mixed-content).
6. **Percorra as páginas mais delicadas.** Sliders da página inicial, o logótipo do cabeçalho, qualquer página criada com um construtor de páginas e o checkout numa loja. São estes que contêm os URLs guardados em opções serializadas.
7. **Limpe a cache de qualquer plugin de cache** a partir do respetivo ecrã de definições.

## Resolução de problemas

**A simulação indica zero substituições.** A string não está na base de dados exatamente nessa forma. Verifique se há uma barra final, um prefixo `www.` ou o esquema. Experimente pesquisar primeiro apenas o nome de anfitrião, para confirmar que existe de todo.

**As imagens deixaram de aparecer após uma mudança de domínio.** Os URLs de multimédia estão em `wp_posts` e `wp_postmeta` e são abrangidos por `--all-tables`, mas um CDN ou um plugin de otimização de imagens pode guardar em cache as suas próprias cópias reescritas. Limpe a cache do CDN e a do plugin e, em seguida, recarregue.

**As definições desapareceram após a substituição.** É o problema da serialização, e significa que a alteração foi feita com SQL direto em vez de através das ferramentas aqui descritas. Restaure a cópia de segurança feita antes da execução: [Restaurar a partir de uma cópia de segurança](https://support.kapsulehost.com/pt-pt/restoring-from-backup).

**Os URLs de staging continuam a voltar.** Algo os está a repor, normalmente um envio agendado ou uma opção em cache. Verifique o fluxo de trabalho em [Usar o staging: enviar e obter alterações](https://support.kapsulehost.com/pt-pt/wordpress-staging-workflow) e certifique-se de que **Rewrite URLs** está assinalado quando faz o envio.