Skip to content

Database Schema

Jump to bottom
Jonathan Bossenger edited this page Nov 10, 2026 · 3 revisions

Database Schema

Current schema (DB version 1)

 notifications_messages          notifications_queue             notifications_subscriptions
+----------------------+        +----------------------+        +----------------------+
| id (PK)              |<-------| message_id           |        | user_id              |
| channel_name         |        | user_id              |        | channel_name         |
| channel_title        |        | dismissed_at         |        | snoozed_until        |
| created_at           |        | displayed_at         |        +----------------------+
| expires_at           |        +----------------------+
| severity             |
| title                |
| message              |
| meta                 |
+----------------------+

A message is created once per emitted notification. The queue links a message to each user who should receive it, and tracks per-user display and dismissal state. Subscriptions record which channels a user is subscribed to.

There are no database-level foreign key constraints. The relationships above are logical only.

{prefix}notifications_messages

Stores each notification message emitted on a channel.

Column Type Null Default Description
id BIGINT(20) No Primary key. ID of the message.
channel_name VARCHAR(50) No Name of the channel the message was emitted on, e.g. core/updates.
channel_title TINYTEXT No Human-readable title of the channel.
created_at DATETIME No CURRENT_TIMESTAMP() When the message was created, in UTC.
expires_at DATETIME Yes NULL When the message expires, in UTC.
severity VARCHAR(16) Yes NULL Severity of the message.
title TINYTEXT Yes NULL Human-readable title of the message.
message TINYTEXT Yes NULL Text content of the message.
meta TEXT Yes NULL JSON-encoded message metadata (see below).

Indexes: PRIMARY KEY (id), KEY channel_name (channel_name)

The meta column holds the JSON output of Message::encode_meta(). The accepted keys are:

  • accept_label: label of the accept action
  • accept_link: URL of the accept action
  • channel_title: human-readable title of the channel
  • dismiss_label: label of the dismiss action
  • expires_at: expiry datetime
  • icon: icon of the message
  • is_dismissible: whether the message can be dismissed (defaults to true)
  • severity: severity of the message

{prefix}notifications_queue

Links a message to each recipient user, and tracks that user's interaction with it.

Column Type Null Default Description
message_id BIGINT(20) No ID of the message (notifications_messages.id).
user_id BIGINT(20) No ID of the recipient user (users.ID).
dismissed_at DATETIME Yes NULL When the user dismissed the message, in UTC. NULL if not dismissed.
displayed_at DATETIME Yes NULL When the message was first displayed to the user, in UTC. NULL if not yet displayed.

Indexes: KEY message_id (message_id), KEY user_id (user_id). There is no primary key.

{prefix}notifications_subscriptions

Records which channels each user is subscribed to.

Column Type Null Default Description
user_id BIGINT(20) No ID of the subscribed user (users.ID).
channel_name VARCHAR(50) No Name of the channel subscribed to.
snoozed_until DATETIME Yes NULL If set, notifications from this channel are snoozed until this time, in UTC.

Indexes: KEY user_id (user_id), KEY channel_name (channel_name). There is no primary key.

Options

Option Description
wp_notifications_db_version Installed schema version. Set to the value of WP_FEATURE_NOTIFICATION_DB_VERSION (currently 1) after the tables are created.
wp_notifications_options Plugin options array, including the plugin version.

Both options are deleted on uninstall.

Notes

  • All DATETIME values are stored in UTC. See WP\Notifications\Helper\Serde.
  • As of writing, the tables are created and dropped by the plugin, but no persistence code reads from or writes to them yet. Wpdb_Notification_Repository is still a stub.

Historical: original schema (pre-v1)

This was the original proposed schema, which was replaced by the DB version 1 schema above. It is kept here for historical reference.

wp_notifications table

  • id (int) 11 auto_increment ID of the notification.
  • sender_key Sender of the notification. As defined by the plugin or theme
  • timestamp Timestamp of when the notification was triggered.
  • recipient_key Single notification recipient. As defined by the plugin or theme
  • title_key Notification title key. As defined by the plugin or theme
  • message_key Notification message key. As defined by the plugin or theme (optional)
  • action_link Correctly formatted URL to an internal or external action.
  • status enum (READ, UNREAD) Notification status.

See the Translations document for details on title_key and message_key fields

Home

Clone this wiki locally