🎉 Celebrate with 10% OFF on All Products! Use Code: GFEX10 Or Buy Any 2+ Items for 30% OFF with Code: GFEX30!

Gravity Forms Redis Db Integration Add-on

Updated 10 min read Gravity Forms Files, Storage & Databases
On this page
  1. System requirements
  2. Install and activate
  3. Step 1: Prepare Redis
  4. Step 2: Connect in the add-on settings
  5. Step 3: Create a feed
  6. The structures
  7. Written once, retries, and lost connections
  8. Send old entries
  9. Entry notes
  10. Developer hooks
  11. Troubleshooting
  12. What this add-on does not do
  13. Frequently asked questions

The Gravity Forms Redis Database Integration Add-on writes every Gravity Forms entry to your own Redis or Valkey server. You choose how the entry is stored: a hash, a JSON string, a list, a set, a stream event or a Pub/Sub message. The key takes merge tags, an expiry time is optional, and writes run in the background, so the form never waits for Redis. A server that is down is tried again later, and lists, streams and Pub/Sub messages are written once only, even when a connection drops. Version 2.0.0 is a full rebuild: earlier versions only added an entry note and never connected to Redis.

System requirements

  • WordPress 5.8 or newer and Gravity Forms 2.5 or newer, PHP 7.4 or newer.
  • A Redis server (5.0 or newer for streams; 6.0 or newer if you use a user name with an ACL) or a Valkey server (7.2 or newer). Redis Cluster and Sentinel are not supported: use the address of one node, or of a proxy that hides the cluster.
  • A way to open a connection: the PHP redis extension (phpredis) if the server has it, otherwise the built-in client, which only needs the normal PHP stream functions (and the openssl extension for TLS). The add-on shows a notice if neither can work.
  • Outbound access from your web server to the Redis host and port (6379 by default). A server on another machine must accept the address of your web server (bind and firewall settings), and Redis should never be open to the whole internet without a password and TLS.

Install and activate

  1. Download the ZIP from My Account, Downloads on your GravityExtra account.
  2. In WordPress go to Plugins, Add New, Upload Plugin, choose the ZIP and activate it. If you run version 1.0.x, install the ZIP over it: WordPress replaces the old plugin, your saved settings and feeds are kept, and the saved password is encrypted automatically.
  3. Go to Forms, Settings, Redis DB Add-On and enter your licence key under Gravity Extra License. Nothing is written until the key is accepted.

New versions appear under Dashboard, Updates like any other plugin.

Step 1: Prepare Redis

You need the host, the port, a password if the server has one, and, on Redis 6 or newer, optionally an ACL user. A user that can only do what the add-on does is the safest choice. This example lets one user write hashes with an expiry, and nothing else:

ACL SETUSER gf_writer on >a-long-random-password ~gf:* +hset +expire +del +ping +info +multi +exec +discard

Add the commands your feeds use: SET for strings, SADD for sets, RPUSH or LPUSH for plain lists, XADD for plain streams, PUBLISH for plain Pub/Sub, and EVAL (plus EXISTS, SET, EXPIRE and the push command) when Write each entry once is on, which is the default for lists, streams and Pub/Sub. Allow the key pattern of your feeds, including gfrd:done:*, the small marker keys of the once-only write.

Step 2: Connect in the add-on settings

  1. Open Forms, Settings, Redis DB Add-On.
  2. Enter Host (a name or an address, for example redis.yourcompany.com; a path that starts with a slash is read as a local socket), Port (default 6379) and Database number (default 0; managed services often allow only 0).
  3. Enter the Username only if the server uses ACL users, and type the Password. The password is stored encrypted with your site keys and is never shown again; leave the box empty later to keep it, or tick Remove the stored password if the server has none.
  4. Choose Encrypted connection (TLS): Off for a server on the same machine, On, and check the server certificate for a server on another machine (recommended; add the CA certificate file if the certificate does not come from a public authority), or On, without checking the certificate if you cannot do better.
  5. Leave Connection library on Automatic (phpredis when installed, otherwise the built-in client), or choose the built-in client if you want to be sure which one runs.
  6. Click Test connection. It connects with the values on the screen, sends PING, reads the server version and tells you whether the connection is encrypted. It writes nothing.
  7. Click Save Settings.
