2.1. Database

Each origin has an associated set of databases. A database has zero or more object stores which hold the data stored in the database.

A database has a name which identifies it within a specific origin. The name is a name, and stays constant for the lifetime of the database.

A database has a version. When a database is first created, its version is 0 (zero).

Each database has one version at a time; a database can’t exist in multiple versions at once. The only way to change the version is using an upgrade transaction.

A database has at most one associated upgrade transaction, which is either null or an upgrade transaction, and is initially null.

2.1.1. Database Connection

Script does not interact with databases directly. Instead, script has indirect access via a connection. A connection object can be used to manipulate the objects of that database. It is also the only way to obtain a transaction for that database.

The act of opening a database creates a connection. There may be multiple connections to a given database at any given time.

A connection can only access databases associated with the origin of the global scope from which the connection is opened.

This is not affected by changes to the [Document](https://www.w3.org/TR/html52/single-page.html#elementdef-document)‘s [domain](https://www.w3.org/TR/html52/single-page.html#dom-document-domain).

A connection has a version, which is set when the connection is created. It remains constant for the lifetime of the connection unless an upgrade is aborted, in which case it is set to the previous version of the database. Once the connection is closed the version does not change.

Each connection has a close pending flag which is initially unset.

When a connection is initially created it is in opened state. The connection can be closed through several means. If the execution context where the connection was created is destroyed (for example due to the user navigating away from that page), the connection is closed. The connection can also be closed explicitly using the steps to close a database connection. When the connection is closed the close pending flag is always set if it hasn’t already been.

A connection may be closed by a user agent in exceptional circumstances, for example due to loss of access to the file system, a permission change, or clearing of the origin’s storage. If this occurs the user agent must run the steps to close a database connection with the connection and with the forced flag set.

🚧 This behavior is new in this edition. It is supported in Chrome 31, Firefox 50, and Safari 10.1. 🚧

A connection has an object store set, which is initialized to the set of object stores in the associated database when the connection is created. The contents of the set will remain constant except when an upgrade transaction is running.

A connection‘s get the parent algorithm returns null.

A version change event will be fired at an open connection if an attempt is made to upgrade or delete the database. This gives the connection the opportunity to close to allow the upgrade or delete to proceed.