Drupal Migration

We start by separating three concerns: the target Drupal runtime architecture (hosting, caching, search, media), the content model (entities, fields, references, translations), and the integration boundaries (SSO, analytics, external content sources). The target architecture is defined early because migration logic depends on entity definitions, media strategy, and how configuration is managed and deployed. Practically, we run an audit of the existing estate and identify constraints such as multisite patterns, editorial workflows, URL requirements, and compliance needs. We then document architectural decisions: which Drupal version, how configuration will be promoted, how files/media will be stored and served, and how search indexing will be handled. This avoids building migrations against a moving target. The output is a concise architecture brief plus a migration-oriented backlog: what must exist in the target build before data movement (content types, vocabularies, media types, user roles), and what can be deferred. This sequencing reduces rework and keeps migration runs deterministic across environments.

Multisite and multi-language migrations add complexity in three areas: content ownership boundaries, shared versus site-specific configuration, and translation/reference integrity. For multisite, we first confirm whether the target remains multisite, moves to a single codebase with multiple sites, or consolidates into one site with domain access patterns. That decision affects how configuration is split and how content is partitioned. For multi-language, we validate how translations are represented in the source (entity translations, separate nodes, or custom patterns) and map them to Drupal’s translation model in the target. We pay particular attention to referenced entities (taxonomy, media, paragraphs) to ensure translations resolve correctly and do not create orphaned references. Operationally, we design migration runs to support partial execution per site or per language when needed, while still allowing full end-to-end rehearsals. Validation includes language completeness checks, URL parity per locale, and verification that editorial workflows and permissions behave consistently across sites.

We treat cutover as an operational procedure with rehearsals, not a single event. The plan starts with defining acceptable downtime and whether a content freeze is required. Many Drupal migrations use a freeze window to ensure the final delta migration is small and predictable, but the exact approach depends on content velocity and integration constraints. We design a cutover runbook that includes: pre-cutover checks, freeze steps (who triggers it and how), final migration execution, cache warmup, search reindex sequencing, and verification of critical journeys. We also define explicit rollback conditions (for example, failed authentication, missing critical content sets, or unacceptable error rates) and the steps to revert routing or DNS. Where feasible, we reduce downtime by rehearsing delta runs and measuring their duration, ensuring the migration pipeline is idempotent and can be re-run. The goal is a cutover window based on measured evidence rather than optimistic estimates.

At minimum, we recommend development, a production-like staging environment, and production. For migrations, staging must be able to run full migration cycles with representative data volumes and production-like infrastructure characteristics (database engine/version, PHP runtime, caching layers, file storage, and search). Without this, performance and edge-case behavior often only appear at cutover. We also define how data refresh works. Migration development typically needs repeatable source snapshots so that mapping changes can be tested consistently. If the source system is still changing, we agree on snapshot cadence and how to handle deltas. Finally, we align configuration management and deployment processes early. Migration code and configuration must be promoted the same way as application code, otherwise teams end up with environment drift that invalidates test results. The outcome is an environment strategy that supports repeatable runs, measurable validation, and realistic cutover rehearsal.

We start by inventorying integration touchpoints and classifying them by risk: authentication/SSO, search indexing, analytics/tagging, outbound webhooks, and inbound content feeds. For each integration, we identify what changes between source and target: identifiers, URL patterns, caching behavior, API responses, or event timing. During implementation, we align integration contracts with the target platform. That may include updating SSO configuration and role mapping, adjusting search indexing pipelines, and ensuring analytics events and page metadata remain consistent. Where possible, we introduce contract checks or fixtures so payload drift is detected during staging runs rather than after go-live. We also plan cutover sequencing. Some integrations must switch at the same time as routing changes (SSO callbacks, search index endpoints), while others can run in parallel. The goal is to avoid a “big bang” integration change by making dependencies explicit and testable throughout migration rehearsals.

