drupal-config-mgmt

name	drupal-config-mgmt
description	Drupal configuration management including config import/export, config splits (complete and partial), syncing config across environments, drush commands for config management, config:import, config:export, config-split commands

Drupal Configuration Management

Comprehensive guide for Drupal configuration management including imports, exports, config splits, and environment syncing.

Remote CLI — host-neutral

Examples below use Pantheon's Terminus (terminus drush <site>.<env> -- <cmd>). The commands are identical on any host — substitute your platform's remote-drush form. If your platform provides Drush site aliases, the generic drush @<alias> <cmd> works everywhere.

Task	Acquia (acli)	Pantheon (Terminus)	Platform.sh / Upsun	Lagoon (amazee.io)	Generic (Drush aliases)
Remote drush	acli remote:drush -- <cmd>	terminus drush <site>.<env> -- <cmd>	platform drush -e <env> -- <cmd> (Upsun: upsun drush …)	lagoon ssh -p <project> -e <env> -C "drush <cmd>"	drush @<alias> <cmd>
Get/inspect config	acli remote:drush -- config:get <name>	terminus drush <site>.<env> -- config:get <name>	platform drush -e <env> -- config:get <name>	lagoon ssh -p <project> -e <env> -C "drush config:get <name>"	drush @<alias> config:get <name>

The auto-confirm warning below applies to every host — append --no to cim/config:import to preview instead of apply. Drush defaults to --yes when invoked non-interactively (which all remote-CLI wrappers do).

Problem: Avoid Accidental Config Imports

CRITICAL: Terminus drush commands default to --yes unless explicitly told --no. This means commands like config:import or cim will AUTO-CONFIRM and import configuration even when you only want to inspect differences.

Dangerous vs Safe Patterns

❌ DANGEROUS - Auto-imports without confirmation:

terminus drush {site}.{env} -- cim --diff  # DON'T DO THIS!

✅ SAFE - Shows diff without importing:

terminus drush {site}.{env} -- cim --no --diff

✅ SAFEST - Read-only commands:

terminus drush {site}.{env} -- config:get config.name
terminus drush {site}.{env} -- config:status

Table of Contents

1. Preferred Prod Config Merge Workflow
2. Configuration Import & Export Basics
3. Config Splits Overview
4. Complete vs Partial Splits
5. Config Split Commands
6. Safe Inspection Workflow
7. Syncing Config from Upstream Environments

---

Preferred Prod Config Merge Workflow

Purpose: Safely merge production config changes while preserving local feature work.

The Process

Step 1: Commit local changes first

git add config/default/your-new-field.yml docroot/modules/custom/your_module/your_module.module
git commit -m "feat: add new feature"

Step 2: Pull production database

ddev pull pantheon --environment=live
# Or your preferred method

Step 3: Export config from prod DB

ddev drush config:export -y

Step 4: Review git diff on config directory

git diff --stat config/           # Summary of changes
git status --short config/        # See added/modified/deleted

Step 5: Identify files to revert vs keep

Look for these patterns:

• D (Deleted) - Your new feature files deleted by prod export → REVERT
• M (Modified) - UUID changes from prod → KEEP
• M (Modified) - Actual prod config changes → KEEP
• M (Modified) - Local changes overwritten → REVERT (case by case)

Step 6: Restore your local feature files

# Restore deleted files (your new feature config)
git checkout HEAD -- config/default/field.storage.node.your_new_field.yml
git checkout HEAD -- config/default/field.field.node.bundle.your_new_field.yml

# Or restore specific modified files
git checkout HEAD -- config/default/some.config.yml

Step 7: Verify and commit prod config

git status --short config/        # Verify your files are restored
git diff config/                  # Review remaining prod changes
git add config/
git commit -m "chore: sync config from production"

Quick Reference Table

