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

Gravity Forms PostgreSQL Integration Add-on

Updated 9 min read Gravity Forms Files, Storage & Databases
On this page
  1. What you need
  2. Step 1: Prepare a database user
  3. Step 2: Connect (Forms, Settings, PostgreSQL)
  4. Step 3: Create a feed
  5. Column types
  6. Insert or upsert
  7. Retries and duplicates
  8. Send past entries
  9. Results on every entry
  10. Updating from 1.0.1
  11. Developer hooks
  12. Troubleshooting
  13. Good to know

The Gravity Forms PostgreSQL Add-On writes every Gravity Forms entry as a row into your own PostgreSQL database. You give it the server and a database user, choose a table, map form fields to columns (or let the add-on build the columns from the form) and decide with conditional logic which entries are written. It works with any PostgreSQL 10 or newer server: self-hosted, Supabase, Neon, Amazon RDS, Google Cloud SQL and others.

What you need

  • WordPress 5.8 or newer, PHP 7.4 or newer, Gravity Forms 2.5 or newer.
  • The PHP pgsql extension or the pdo_pgsql extension on your web server. The add-on uses pgsql when both are present. If neither is installed, a red notice appears in the WordPress admin and the settings page says so; forms keep working, but no row is written until your host enables one of them.
  • A PostgreSQL server that your web server can reach (outbound firewall access on the port, usually 5432) and a database user that may insert into your tables. To let the add-on create tables and columns, the user also needs the CREATE right on the schema and ownership of the tables it changes.
  • A Gravity Extra licence key (Forms, Settings, PostgreSQL).

Step 1: Prepare a database user

Create a dedicated user that can only do what the feeds need. For a table that already exists:

CREATE ROLE gf_writer WITH LOGIN PASSWORD 'choose-a-long-password';
GRANT CONNECT ON DATABASE shopdb TO gf_writer;
GRANT USAGE ON SCHEMA public TO gf_writer;
GRANT INSERT, SELECT, UPDATE ON public.leads TO gf_writer;

SELECT is needed because the add-on reads the column list of the table (from information_schema) before it writes. UPDATE is only needed for upsert feeds. If you want the add-on to create the table itself, also run GRANT CREATE ON SCHEMA public TO gf_writer;. On a self-hosted server, allow the IP address of your web server in pg_hba.conf and reload the configuration.

Step 2: Connect (Forms, Settings, PostgreSQL)

  1. Open Forms, Settings, PostgreSQL and activate your licence key.
  2. Enter the Host, Port (default 5432), Database, Schema (default public), User and Password.
  3. Choose the SSL mode: require (encrypted, the default), prefer, verify-ca, verify-full, allow or disable. The two verify modes also check the server certificate; enter the path of the root certificate file on your web server in Server certificate file.
  4. Click Save Settings, then Test the connection. The test connects with the saved settings, reads the server version, database and user, tells you whether the connection is encrypted and warns if the user has no USAGE right on the schema. It writes nothing.

The password is stored encrypted with your site’s security keys and is never shown again. Leave the password box empty on later saves to keep it, type a new one to replace it, or tick Remove the stored password when saving. If you change the WordPress security keys (AUTH_KEY, SECURE_AUTH_KEY and their salts), enter the password again.

By default rows are written in the background a few seconds after the form is sent, so a slow or unreachable database never holds up the visitor. Tick Write while the visitor waits only if you need the row at once.

PostgreSQL settings with host, port, database, schema, user, password and SSL mode
Figure 1: Forms, Settings, PostgreSQL: the connection settings.

Step 3: Create a feed

Open the form, then Settings, PostgreSQL, and add a feed.

  • Table: the table name, or schema.table to use another schema than the one in the settings.
  • Columns: either Build the columns from the form fields (one column per field, named after the label or the field ID, plus the entry details you tick: entry_id, form_id, created_at, source_url, user_id, payment_status, payment_amount, transaction_id, ip) or I choose the columns (you type the table column and pick the form field, a single input of a name or address field, or an entry detail).
  • Write: Insert a new row, or Upsert.
  • Table maintenance: Create the table and add new columns, and Never insert the same entry twice.
  • Condition: write only the entries that match your conditional logic.
PostgreSQL feed settings with the table, the module and the column mapping
Figure 2: A PostgreSQL feed: table, module and column mapping.
List of PostgreSQL feeds for a form
Figure 3: The feeds of a form.

Column types

When the add-on creates the table, it uses these types. When the table already exists, the add-on reads the real column types and converts the value to fit.

Form field Column
Text, email, textarea, radio, select, phone, website, list (as JSON text), single file upload text
Number, quantity, total, price, shipping numeric
Date (any Gravity Forms date format) date
Time time
Consent boolean
Checkbox, multi select, multiple file upload text[]
Name and address fields one text column per input
entry_id, form_id, user_id bigint
created_at (UTC) timestamptz
payment_amount numeric

An empty answer is stored as NULL. A value that is not a valid number or date for its field becomes NULL as well. Existing columns of type text receive text; integer columns receive whole numbers; json and jsonb columns receive valid JSON; array columns receive a list. Column names are written in lower case with underscores (full_name) and are limited to 63 characters, the PostgreSQL limit. Column names you type in the mapped mode keep their case; if the table has the same name in another case and it is unique, that column is used.

