Skip to content

Ignore rules

Some WordPress sites contain a lot of "noise" like log entries, results of security scans, cache items, etc. It is not uncommon that even a simple-looking website contains hundreds of thousands of rows in the database which is a big problem for staging, both from the usability and performance perspective.

Because of that, VersionPress.com uses ignore rules to filter such things out. We're gradually improving these rules so please let us know if you have a site that seems to transfer a lot of unnecessary items between staging and live.

Note

Please note that staging is currently disabled for sites with more than 50,000 non-ignored database rows.

Custom ignore rules

Experimental feature

This feature is a work in progress and may be updated at any time. If you have any feedback to it, please send it our way.

You can create a vp-ignore.json file in your site root to exclude certain items from staging.

Ignoring files

Let's say you have a custom backup folder at wp-content/my-backups:

image

You can exclude it from staging by creating a vp-ignore.json file at the site root (/var/www/html) with this content:

{
  "example.com": {
    "files": [
      "/wp-content/my-backups"
    ]
  }
}

When you create a staging site now, it will not contain the my-backups folder at all:

image

In the JSON:

  • The top-level key (example.com above) is any string that makes sense to you. It is not actively used by the staging engine right now, however, if you know which plugin created the folder we recommend that you use its slug, it might be used in the future. For example, ignore rules for Akismet would be under the akismet key.
  • The files key is an array of files and/or folders to ignore. Each path should start with a slash.

Ignoring database entities

Now let's say you have created a staging environment and when pushing live, you notice that there are options created by someplugin that you don't want to push:

image

You can ignore them by updating your vp-ignore.json file to contain this:

{
  "example.com": {
    "files": [
      "/wp-content/my-backups"
    ],
    "database": {
      "${prefix}options": [
        {"option_name": "someplugin_.*"}
      ]
    }
  }
}

In the new database section:

  1. The table name can be prefixed, use ${prefix} placeholder to use your site's actual prefix.
  2. Under each table, there is an array of column => regex pairs that define what to ignore.

With this, the push to live will exclude the options.

Ignoring whole tables

You can also ignore entire tables, or, more precisely, all rows from them by using the all-rows keyword. The tables themselves will still be created which is important for functionality of some plugins.

For example, most of Wordfence tables can be ignored like this:

{
  "wordfence": {
    "database": {
      "${prefix}wfBadLeechers": "all-rows",
      "${prefix}wfBlockedCommentLog": "all-rows",
      "${prefix}wfBlockedIPLog": "all-rows",
      "... etc. ...": "all-rows"
    }
  }
}

Complex example

The example below is taken from our "global" rules that are applied to each site. Your rules will typically be simpler.

{
  "core": {
    "database": {
      "${prefix}options": [
        {"option_name": "_transient_.*"},
        {"option_name": "_site_transient_.*"},
        {"option_name": "cron"},
        {"option_name": "cron_.*"},
        {"option_name": "db_upgraded"},
        {"option_name": "rewrite_rules"},
        {"option_name": "recently_edited"},
        {"option_name": ".*\\.lock"},
        {"option_name": "can_compress_scripts"},
        {"option_name": "auto_core_update_(notified|failed)"},
        {"option_name": "(auth_|secure_auth_|nonce_|logged_in_)(key|salt)"},
        {"option_name": "logged_in_key"},
        {"option_name": "logged_in_salt"},
        {"option_name": "theme_switched"}
      ],
      "${prefix}postmeta": [
        {"meta_key": "_edit_lock"},
        {"meta_key": "_edit_last"},
        {"meta_key": ".*\\.lock"},
        {"meta_key": "_pingme"},
        {"meta_key": "_encloseme"}
      ],
      "${prefix}usermeta": [
        {"meta_key": "session_tokens"},
        {"meta_key": "nav_menu_recently_edited"},
        {"meta_key": "wporg_favorites"},
        {"meta_key": ".*dashboard_quick_press_last_post_id"}
      ],
      "${prefix}post": [
        {"meta_key": "session_tokens"},
        {"meta_key": "nav_menu_recently_edited"},
        {"meta_key": "wporg_favorites"},
        {"meta_key": ".*dashboard_quick_press_last_post_id"}
      ]
    },
    "files": [
      "/.maintenance"
    ]
  },
  "wp-super-cache": {
    "database": {
      "${prefix}options": [
        {"option_name": "wpsupercache_start"},
        {"option_name": "wpsupercache_count"},
        {"option_name": "wpsupercache_gc_time"},
        {"option_name": "supercache_stats"},
        {"option_name": "supercache_last_cached"},
        {"option_name": "preload_cache_counter"},
        {"option_name": "wpsc_feed_list"}
      ]
    },
    "files": [
      "/wp-content/cache"
    ]
  }
}

JSON Schema

The platform validates the JSON you create and will display an error if it is not well-formed or doesn't validate against the following schema:

Tip

You can use this schema to validate in modern editors like VSCode or PhpStorm, or use this online tool.

{
  "title": "VersionPress.com staging ignore rules",
  "$schema": "http://json-schema.org/draft-06/schema#",
  "type": "object",
  "properties": {
    "$schema": {}
  },
  "patternProperties": {
    ".+": {
      "type": "object",
      "description": "Plugin slug (or basically anything; not significant at runtime)",
      "properties": {
        "database": {
          "type": "object",
          "description": "Database entities to ignore",
          "patternProperties": {
            ".+": {
              "anyOf": [
                {
                  "type": "array",
                  "description": "Table name – (${prefix}options will be replaced with wp_options if your site's $table_prefix is wp_)",
                  "items": {
                    "type": "object",
                    "patternProperties": {
                      ".+": {
                        "description": "Column name => regex",
                        "type": "string"
                      }
                    }
                  }
                },
                {
                  "const": "all-rows"
                }
              ]
            }
          }
        },
        "files": {
          "type": "array",
          "description": "Paths to ignore. Must be relative to site root. E.g.:\n\n['/readme.txt', '/wp-content/cache']"
        }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

Applying rules in live vs. staging

You may have noticed how you can update vp-ignore.json in both live or staging environments, it is just a file in the site root after all. It is OK if the rules are momentarily different, they will always apply to "their" environment. For example, in the Ignoring database entities example above, the wp_options will be ignored just in the staging first. Then, after push, which will also synchronize the vp-ignore.json files, the options will be ignored in both environments.