Yes, but we treat it as a data integration and transformation problem rather than a simple import. The first step is to define the source-of-truth for each content domain and the extraction method (database access, APIs, exports). We then map source fields to the target Drupal content model, including normalization rules, taxonomy alignment, and media handling. Implementation typically uses Drupal’s migration framework with custom source plugins or intermediate staging tables where needed. For API-based sources, we pay attention to rate limits, pagination, and idempotency so repeated runs are reliable. For file-based sources, we define validation rules and checksums to detect missing or corrupted assets. The key risk is hidden semantics in the source system (implicit relationships, inconsistent formats). We mitigate this by running early profiling, creating transformation tests, and producing validation reports that confirm completeness and referential integrity before cutover.

Content model drift is usually a governance and tooling issue: changes are made ad-hoc to meet short-term needs, and over time the model becomes inconsistent. During migration, we establish a baseline content model with explicit definitions (entity types, fields, vocabularies, allowed values) and document the rationale for key decisions. We then align governance with delivery workflows. That includes defining who can propose and approve model changes, how changes are reviewed (impact on templates, APIs, search, and analytics), and how configuration is promoted across environments. In Drupal, configuration management is central: model changes should be versioned, reviewed, and deployed like code. Where appropriate, we add automated checks in CI to detect unexpected configuration changes or schema drift. The goal is not to block evolution, but to ensure changes are intentional, reviewed, and compatible with integrations and long-term maintainability.

Redirect and SEO ownership should be shared, with clear decision rights. Engineering typically owns implementation and verification (redirect rules, canonical behavior, sitemap generation, performance impact), while product/content stakeholders own prioritization and acceptance criteria (which URLs must be preserved, what can change, and how content is consolidated). We recommend establishing a redirect strategy early: preserve where feasible, redirect where necessary, and avoid creating chains. We also define how redirects are sourced (existing redirect modules, spreadsheets, analytics-driven top URLs) and how they are tested. Validation includes sampling and automated checks for critical URL sets, plus verification of canonical tags and metadata behavior. During cutover, redirects are part of the operational runbook. Post-launch, we monitor 404s and search console signals to identify gaps. This governance model keeps SEO continuity measurable and prevents last-minute changes that introduce risk.

We define integrity as a set of measurable checks rather than a subjective review. Typical checks include entity counts by type, required field completeness, media file presence, translation completeness, and referential integrity for entity references. We also validate URL parity or redirect coverage for agreed URL sets. The approach combines automated validation (scripts and Drupal queries) with targeted manual sampling for high-value content. For complex relationships (nested components, paragraphs, embedded media), we add specific checks that confirm referenced entities exist and render correctly. Where content is transformed (HTML cleanup, taxonomy normalization), we validate transformation rules against representative samples and edge cases. The output is a validation report per run, allowing teams to compare results across iterations and identify regressions when mappings change. This evidence-based approach supports go/no-go decisions and reduces reliance on late-stage manual spot checks.

Custom modules create risk when they encode business logic that is not visible in content structure alone. Common issues include: custom entity types, bespoke field storage patterns, hard-coded assumptions about node IDs or paths, and integrations implemented directly in module code without clear contracts. We mitigate this by auditing custom modules early and classifying them: retire, replace with contrib/core, refactor, or rebuild. For modules that must remain, we identify what data they depend on and ensure migration mappings provide the required entities and configuration. We also check for behavioral changes between Drupal versions (event subscribers, services, caching, routing) that can alter runtime behavior. Finally, we plan testing around custom logic. Migration validation must include functional checks for features implemented in custom modules, not just content completeness. This reduces the risk of launching a platform where content exists but critical workflows fail.

Timeline depends on content volume, model complexity, custom code, and integration surface area. A useful way to estimate is by phases: discovery/audit, target model alignment, migration implementation, iterative validation cycles, and cutover rehearsal. The number of iterations is often the dominant factor, because mapping changes and edge cases emerge as teams test with real data. For complex platforms, we typically plan for multiple migration runs in staging with measurable acceptance criteria. Each run produces validation evidence and a defect backlog, which is then addressed before the next run. This iterative approach is what makes cutover predictable. We provide an initial estimate after discovery, including critical path items (custom module refactors, integration changes, media handling). We also identify opportunities to reduce scope or sequence work, such as migrating core content first and deferring low-value legacy content, as long as governance and SEO requirements are respected.