Redis settings with host, port, database number, username, password, TLS and the Test connection button
Figure 1: Forms, Settings, Redis Database: the connection settings.

By default entries are written in the background. Tick Write while the visitor waits only if you must have the data in Redis before the confirmation page appears: then a slow server also slows the form.

Step 3: Create a feed

  1. Open the form, then Settings, Redis DB Add-On and click Add New.
  2. Give the feed a Feed Name and choose the Structure (see the table below).
  3. Type the Key (or the channel of a Pub/Sub feed). Merge tags work, for example gf:{form_id}:{entry_id} gives every entry its own key, crm:contact:{Email:2} gives every address its own key, and a fixed key such as queue:signups shares one list or stream between all entries. {feed_id} is available too.
  4. Optionally set Expire after (seconds).
  5. Choose the fields: I choose the fields (Field Mapping: the name in Redis on the left, the form field, an entry detail or a custom value with merge tags on the right) or Use every form field (named by label, for example customer_name, or by field ID, for example field_3; tick the entry details you want, such as the entry ID, form ID and date).
  6. Optionally use Enable Condition to write only the entries that match.
  7. Save the feed.
Redis feed settings with the structure, the key with merge tags, the expiry and the entry details
Figure 2: A Redis feed: structure, key, expiry and fields.

The structures

StructureRedis commandWhat is storedSent twice
HashHSET key field value …One field per mapped form field under the key. Optional: delete the key first (Replace the hash).Same data again, no harm
StringSET key value [EX seconds]The mapped fields as a JSON object (lists stay lists, entry ID and form ID stay numbers), or your own Message text.Same data again, no harm
SetSADD key memberThe member is your Message (for example {Email:2}) or the JSON object. The same member twice is one member.No harm
List, endRPUSH key elementOne element per entry: your Message or the JSON object. A queue for workers that pop from the start.Written once by the marker
List, startLPUSH key elementSame, added at the start.Written once by the marker
StreamXADD key [MAXLEN ~ n] * field value …One event per entry with the mapped fields. Keep about this many events trims the stream. Redis 5 or newer.Written once by the marker
Pub/SubPUBLISH channel messageThe message is your Message or the JSON object. Pub/Sub keeps no history: a message published while nobody is subscribed is gone, and the entry note says so.Written once by the marker

Expiry: for a hash, string or set the key gets EXPIRE (or EX for a string); for a list or stream the key gets the expiry again after every entry. A feed that writes a hash with an expiry sends HSET and EXPIRE together in one MULTI / EXEC group, so a key never stays without its expiry.

Written once, retries, and lost connections

Every write runs in the background through WordPress cron. If Redis is unreachable, loading, read-only or out of memory, the add-on tries again after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours (six tries in all). Wrong passwords, a missing permission, a key of the wrong type or a key that cannot be used fail at once with the reason in the entry note, because trying again would not help.

The hard case is a connection that drops while a command is running: nobody can know whether Redis applied it. A hash, string or set is simply written again (same data). For a list, stream or Pub/Sub feed the add-on uses Write each entry once (on by default): the item and a small marker key (gfrd:done:gf<form>-e<entry>-f<feed>, kept 30 days) are written by one Lua script (EVAL), which runs as a single step on the server. The script looks for the marker first, writes the item, and sets the marker last, so a retry can never add the item twice, and a write that Redis refuses leaves no marker behind. If your server does not allow EVAL, turn the option off: the entry note then explains the choice, and an item whose delivery was unclear is not retried (status “not confirmed”), because a retry could add it twice. You can check Redis and send it again by hand.

Send old entries

In Forms, Entries select entries (or all) and choose Send to Redis (skip entries already sent). They are written in small batches by cron, 25 at a time, and entries that were already written are skipped. For hash, string and set feeds there is also Send to Redis again, which writes them again (for example after you changed the mapping). List, stream and Pub/Sub feeds offer only the first action, because the marker would refuse a second item. A notice tells you how many writes were queued and how many were skipped.

Entry notes

Every write adds a note to the entry, for example “Redis: hash written to key gf:3:17.” or “Redis write failed: … ” with the reason and, for common faults, what to do. Notes never contain the password.

Entry note that says Redis: hash written to key
Figure 3: Every entry gets a note that says what happened in Redis.

