The Places database

This document provides a high-level overview of the overall database design of the Places system. Places is designed to be a complete replacement for the Firefox bookmarks and history systems using Storage.

View the schema diagram.

Core URL table

• moz_places: This is the main table of URIs and is managed by the history service (see also History service design). Any time a Places component wants to reference a URL, whether visited or not, it refers to this table. Each entry has an optional reference to the moz_favicon table to identify the favicon of the page. No two entries may have the same value in the url column.
• moz_hosts: One entry in this table is created each time you visit a new host. It contains the host url, frequency of access, if typed or not, and it's prefix (https://, ftp://, etc).

History tables

• moz_historyvisits: One entry in this table is created each time you visit a page. It contains the date, referrer, and other information specific to that visit. It contains a reference to the moz_places table which contains the URL and other global statistics.

See History service design for more information.

Bookmarks Tables

• moz_bookmarks: This table contains bookmarks, folders, separators and tags, and defines the hierarchy. The hierarchy is defined via the parent column, which points to the moz_bookmarks record which is the parent. The position column numbers each of the peers beneath a given parent starting with 0 and incrementing higher with each addition. The fk column provides the id number of the corresponding record in moz_places.

• moz_bookmarks_roots: Lists special folders that are the root folders of certain content types in the bookmarks system. The records in this table are mapped to records in the moz_bookmarks table. Bookmarks, folders and separators are descendants of the bookmarks root, while tags and tagged URIs are descendants of the tag root.

• moz_keywords: This table is a unique list of keywords. The moz_bookmarks table has a keyword_id column that maps to a record in moz_keywords table.

See Bookmarks service design for more information.

Annotation Tables

• moz_anno_attributes: Contains the names of all the annotations in the system and a name ID. There should be relatively few unique names.

• moz_annos: Contains the values of page annotations. It maps a page (reference to moz_places) and an annotation name (reference to moz_anno_attributes) to the value of the annotation.

• moz_items_annos: Contains the values of bookmark item annotations. It maps a bookmark, folder or separator (reference to moz_bookmarks) and an annotation name (reference to moz_anno_attributes) to the value of the annotation.

Favicon table

• moz_favicons: This contains a list of unique favicon URIs and data. One or more pages in moz_places refer to each entry. When no pages reference a favicon, the icon entry will be deleted.
  • If the mime type of the image is image/png, the data blob must be reencoded from base16 (the format in which it is stored) to base64 in order to display correctly.

Expiration

Expiration is handled in toolkit/components/places/nsPlacesExpiration.js. This algorithm determines the lifetime of all objects in the Places system.

Periodically at runtime, the following happens to expire pages:

• Expire visits that are older than the history expiration threshold.
• Delete the history entries that were referenced by the expired visits and not referenced by any non-expired visit or bookmark.
• Delete favicons for those expiring history entries that are not referenced by any other history entry.
• Delete annotations that belong to the expiring pages.

At shutdown time, an extra step is performed in case there are any orphans. There are several ways for orphans to be created, including calling markPageAsTyped and then never visiting the page. Extensions might also set favicons for pages that have never been visited.

• Delete any history entries that have no visits, are not bookmarked, and are not place: URIs.
• Delete any favicons that are not referenced by any history entries.

See Places Expiration for more information.