WordPress to Next.js: The Complete Database & Content Migration Guide

Your WordPress Database Is More Complex Than You Think

Most people think of WordPress as a simple CMS with posts and pages. In reality, the WordPress database is a sprawling system of 12+ tables with complex relationships. A typical business site that's been running for 3-5 years has accumulated thousands of rows across wp_posts, wp_postmeta, wp_options, wp_terms, and wp_term_relationships. Understanding this structure is the first step to a clean migration.

The good news: WordPress's database is well-documented and follows predictable patterns. The bad news: years of plugin installations have likely added custom tables, serialized data in meta fields, and relationships that aren't immediately obvious. We've migrated sites with 50,000+ posts and 200,000+ meta entries. It's always possible — it just requires a methodical approach.

Understanding the WordPress Database Structure

Before you can migrate content, you need to understand where it lives. Here's the anatomy of a WordPress database:

wp_posts: The Content Hub

This table stores everything that WordPress considers 'content' — and that's more than just blog posts. Pages, custom post types, menu items, WooCommerce products, revisions, and even attachments (media references) all live in wp_posts. Each row has a post_type field that differentiates them. A typical site might have post types like post, page, product, testimonial, case_study, and attachment.

The critical fields for migration are: post_title, post_content (the HTML body), post_excerpt, post_status (published, draft, etc.), post_date, post_name (the URL slug), and post_type. Every one of these needs to map to a field in your new CMS.

wp_postmeta: The Hidden Data Layer

This is where the complexity lives. wp_postmeta stores key-value pairs associated with each post. If you use Advanced Custom Fields (ACF), all your custom field data is here. If you use Yoast SEO, your meta titles and descriptions are here. WooCommerce product prices, SKUs, and inventory data? All here.

The challenge is that meta values are stored as serialized PHP arrays or JSON strings. A single ACF repeater field might generate 20+ meta entries. You'll need to parse and reconstruct these relationships during migration. We've built tooling specifically for this — it's the most time-consuming part of any WordPress migration.

wp_terms and wp_term_relationships: Categories and Tags

WordPress uses a flexible taxonomy system. Categories, tags, and any custom taxonomies (like 'industry' or 'region') are stored in wp_terms. The wp_term_relationships table connects terms to posts. This is a many-to-many relationship — a single post can have multiple categories and tags.

In your Next.js CMS, you'll typically map these to either select fields (for categories with a fixed set) or relationship fields (for taxonomies that grow organically). The mapping should preserve URL structures — if your WordPress URLs are /category/name/post-slug, your redirect map needs to account for this.

wp_options: Site-Wide Settings

This table contains your site title, description, permalink structure, widget configurations, and plugin settings. Most of this doesn't need to migrate — it's WordPress-specific configuration. But some values are important: your site title, tagline, social media URLs, and any global settings your theme uses.

Choosing Your Export Method

There are four primary ways to extract content from WordPress. Each has trade-offs:

Method 1: WordPress REST API

The REST API is the cleanest extraction method for sites with fewer than 10,000 posts. It returns structured JSON with proper relationships already resolved. You can paginate through posts, pages, categories, tags, and media with simple HTTP requests.

• Pros: Clean JSON output, handles relationships, works with any WordPress site, no server access needed
• Cons: Slow for large sites (100 posts per page max), doesn't include all meta fields by default, rate limiting on shared hosts
• Best for: Sites with under 5,000 posts that need a clean, repeatable extraction process

Method 2: WP-CLI Export

If you have SSH access to your WordPress server, WP-CLI is the fastest option. The wp export command generates a WXR (WordPress eXtended RSS) file with all content. You can filter by post type, date range, or author.

• Pros: Fast, complete export including all post types, works offline
• Cons: Requires server access, WXR format needs parsing, media files exported as URLs (not files)
• Best for: Sites where you have server access and want a complete snapshot

Method 3: Direct Database Dump

For complex sites with deep plugin integrations, sometimes you need the raw database. A mysqldump gives you everything — including custom plugin tables, serialized data, and relationships that the REST API doesn't expose.

• Pros: Complete data, nothing lost, includes custom plugin tables
• Cons: Requires database access, needs SQL parsing, serialized PHP data needs special handling
• Best for: Large sites (10,000+ posts) or sites with heavy ACF/WooCommerce usage

Method 4: XML Export (WordPress Admin)

The built-in WordPress export tool (Tools > Export) generates a WXR file without needing server access. It's the same format as WP-CLI export but accessible through the admin dashboard.

• Pros: No technical skills needed, accessible from admin dashboard
• Cons: Can time out on large sites, doesn't include all meta data, limited filtering
• Best for: Small to medium sites where you only have admin dashboard access

Handling Custom Fields: ACF to Structured Content