Developer hooks

gform_redis_db_data_pre_send (filter, three arguments) runs before the write. $redis_data holds structure, key, ttl (seconds), fields (name to value) and message (text or null). Set custom_key to replace the key. gform_redis_db_post_process (action, three arguments) runs after a successful write while the connection is open; $redis_client has command(), transaction() and publish(). It does not run when the once-only marker found the entry already written. gfrd_connection (filter) lets you return your own connection object, and gfrd_guard_ttl (filter) changes the life of the marker keys.

add_filter( 'gform_redis_db_data_pre_send', function ( $redis_data, $feed, $entry ) {
	$redis_data['custom_key']          = sprintf( 'gf:entry:%d:%s', $entry['form_id'], $entry['id'] );
	$redis_data['ttl']                 = 604800; // 7 days.
	$redis_data['fields']['ip_hash']   = hash( 'sha256', $entry['ip'] );
	return $redis_data;
}, 10, 3 );

add_action( 'gform_redis_db_post_process', function ( $redis_client, $entry, $feed ) {
	$redis_client->publish( 'events:form_activity', wp_json_encode( array( 'entry_id' => $entry['id'] ) ) );
}, 10, 3 );

Troubleshooting

MessageCauseWhat to do
Cannot connect to …Redis is not running, listens on another address, or a firewall blocks the port. Retried later.Check host and port, bind in redis.conf and the firewall; click Test connection.
NOAUTH Authentication requiredThe server wants a password.Type it in the settings.
WRONGPASS invalid username-password pairWrong user or password.Check both. Leave the username empty for the default user.
AUTH called without any password configuredYou typed a password but the server has none.Tick Remove the stored password.
NOPERM … no permissionsThe ACL user may not run a command or use a key.Allow the command or key pattern (see Step 1).
WRONGTYPE Operation against a keyThe key already holds another kind of data than the feed writes.Use another key.
READONLY / LOADING / OOMReplica, server still starting, or out of memory. Retried later.Use the primary address, wait, or free memory.
The key is empty or not usableThe key template gave nothing, or more than 512 bytes.Use a merge tag that always has a value, or a fixed text.
… does not allow Lua scripts (EVAL)Once-only writes need EVAL.Allow EVAL, or turn off Write each entry once.
MOVED / ASK (cluster)The server is a Redis Cluster.Cluster mode is not supported: use one node or a proxy.

What this add-on does not do

  • It does not connect to Redis Cluster or Sentinel, and does not keep persistent connections between requests.
  • It does not read from Redis, rate-limit visitors, or count submissions in Redis: it writes entries.
  • It does not delete data in Redis when an entry is deleted in WordPress. Give the key an expiry, or remove the data in Redis when a person asks to be erased.
  • Pub/Sub has no delivery guarantee: Redis drops a message when nobody is subscribed.

Frequently asked questions

Does this replace the Gravity Forms entries in WordPress? No. The entry is saved by Gravity Forms as usual; the add-on adds a copy to Redis.

Is the password safe? It is encrypted with your site keys (libsodium, or OpenSSL AES-256-GCM) before it is stored, never shown again, and never written to entry notes or logs. If you change the WordPress secret keys, type the password again.

Which library connects? phpredis if the extension is installed and the setting is on Automatic, otherwise a small built-in client of the Redis protocol, with TLS through PHP streams. The Test connection result names the one in use.

What happens when I update from 1.0.x? Your saved connection is kept (a numeric “Database Name” becomes the database number) and your feeds are read as hash feeds: the old “table name” becomes the start of the key (name:{entry_id}) and the old column mapping becomes the hash fields. Version 1 never wrote anything, so after the update the feeds start writing to Redis. Enter your licence key once under the new settings.

Still need help?

Our support team answers tickets every day, usually within a few hours.

0
0
Your Cart
Your cart is emptyReturn to Shop
🔥 FREQUENTLY BOUGHT TOGETHER
Complete Combo & Save 40%!
ITEM IN YOUR CART
Gravity Forms Klaviyo Add-on
$39.00/yr
+
🎁 RECOMMENDED ADD-ON SAVE 40% OFF
Original Price: $39.00/yr
Bundle Special Price: $23.40/yr