Successful migrations require both engineering and content participation. From your side, we typically need: a technical owner (platform architect or lead engineer) to make architecture decisions and coordinate environments; a content owner to validate content model decisions and editorial workflows; and stakeholders for SEO and integrations (analytics, SSO, search) to confirm acceptance criteria. Engineering participation is important for access, security approvals, and integration knowledge. Content participation is important for validating that the target model supports real editorial use and that transformed content remains accurate. SEO and analytics stakeholders help define URL continuity requirements and measurement expectations. We keep collaboration structured through mapping workshops, validation review sessions, and cutover rehearsals. Clear decision rights and availability during key checkpoints reduce rework and prevent late-stage scope changes that increase risk.

We treat Drupal 10 as the immediate target and Drupal 11 as a compatibility constraint. During discovery and target design, we review contributed modules, custom code, and theming approaches for forward compatibility. This includes checking deprecations, Symfony/PHP version alignment, and whether key dependencies have a clear Drupal 11 roadmap. In implementation, we avoid patterns that create upgrade friction: tightly coupled custom patches, unversioned configuration changes, and undocumented overrides. We also keep migration logic and configuration in version control with repeatable pipelines, so future upgrades can be tested in parallel environments. The goal is not to over-engineer for an unknown future, but to make deliberate choices that reduce the cost of the next upgrade cycle. A migration that lands on Drupal 10 with clean dependencies, clear governance, and automated checks is typically much easier to move to Drupal 11 when the time comes.

Performance risk often comes from two sources: content structures that create expensive render paths (deeply nested components, heavy entity reference graphs) and media handling that increases storage and delivery overhead. During modeling and mapping, we review how content will be rendered and cached, and we identify patterns that can cause N+1 entity loads or excessive cache invalidations. We also plan for operational performance events during cutover: cache cold starts, search reindexing, and media synchronization. Cutover runbooks include cache warmup steps and sequencing for indexing so the platform stabilizes quickly after routing changes. Validation includes performance testing in a production-like staging environment using representative content volumes. We focus on key templates, high-traffic routes, and editorial operations that can trigger expensive rebuilds. Where issues are found, we adjust caching strategy, rendering patterns, or content model constraints to keep performance predictable.

For Drupal migrations, we generally prefer the Drupal migration framework because it makes transformations explicit, supports dependency ordering, and enables repeatable runs with validation. Direct database moves can appear faster initially, but they often carry forward legacy schema assumptions and make it harder to normalize the target content model. That said, we may use database-level approaches for specific cases: moving large file metadata tables, staging source snapshots, or extracting data from legacy systems where the Drupal migration framework needs a stable intermediate representation. The key is to keep the transformation logic deterministic and testable. We decide based on requirements: how much the content model changes, how many transformations are needed, and how important repeatability and rollback are. For enterprise platforms with complex content and integrations, the migration framework typically provides better control and auditability.

Maintainability is addressed through architecture decisions, governance, and operational practices established during the migration. We align the target platform with configuration management, environment parity, and a clear deployment process so changes are traceable and reproducible. We also document content model decisions and integration contracts so future teams can evolve the platform without rediscovering assumptions. We recommend a post-go-live stabilization period where migration-related defects are resolved and deferred cleanups are completed. This is also when ownership is formalized: who manages content model changes, how redirects are maintained, and how integrations are monitored. Finally, we aim to leave behind a platform that is upgrade-ready: dependencies are known, custom code is rationalized, and operational runbooks exist for common tasks. This reduces the likelihood that the next upgrade becomes another high-risk migration program.

Collaboration typically begins with a short discovery phase focused on evidence gathering and decision-making. We start with access and context: a walkthrough of the current Drupal estate, an inventory of environments, and a review of key integrations and operational constraints. We also identify stakeholders for content, SEO, and platform operations. Next, we run an audit of content structures and custom code to determine complexity drivers and migration risk areas. In parallel, we clarify the target: Drupal version, hosting assumptions, configuration management approach, and any non-negotiables such as URL continuity or compliance requirements. The discovery phase produces concrete outputs: a migration plan with scope boundaries, a target architecture brief, a draft content model mapping approach, and an initial cutover strategy. From there, we agree on delivery cadence (iterations and validation checkpoints), define roles and responsibilities, and begin implementing migrations in a way that supports repeatable runs and measurable integrity checks.