Understanding the WordPress Options Table: wp_options

Most tables in the WordPress database are related to other tables, but one table is a little different: wp_options. In the WordPress database, this table is completely independent and has no direct relationship with other tables, as shown below.

WordPress database table structure (click to view the full image)

The wp_options table stores site configuration data rather than site content. That data can be accessed through the Options API or the Settings API. We can add data to existing options, or create new options as needed.

In this article, I will cover the following topics:

Accessing data from the wp_options table
The structure of the wp_options table
The sources of data stored in wp_options
WordPress Options API
WordPress Settings API

Accessing data from the wp_options table

The wp_options table stores site settings that affect the whole website. Access to this table must therefore be restricted. Only users with the manage_options capability are allowed to modify its data. By default, that capability belongs to the administrator role, and in multisite mode it belongs to the network administrator role.

That means if you want users with other roles to access data in this table, you would have to grant them the manage_options capability. That is generally risky and should only be done if you fully understand the consequences.

The structure of the wp_options table

The structure of the options table is similar to the metadata tables. It has four fields:

option_ID – an auto-increment ID
option_name – the key of the option
option_value – the value of the option
autoload – whether the option should be automatically loaded when the page loads; in a single-site install the default is usually yes, while in multisite the default is usually no.

option_name is unique in the table. If multiple values are associated with an option, WordPress stores them as an array in option_value. The active_plugins option is a good example, because it stores the currently activated plugins.

When adding, editing, or deleting data in wp_options, you always target the record by its option_name. That point becomes especially important in the APIs described below.

Data sources in the wp_options table

The data stored in wp_options mainly comes from three sources:

Default WordPress settings
Theme settings
Settings added by plugins

To make it easier to work with this table, WordPress provides convenient APIs. Of course, you can also write your own helper functions if you need to interact with the table directly. When creating new settings, the usual approach is to use either the Options API or the Settings API.

Using the WordPress Options API

The Options API includes eight functions that let us add, retrieve, update, and delete options.

Function	Arguments	Notes
`add_option()`	`$option`, `$value`, `$deprecated`, `$autoload`	Only `$option` is required. If the table already contains the specified `option_name`, WordPress treats `$value` as an additional value stored in `option_value`; otherwise it creates a new row.
`delete_option()`	`$option`	Deletes all records for the specified option.
`get_option()`	`$option`, `$default`	`$default` is optional and is returned if the option does not exist.
`update_option()`	`$option`, `$new_value`	`$new_value` becomes the new value stored in `option_value`.
`add_site_option()`	`$option`, `$value`	Similar to `add_option()`, but available network-wide in multisite. The setting is added to the shared options table instead of a site-specific `wp_XX_options` table.
`delete_site_option()`	`$option`	The multisite equivalent of `delete_option()`.
`get_site_option()`	`$option`, `$default`, `$use_cache`	The multisite equivalent of `get_option()`.
`update_site_option()`	`$option`, `$value`	The multisite equivalent of `update_option()`.

When creating an option, you can leave the option_value field empty and add the data later if needed.

Using the WordPress Settings API

Like the Options API, the Settings API can also be used to work with data stored in wp_options. The Settings API lets us create pages that add or update option data, so site settings can be changed directly from the dashboard.

The Settings API overlaps heavily with the Options API, so I will not explain every function in detail here. Instead, I will focus on the key differences:

Settings: the underlying data stored in wp_options
Fields: the user interface used to add or edit that data
Sections: logical groups of fields

The following two functions in the Settings API directly affect data in the wp_options table:

Function	Arguments	Notes
`register_setting()`	`$option_group`, `$option_name`, `$sanitize_callback`	The `$option_name` parameter maps directly to the `option_name` field in `wp_options`.
`unregister_setting()`	`$option_group`, `$option_name`, `$sanitize_callback`	Removes a registered setting from the options system. It effectively does the opposite of `register_setting()`.

The functions above create and manage the settings interface, but they do not directly insert rows into the wp_options table by themselves.

Summary

The wp_options table is not directly related to any other content table in WordPress. It stores site settings and some temporary data, and WordPress provides both the Options API and the Settings API to work with that data safely and consistently.