docs_sdk_open-database.html

<!-- Docs - SDK - openDatabase -->
<div class="section">
  <h2><a href="/docs/">Docs</a> : <a href="/docs/sdk/">SDK</a> : openDatabase</h2>

  <p><span class="font-semibold">openDatabase</span> lets you retrieve your user's data. You also need to have a database open before storing or modifying user data. This API will return a promise that gets resolved once the database becomes available for use.</p>

  <pre>
    <code class="language-javascript">
      userbase.openDatabase({
        databaseName: 'example-database-name',
        changeHandler: function (items) {
          // update your application state with the database items
        }
      }).then(() => {
        // the database can now be used
      }).catch((e) => console.error(e))
    </code>
  </pre>

  <h3 id="params">Parameters</h3>

  <ul>
    <li>
      <span class="field">databaseName</span> [string | Len: 1-100] - The database name to use.
    </li>
    <li>
      <span class="field">changeHandler</span> [function] - A callback that gets invoked when the database gets modified.
      <ul>
        <li>
          <span class="field">items</span> [Array] - The full collection of items in the database, in insertion order.
          <ul>
            <li><span class="field">itemId</span> [string] - The item's unique identifier.</li>
            <li><span class="field">item</span> [object] - The stored item.</li>
            <li><span class="field">fileId</span> [string | optional] - The attached file's unique identifier (if a file has been attached to this item via <a href="/docs/sdk/upload-file/">uploadFile</a>). This can be passed to <a href="/docs/sdk/get-file/">getFile</a> to retrieve the file.</li>
            <li><span class="field">fileName</span> [string | optional] - The attached file's name.</li>
            <li><span class="field">fileSize</span> [number | optional] - The attached file's size in bytes.</li>
            <li>
              <span class="field">createdBy</span> [object] - The item creator's attribution data.
              <ul>
                <li><span class="field">timestamp</span> [date] - The date the item was created.</li>
                <li><span class="field">username</span> [string | optional] - The item creator's username. Not present if the user has been deleted.</li>
                <li><span class="field">userDeleted</span> [boolean | optional] - Whether or not the user has been deleted.</li>
              </ul>
            </li>
            <li>
              <span class="field">updatedBy</span> [object | optional] - Attribution data for the latest update.
              <ul>
                <li><span class="field">timestamp</span> [date] - The date the item was most recently updated.</li>
                <li><span class="field">username</span> [string | optional] - The item updater's username. Not present if the user has been deleted.</li>
                <li><span class="field">userDeleted</span> [boolean | optional] - Whether or not the user has been deleted.</li>
              </ul>
            </li>
            <li>
              <span class="field">fileUploadedBy</span> [object | optional] - Attribution data for the attached file.
              <ul>
                <li><span class="field">timestamp</span> [date] - The date the file was uploaded.</li>
                <li><span class="field">username</span> [string | optional] - The file uploader's username. Not present if the user has been deleted.</li>
                <li><span class="field">userDeleted</span> [boolean | optional] - Whether or not the user has been deleted.</li>
              </ul>
            </li>
            <li>
              <span class="field">writeAccess</span> [object | optional] - Access controls set on the item.
              <ul>
                <li><span class="field">onlyCreator</span> [boolean | optional] - If true, only the item creator or database owner can modify the item.</li>
                <li><span class="field">users</span> [Array | optional] - If set, these are the users allowed to modify the item.</li>
                <ul>
                  <li><span class="field">username</span> [string]</li>
                </ul>
              </ul>
            </li>
          </ul>
        </li>
      </ul>
    </li>
  </ul>

  <h3 id="advanced-params">Advanced Parameters</h3>

  <ul>
    <li>
      <span class="field">shareToken</span> [string | optional] - This token can only be used to open a database another user shared via <a href="/docs/sdk/share-database/">shareDatabase</a>.
    </li>
    <li>
      <span class="field">databaseId</span> [string | optional] - The database's unique identifier. This can only be used to open a database the user received access to directly from another user via <a href="/docs/sdk/share-database/">shareDatabase</a>.
    </li>
  </ul>

  <h3 id="notes">Notes</h3>

  <ul>
    <li>
      If the user provides a new <span class="field">databaseName</span> for the first time, this will create a new database and the user will be the owner.
    </li>
    <li>
      To interact with a database the user received access to from another user via <a href="/docs/sdk/share-database/">shareDatabase</a>, you must provide either the <span class="field">databaseId</span> or a <span class="field">shareToken</span>. Providing a <span class="field">databaseName</span> will simply open a new database and the user will be the owner.     
    </li>
    <li>
      You can retrieve the <span class="field">databaseId</span> of databases the user received access to from other users via <a href="/docs/sdk/get-databases/">getDatabases</a>.
    </li>
    <li>
      Attribution data provided by the <span class="field">createdBy</span>, <span class="field">updatedBy</span>, and <span class="field">fileUploadedBy</span> fields is only available in newly created databases.
    </li>
  </ul>

  <h3 id="errors">Errors</h3>

  <ul>
    <li>ParamsMustBeObject</li>
    <li>DatabaseAlreadyOpening</li>
    <li>DatabaseNameMissing</li>
    <li>DatabaseNameMustBeString</li>
    <li>DatabaseNameCannotBeBlank</li>
    <li>DatabaseNameTooLong</li>
    <li>DatabaseNameRestricted</li>
    <li>DatabaseIdMustBeString</li>
    <li>DatabaseIdCannotBeBlank</li>
    <li>DatabaseIdInvalidLength</li>
    <li>DatabaseIdNotAllowed</li>
    <li>DatabaseIdNotAllowedForOwnDatabase</li>
    <li>ShareTokenInvalid</li>
    <li>ShareTokenNotFound</li>
    <li>ShareTokenNotAllowedForOwnDatabase</li>
    <li>DatabaseNotFound</li>
    <li>ChangeHandlerMissing</li>
    <li>ChangeHandlerMustBeFunction</li>
    <li>UserNotSignedIn</li>
    <li>UserNotFound</li>
    <li>SubscriptionPlanNotSet</li>
    <li>SubscriptionNotFound</li>
    <li>SubscribedToIncorrectPlan</li>
    <li>SubscriptionInactive</li>
    <li>TrialExpired</li>
    <li>TooManyRequests</li>
    <li>ServiceUnavailable</li>
  </ul>

</div>

<hr>