Working with Sitecore databases

This section provides information about APIs for accessing Sitecore databases.

You can use the Sitecore.Data.Database class to access Sitecore databases. A default Sitecore configuration includes these databases:

  • Master - Contains all versions of all content supporting CMS users.

  • Web - Contains published versions from Master supporting the Web site(s).

  • Core - Contains data controlling the Sitecore CMS user interfaces.

You can use the techniques described in the following sections to access Sitecore databases.

It is important to remember that:

  • You should always use Sitecore APIs to access Sitecore databases.

  • You should not use SQL commands to access Sitecore databases.

  • All code runs in the security context of the context user by default.

  • Every attempt to access databases, items, fields, and other resources that do not exist may return Null or raise an exception.

    You can use a security user switcher or security disabler for specific tasks if you know the context user does not have the access rights required to complete an operation.

  • Developers should check for Null when accessing items and fields.

    For brevity’s sake, the code examples in this document do not always check for Null.

  • The Sitecore APIs access Sitecore databases.

    You can also access external data stores using the appropriate .NET APIs.

  • If you create, update, or remove items from a publishing target database, publishing from Master to that publishing target will overwrite those changes.

    You should avoid writing to publishing target databases. To reduce the risk of writing to a publishing target database, do not write to a Sitecore database from a presentation component.

  • You can access data templates, and fields by specifying the name, partial path, full path, ID, and potentially other criteria such as language and version of various API methods.

    For best performance, use IDs whenever possible, but use constants or other features to avoid hard-coding strings in more than one class.

How to access the content database

CMS user interface components such as the Content Editor interact with the content database. The default content database is the Master database. User interfaces such as the Sitecore Desktop allow the user to change the content database to another database.

Note

Presentation components almost exclusively access the context database instead of referencing a database by name.

You can use the Sitecore.Context.ContentDatabase property to access the content database. For example, to access the context database:

Sitecore.Data.Database content = Sitecore.Context.ContentDatabase;

Note

CMS user interface components use configuration data in the context database to manage data in the content database. For more information about the content database, see the section How to Access the Content Database.

How to access a database by name

You can use the Sitecore.Configuration.Factory.GetDatabase() method to access a specific database. For example, to access the Master database:

Sitecore.Data.Database master = Sitecore.Configuration.Factory.GetDatabase("master");

Application logic that publishes or import data typically accesses the Master database by name.

Note

If the first parameter does not match the id of any of the /configuration/sitecore/databases/database elements in web.config, the Sitecore.Configuration.Factory.GetDatabase() method throws an exception. This comparison is case-sensitive.

How to access the context database

The context database is the primary database associated with the logical site accessed by the Web client. For presentation components running on the published Web sites, the context database is one of the publishing target databases, such as Web. In the Experience Editor, the context database is the Master database. In the Desktop, the Content Editor, and other CMS user interfaces, the context database is the Core database.

Presentation components almost exclusively access the context database instead of referencing a database by name.

You can use the Sitecore.Context.Database property to access the context database. For example, to access the context database:

Sitecore.Data.Database context = Sitecore.Context.Database;

Note

CMS user interface components use configuration data in the context database to manage data in the content database. For more information about the content database, see the section How to Access the Content Database.