Skip to main content

Using jq with Drush to inspect state values in Drupal

Published on

Drupal has a key-value database table that stores information about the current environment. The values stored are serialized PHP objects or arrays. That makes inspecting them nearly impossible by just querying the database. Luckily, Drush provides a state:get command for retrieving those values. This command unserializes the values, making them human-readable and even in different formats. One of my favorite tricks is to format the output of arrays or objects to JSON using --format=json. You can then use a tool like jq to extract data.

jq is a command-line processor for JSON. You can use pipes to query and filter JSON data returned from other commands. This makes it easy to extract specific information from JSON output. As the project page says, it's like sed for JSON data. Take an example of needing to debug the Twig cache (TwigPhpStorageCache) and wanting to find a cached template file. Twig templates are cached as PHP files with a prefix. That prefix is saved in the twig_extension_hash_prefix state value. The twig_extension_hash_prefix value is an array containing twig_extension_hash and twig_cache_prefix. The twig_cache_prefix is the prefix prepended to all cached Twig template filenames.

We can use Drush to get the twig_extension_hash_prefix array value:

drush state:get twig_extension_hash_prefix --format=json

  "twig_extension_hash_prefix": {
    "twig_extension_hash": "zJRthtmXi5sRB9HVP6ktv0OJjZ0dNkeMgpXJ2wZdUH8",
    "twig_cache_prefix": "64923a31979bd"

We then use jq to filter and only return the cache prefix value:

drush state:get twig_extension_hash_prefix --format=json \
	| jq '.twig_extension_hash_prefix.twig_cache_prefix'


With that, you can check your template cache (by default sites/default/files/php/twig unless you have customized php_storage) for files that match or do not match that prefix.

# Find files without the current Twig cache prefix
find . ! -name "64923a31979bd*"

# Find files with the current Twig cache prefix
find . -name "64923a31979bd*"

This can be useful when debugging cached Twig templates stored in object storage, like S3 or other volume mounts.

However, most of the time, the state values are simple strings. The key-value store has different collections that currently aren't accessible via Drush. This would be even more useful if we could extract other data from the key-value store. The entity.definitions.installed collection contains entity definition information. The entity.storage_schema.sql collection includes the state of entity schema information. This data help debug the installation, update, and uninstallation of custom fields. If you've seen errors about mismatched entity field definitions even though your database table schema is correct, it's often due to something needing to be fixed by updating these values.

I've opened a feature request for Drush to allow accessing these other key-value collection items.

If you're curious about why you'd want to inspect entity.definitions.installed and entity.storage_schema.sql, check out address_update_8101 from the Address module. We have a similiar example in Commerce Core when the order_items field for orders was converted from a configurable field to a base field in commerce_order_update_8208.