Advanced Custom Fields (ACF) is used on over 2 million WordPress sites. If your site uses ACF, your migration needs special attention. ACF stores field data in wp_postmeta with a specific naming convention: each field has a value entry and a reference entry (prefixed with an underscore).

The migration process involves:

1. Export your ACF field groups as JSON from the ACF settings page. This gives you the field definitions — types, names, and validation rules.
1. Map ACF field types to your new CMS schema. Text fields become text fields. Repeaters become arrays. Flexible content becomes blocks. Image fields become media relationships.
1. Write a transformation script that reads postmeta entries, matches them to ACF field definitions, and outputs structured data in your new CMS format.
1. Handle serialized data carefully. ACF repeaters store data as serialized PHP arrays in meta values. You need a PHP unserialize function (or a Node.js equivalent like php-serialize) to parse these.

We've found that ACF-heavy sites take 30-50% longer to migrate than standard WordPress sites. The field mapping alone can take a full day for complex configurations. But the result is worth it — your new CMS will have properly typed, validated fields instead of the loosely-typed meta system WordPress uses.

Media Migration: From wp-content to CDN

WordPress stores media files in wp-content/uploads/, organized by year and month (e.g., wp-content/uploads/2024/06/photo.jpg). Your migration needs to:

1. Download all media files from the existing server
1. Re-optimize images (WordPress generates multiple sizes, but they're often not WebP)
1. Upload to your new storage (Vercel Blob, AWS S3, Cloudflare R2, or local)
1. Update all content references to point to new URLs
1. Generate responsive image sets with next/image-compatible dimensions

The tricky part is content references. WordPress embeds images in post_content as HTML img tags with absolute URLs. You need to find-and-replace every image URL in every piece of content. A regex-based approach works for simple cases, but for sites with 500+ posts, we use an AST parser that walks the HTML tree and replaces image nodes with proper Next.js Image components.

After migration, your images will actually perform better than they did on WordPress. Next.js's Image component automatically serves WebP, handles responsive sizing, lazy loads below-the-fold images, and generates blur placeholders. Most sites see a 40-60% reduction in image payload after migration.

Preserving Relationships and Taxonomies

Your WordPress content doesn't exist in isolation. Posts have authors, categories, tags, and often custom relationships (related posts, featured content, parent-child pages). Preserving these relationships requires a deliberate mapping strategy:

• Author data: WordPress stores authors in wp_users. Map these to your new CMS's author or team collection. Include display names, bios, and avatar images.
• Categories and tags: Create matching taxonomy structures in your new CMS. Preserve slugs for URL continuity. Consider whether your category hierarchy (parent/child categories) needs to survive.
• Featured images: WordPress stores featured image IDs in postmeta (_thumbnail_id). Resolve these to actual media entries and establish relationships in your new CMS.
• Internal links: Posts often link to other posts. After migration, these internal links need to point to the new URL structure. A find-and-replace pass through all content is essential.
• Menu structures: WordPress menus are stored as custom post types (nav_menu_item) with parent-child relationships. Extract these and rebuild them as navigation data in your new CMS or as a code-based navigation component.

URL Redirect Mapping for SEO Continuity

This is arguably the most critical step in any WordPress migration. Your existing pages have accumulated search engine authority over years. If URLs change without proper redirects, you lose that authority — and your search traffic drops.

WordPress permalink structures vary widely. Common patterns include:

• /blog/post-slug/ (simple)
• /2024/06/post-slug/ (date-based)
• /category/subcategory/post-slug/ (category-based)
• /custom-post-type/post-slug/ (custom post types)

Your redirect map should be a complete list of every old URL and its corresponding new URL. For a blog migration, this might mean mapping /2024/06/my-post/ to /blog/my-post. Use Next.js's next.config.js redirects or middleware for this. For sites with hundreds of redirects, a database-driven redirect system is more maintainable.

After launching, monitor Google Search Console daily for the first two weeks. Look for crawl errors, dropped pages, and indexing issues. Submit your new sitemap immediately and request re-indexing of your most important pages.

Post-Migration Verification Checklist

Before declaring the migration complete, verify every single one of these:

• Every published post and page exists at its new URL (or has a 301 redirect)
• Featured images display correctly on all content
• Custom fields (ACF, etc.) render properly in the new templates
• Categories and tags link to proper archive pages
• Internal links point to new URLs (no links to old WordPress URLs)
• Contact forms submit successfully
• Search functionality works with all migrated content
• RSS feed includes recent posts
• Sitemap includes all migrated pages
• Google Analytics / tracking scripts are installed
• Meta titles and descriptions are preserved from Yoast/RankMath
• Open Graph images work for social sharing

A WordPress migration is only as good as its verification. We've seen teams rush the launch and discover missing content weeks later — after Google has already de-indexed those pages. Take the time to verify everything before DNS cutover.