Insert or upsert

Insert adds one row per entry. With Never insert the same entry twice on (the default) and an entry_id column in the feed, the add-on inserts the row only if no row with that entry ID exists yet. Without an entry_id column that guard cannot work, and the entry note tells you so.

Upsert uses INSERT ... ON CONFLICT (key) DO UPDATE. Enter the Key column (default entry_id); it must be one of the columns of the feed. Choose what happens when the key exists: Update the row with the new answers or Keep the old row and do nothing. ON CONFLICT needs a unique index or primary key on the key column. When the add-on creates the table it also creates that unique index. For an existing table, add one yourself, for example CREATE UNIQUE INDEX ON public.leads (email);; if it is missing and table maintenance is on, the add-on tries to create it, and if it cannot (for example because the table already holds duplicates) the entry note explains why. Upsert is the way to keep one row per person: use email as the key and every new submission updates the same row.

Retries and duplicates

  • Temporary faults are retried later: server restarting or shutting down, too many connections, a deadlock, a statement timeout, or no connection (refused, timed out). The waits are 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours, so six tries in all. After the last try the entry gets an error note.
  • Final errors are not retried and the note shows the reason PostgreSQL gave: wrong password or user, unknown database, no right on the table, a value the column cannot take, a missing table or column when table maintenance is off.
  • If the connection drops while the row is being written, the add-on cannot know whether the row was saved. For upsert feeds, and for insert feeds with the entry guard, it simply retries, and no second row is created. For an insert feed without the guard it does not retry; the note says the row may or may not be saved.
  • Two processes never write the same entry and feed at once, and a retry of an entry that has already been written is skipped.
  • Each statement runs with a 15 second limit, the connection timeout is 5 seconds, and values are always sent as bound parameters; table and column names are quoted identifiers.

Send past entries

Open Forms, Entries, tick entries (or choose all entries of the current filter), and pick a bulk action:

  • Send to PostgreSQL: skips entries that were already written and writes the others.
  • Resend to PostgreSQL: writes them again even if they were already written. With upsert, or with the insert guard, this updates or skips rows instead of duplicating them; with an unguarded insert it adds new rows.

The entries are written in the background, about twenty at a time, so a large selection does not time out. Only entries that match the feed’s conditional logic are written.

Entry list with the PostgreSQL bulk action
Figure 4: Forms, Entries: the PostgreSQL bulk action for old entries.

Results on every entry

Each entry gets a note: Row inserted into PostgreSQL table public.leads (or Row written to … (insert or update)), or PostgreSQL write failed with the reason.

Entry with the note Row inserted into PostgreSQL table
Figure 5: Every entry gets a note that says what happened in the database.

Updating from 1.0.1

Version 1.0.1 did not write any row. Install the 2.0.0 zip over the old plugin once (later updates arrive through the normal WordPress update screen), then activate your licence key. Your saved host, port, database, user and password are kept and the password is encrypted the first time you open the WordPress admin. Feeds that you created with 1.0.1 (table name and column mapping) keep their settings and now really write rows. Add the schema and set the SSL mode under Forms, Settings, PostgreSQL; the schema defaults to public and the SSL mode of old settings is prefer until you save the page.

Developer hooks

// Change the values of a row before it is written (column name => value).
add_filter( 'gepg_row', function ( $row, $feed, $entry, $form ) {
    if ( isset( $row['email'] ) ) {
        $row['email'] = strtolower( $row['email'] );
    }
    return $row;
}, 10, 4 );

// After a row was written.
add_action( 'gepg_sent', function ( $entry, $feed, $form ) { /* ... */ }, 10, 3 );

// After the last try failed (the reason is the fourth argument).
add_action( 'gepg_failed', function ( $entry, $feed, $form, $reason ) { /* ... */ }, 10, 4 );

// Connection timeout in seconds (default 5).
add_filter( 'gepg_connect_timeout', function () { return 10; } );

The filter works on the columns of the feed; a key that is not a column of the feed is ignored.

Troubleshooting

Message Cause and fix
The PHP pgsql or pdo_pgsql extension is not installed Ask your host to enable pgsql or pdo_pgsql.
password authentication failed Wrong user or password, or the authentication rule in pg_hba.conf does not match. Enter the password again under Forms, Settings, PostgreSQL.
Connection refused / timeout expired The server is not listening on that host and port, or a firewall blocks your web server. The write is retried later.
no pg_hba.conf entry … SSL Your SSL mode does not match what the server accepts. Try require, or prefer for a server without TLS.
The table … does not exist, or the database user has no rights on it Create the table, give the user rights on it, or turn on Create the table and add new columns.
The table … has no column … Add the column, or turn on table maintenance.
no unique index or primary key Add a unique index on the key column of an upsert feed.
invalid input syntax for type … A value does not fit an existing column type. The note names the type; change the column or the field.

Good to know

  • Deleting an entry in WordPress does not delete the row in PostgreSQL.
  • The add-on opens one connection for each write and closes it again. It does not keep a connection pool. If your provider offers a pooler, use its host and port in the settings.
  • Existing columns are never changed or removed. Only new columns are added.
  • The IP address column is personal data: tick it only when you need it.

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