git status	Meaning	Action
D config/default/field.*.your_feature.yml	Your new feature deleted	git checkout HEAD -- <file>
M config/default/*.yml (UUID only)	Prod UUID sync	Keep (stage for commit)
M config/default/views.view.*.yml	View changed in prod	Keep (review first)
M config/default/system.*.yml	System config from prod	Keep (review first)

Example Session

# After pulling prod DB and exporting config
$ git status --short config/
 M config/default/core.entity_view_display.node.song.teaser.yml
 M config/default/field.storage.group.field_member_count.yml
 D config/default/field.field.node.song.field_child_song_count.yml
 D config/default/field.storage.node.field_child_song_count.yml
 M config/default/views.view.songs.yml

# The D files are our new feature - restore them
$ git checkout HEAD -- config/default/field.field.node.song.field_child_song_count.yml \
                       config/default/field.storage.node.field_child_song_count.yml

# Verify
$ git status --short config/
 M config/default/core.entity_view_display.node.song.teaser.yml
 M config/default/field.storage.group.field_member_count.yml
 M config/default/views.view.songs.yml

# Our feature files are no longer in the diff - commit prod changes
$ git add config/ && git commit -m "chore: sync config from production"

---

Configuration Import & Export Basics

Exporting Configuration

Export ALL configuration (from active config to YAML files):

# Local
ddev drush config:export
ddev drush cex

# Remote
terminus drush {site}.{env} -- config:export

Export a SINGLE config object:

# Get config and save to file
ddev drush config:get config.name --format=yaml > config/default/config.name.yml

# Example: Export a specific view
ddev drush config:get views.view.content --format=yaml > config/default/views.view.content.yml

Importing Configuration

Import ALL configuration (from YAML files to active config):

# Local
ddev drush config:import
ddev drush cim

# Remote (DANGEROUS - auto-confirms with terminus!)
terminus drush {site}.{env} -- config:import --no  # Use --no to preview only

Import a SINGLE config object:

# Delete from active config first, then import
ddev drush config:delete config.name
ddev drush config:import --partial --source=config/default

# Or use config:set for specific values
ddev drush config:set config.name key.subkey value

Best Practice: Always preview changes first:

ddev drush config:import --no --diff  # Show what would change
ddev drush cim --no --diff            # Alias

---

Config Splits Overview

Config splits allow you to have environment-specific configuration that doesn't get deployed to all environments.

Common Use Cases

• Local development: Enable devel, kint, stage_file_proxy
• Staging/Test: Enable similar modules but different API keys
• Production: Disable development modules, enable caching

How Splits Work

1. Base config (config/default/) - Shared across all environments
2. Split config (config/{split-name}/) - Environment-specific overrides
3. Split definition (config/default/config_split.config_split.{name}.yml) - Defines which config goes in split

When a split is active, its config takes precedence over base config.

Split Activation

Splits are activated based on conditions in their config:

• Status: status: true in split config
• Environment variable: Can use conditions based on env vars
• Manual activation: Via admin UI or drush

---

Complete vs Partial Splits

CRITICAL: Understanding the difference between Complete and Partial splits is essential.

Complete Splits (Recommended for most cases)

How it works:

• Config in the split is ONLY active when split is enabled
• When split is disabled, config is completely removed from active config
• Think: "This config exists ONLY in this environment"

Use cases:

• Development modules (devel, kint, webprofiler)
• Environment-specific modules (stage_file_proxy for local)
• Testing modules (simpletest, phpunit)

Example: Local split with devel module

# config/default/config_split.config_split.local.yml
status: true
module:
  devel: 0
  kint: 0
complete_list:
  - 'core.extension'

When split is active: devel and kint are enabled When split is inactive: devel and kint are completely removed

Reference: See admin form at /admin/config/development/configuration/config-split/{split-name}:

"Complete Split: Remove the selected configuration entirely when the split is inactive. When this split is inactive, the configuration listed here will be removed from the system completely."

Partial Splits (Conditional Overrides)

How it works:

• Base config exists in config/default/
• Split contains overrides in config/{split-name}/
• When split is active, overrides are merged with base config
• When split is inactive, base config is used
• Think: "This config exists everywhere, but with different values per environment"

Use cases:

• API keys that differ per environment
• Email settings (different SMTP per environment)
• Cache settings (aggressive in prod, disabled in local)
• Search server URLs (local Solr vs Pantheon Search)

Example: Different search servers per environment

Base config (config/default/search_api.server.main.yml):

backend_config:
  connector: pantheon_search
  # Production settings

Local override (config/local/config_split.patch.search_api.server.main.yml):

backend_config:
  connector: solr
  connector_config:
    host: solr
    # Local Solr settings

When local split is active: Uses local Solr When local split is inactive: Uses Pantheon Search

Reference: See admin form at /admin/config/development/configuration/config-split/{split-name}:

"Partial Split (Conditional Override): Keep the selected configuration, but override it when the split is active. The configuration will exist in the sync directory, but the version from this split will be used instead when the split is active."

Choosing Complete vs Partial

Use Complete when:

• ✅ Config should NOT exist in other environments (modules, views, blocks)
• ✅ It's an on/off decision (enable/disable)
• ✅ Different environments need different features

Use Partial when:

• ✅ Config exists everywhere but with different VALUES
• ✅ Same feature, different settings (API URLs, credentials)
• ✅ You need the base config to be importable without the split active

---

Config Split Commands

CRITICAL: Active vs Exported Configuration

⚠️ IMPORTANT: When updating config split definitions, changes must be in ACTIVE configuration (database), not just exported files!

Workflow:

1. Edit config/default/config_split.config_split.{name}.yml
2. Import to make active: ddev drush config:import --partial OR use PHP (see below)
3. Export: ddev drush cex

Quick method - Set active config via PHP:

ddev drush php:eval "\$config = \Drupal::configFactory()->getEditable('config_split.config_split.local'); \$config->set('partial_list', ['config.name']); \$config->save();"

See examples.md for detailed workflow.

Export Config with Splits

Export ALL config including active splits:

ddev drush config:export

This exports:

• Base config to config/default/
• Active split config to config/{split-name}/

Export a specific split:

ddev drush config-split:export {split-name}
ddev drush csex {split-name}

Import Config with Splits

Import ALL config including active splits:

ddev drush config:import
ddev drush cim

This imports:

• Base config from config/default/
• Active split config from config/{split-name}/

Import a specific split:

ddev drush config-split:import {split-name}
ddev drush csim {split-name}

Import only base config (ignore splits):

ddev drush config:import --skip-modules=config_split

Activate/Deactivate Splits

Activate a split:

ddev drush config-split:activate {split-name}

Deactivate a split:

ddev drush config-split:deactivate {split-name}

Check Split Status

List all splits and their status:

ddev drush config-split:status
ddev drush css

Example output:

Split       Active  Configuration directory
local       Yes     ../config/local
dev         No      ../config/dev
test        No      ../config/test

---

Safe Inspection Workflow

Use config:get and config:status for read-only inspection, or use --no flag with cim/cex to prevent auto-confirmation.

Get Config Values

# Get full config object
terminus drush {site}.{env} -- config:get config.name

# Get as YAML
terminus drush {site}.{env} -- config:get config.name --format=yaml

# Extract specific values
terminus drush {site}.{env} -- config:get config.name 2>&1 | grep "setting_name"

Compare Local vs Remote

# View diffs without importing (SAFE with --no)
terminus drush {site}.{env} -- cim --no --diff

# Get remote and compare manually
terminus drush {site}.{env} -- config:get config.name --format=yaml > /tmp/remote.yml
diff -u config/default/config.name.yml /tmp/remote.yml

CRITICAL: Always use --no flag with terminus! Without it, commands auto-confirm.

Apply Changes

Preferred: Edit config files directly, then commit:

# Use Edit tool on config/default/config.name.yml
git diff config/default/config.name.yml
git add config/default/config.name.yml
git commit -m "Update config from {env}"

---

Syncing Config from Upstream Environments

Quick Methods

Single config object:

terminus drush {site}.{env} -- config:get config.name --format=yaml > config/default/config.name.yml
git add config/default/config.name.yml && git commit -m "Update from {env}"
ddev drush config:import --partial

Full config sync via rsync:

terminus drush {site}.{env} -- cex
terminus rsync {site}.{env}:code/config/default /tmp/remote
diff -r config/default /tmp/remote  # Review
cp /tmp/remote/*.yml config/default/
git add config/default/ && git commit -m "Sync from {env}"
ddev drush cim

Via database pull (DDEV + Pantheon):

ddev pull pantheon --environment={env}  # Warning: Overwrites local DB!
ddev drush cex
git diff config/ && git add config/ && git commit -m "Config from {env}"

See examples.md for detailed workflows.

Best practices: Review diffs, commit separately, test locally, document source, avoid syncing environment-specific config.

---

Deep Dive References

For comprehensive technical documentation, see:

• config-split-deep-dive.md - Complete technical reference on Config Split 2.0, patch files, export/import process, and dependency handling
• examples.md - Practical examples and workflows

Config Status Check

Check what config would be imported (read-only):

# Local environment
ddev drush config:status

# Remote environment
terminus drush {site}.{env} -- config:status

Best Practices

1. Always inspect before importing - Use config:get and --no --diff flags
2. Manual edits preferred - Edit config files directly for precision
3. One config type per commit - Separate concerns for clean history
4. Clear commit messages - Reference source environment
5. Clean up temp files - Remove temporary YAML files
6. Verify before committing - Always review git diff output
7. Test locally first - Import and test before deploying
8. Use config splits - Keep environment-specific config separate

---

Troubleshooting

Config files deleted from working directory

If files are marked as deleted in git status:

git checkout HEAD -- config/default/*.yml

This can happen if a drush command runs unexpectedly.

Split not activating

Check split status:

ddev drush config-split:status

Manually activate:

ddev drush config-split:activate {split-name}
ddev drush cex  # Export to save activation state

Config deleted from config/default on export

COMMON ISSUE: Config (like search_api.server.pantheon_search) gets removed from config/default/ when you run drush cex.

Root cause (99% of cases): Config is in complete_list instead of partial_list!

Complete split = Config is REMOVED from config/default/ and moved to split directory entirely Partial split = Config STAYS in config/default/, only differences are patched

Diagnosis:

# Check if config is in complete_list (will be deleted from config/default)
grep -A10 "complete_list:" config/default/config_split.config_split.local.yml

# Check if config is in partial_list (will stay in config/default)
grep -A10 "partial_list:" config/default/config_split.config_split.local.yml

Solution: Move from complete_list to partial_list

# Edit the split definition
# Move: search_api.server.pantheon_search
# FROM: complete_list
# TO: partial_list

ddev drush cex  # Re-export
# Check that config/default/search_api.server.pantheon_search.yml exists
# Check that config/local/config_split.patch.search_api.server.pantheon_search.yml exists

See config-split-deep-dive.md for complete technical explanation.

Config won't import

Common issues:

• Dependencies missing: Install required modules first
• UUID mismatch: Use --partial flag
• Locked config: Some config (like system.site) has immutable values

# Skip specific config during import
ddev drush config:import --skip-config=system.site

Related Commands

Read-only: config:get, config:status Exports: config:export (alias: cex) Imports: config:import (alias: cim) - Use with --no --diff to preview Splits: config-split:status, csex, csim, config-split:activate