diff --git a/src/pages/config.md b/src/pages/config.md index a872ebb08..3e7fcb315 100644 --- a/src/pages/config.md +++ b/src/pages/config.md @@ -90,8 +90,8 @@ - [State and Files](guides/app_builder_guides/storage/application-state.md) - [Database (Beta)](guides/app_builder_guides/storage/database.md) - [aio app db Commands](guides/app_builder_guides/storage/db-commands.md) - - [MongoDB Compatibility](guides/app_builder_guides/storage/db-mongo-compatibility.md) - [Runtime Actions](guides/app_builder_guides/storage/db-runtime-actions.md) + - [MongoDB Compatibility](guides/app_builder_guides/storage/db-mongo-compatibility.md) - [Best Practices](guides/app_builder_guides/storage/db-best-practices.md) - [Telemetry](guides/app_builder_guides/telemetry.md) - [Runtime Guides](guides/runtime_guides/index.md) diff --git a/src/pages/guides/app_builder_guides/index.md b/src/pages/guides/app_builder_guides/index.md index 718991868..7e707a115 100644 --- a/src/pages/guides/app_builder_guides/index.md +++ b/src/pages/guides/app_builder_guides/index.md @@ -17,7 +17,7 @@ Welcome to the App Builder Guides section. Here you'll find comprehensive docume * [Development](development.md) * [Distribution](distribution.md) * [Optimization](optimization.md) -* [Storage](./storage/application-state.md) +* [Storage](./storage/index.md) * [Telemetry](telemetry.md) ## Configuration and Deployment diff --git a/src/pages/guides/app_builder_guides/storage/database.md b/src/pages/guides/app_builder_guides/storage/database.md index 9e9c4709a..1642add48 100644 --- a/src/pages/guides/app_builder_guides/storage/database.md +++ b/src/pages/guides/app_builder_guides/storage/database.md @@ -18,6 +18,12 @@ Database Storage for App Builder provides document-style database persistence fo There is a strict one-to-one relationship between an AIO project workspace and a workspace database, and each workspace database is entirely isolated from all other workspace databases. +## App Builder Data Services API + +In order to use App Builder Database Storage in an AIO project workspace, you must add the **App Builder Data Services** API, which provides the necessary authentication between runtime actions and the App Builder Database Storage service. + +You can add the **App Builder Data Services** API in the developer console like any other API. It does not require any special license or subscription beyond the App Builder license. + ## Provision a workspace database Before using Database Storage in an AIO project workspace, a workspace database must be provisioned. This is a self-service operation requiring no special permissions. @@ -79,13 +85,48 @@ Run the following command in the root of your AIO project workspace to install t npm install @adobe/aio-lib-db ``` +### Initialization and authentication + +You must always initialize **aio-lib-db** with an IMS Access Token. The simplest way to generate a token is by using the **@adobe/aio-sdk** library as demonstrated in the following example: + +```javascript +const {generateAccessToken} = require('@adobe/aio-sdk').Core.AuthClient; +const libDb = require('@adobe/aio-lib-db'); + +async function main(params) { + const token = await generateAccessToken(params); + const db = await libDb.init({token: token.access_token}); +} +``` + +This example has the following requirements: + +- The AIO project workspace must include the **App Builder Data Services** API. See [App Builder Data Services API](#app-builder-data-services-api) for details. +- The `include-ims-credentials` annotation for the runtime action must be set to `true` in the `app.config.yaml` application manifest. + +The `include-ims-credentials` annotation will look similar to the following example: + +```yaml + actions: + action: + function: actions/generic/action.js + annotations: + include-ims-credentials: true +``` + +The **@adobe/aio-sdk** library transparently manages caching and refreshing tokens as needed, so you do not need to implement caching or refreshing tokens yourself. + ### Region selection **aio-lib-db** must be initialized in the region the workspace database was provisioned. Otherwise, the connection will fail. -To explicitly initialize the library in a specific region, pass the `{region: ""}` arguement to the `libDb.init()` method. +To explicitly initialize the library in a specific region, pass the `{region: ""}` argument to the `libDb.init()` method. + +Called without an explicit region, `libDb.init()` will initialize the library either in the default `amer` region or in the region defined in the `AIO_DB_REGION` environment variable. + +### General use -Called with no arguments, `libDb.init()` will initialize the library either in the default `amer` region or in the region defined in the `AIO_DB_REGION` environment variable. +Using `aio-lib-db` in a runtime action is documented at [Runtime actions with Database Storage](./db-runtime-actions.md). ## Usage quotas and limits diff --git a/src/pages/guides/app_builder_guides/storage/db-commands.md b/src/pages/guides/app_builder_guides/storage/db-commands.md index b230348fb..39b87ab5f 100644 --- a/src/pages/guides/app_builder_guides/storage/db-commands.md +++ b/src/pages/guides/app_builder_guides/storage/db-commands.md @@ -18,11 +18,18 @@ The following is only a brief introduction to the DB Plugin. For more thorough d ## Installation -To install the pre-GA plugin for the AIO CLI: +The DB plugin for the AIO CLI requires `@adobe/aio-cli-plugin-app` version 14.5.1 or higher and `@adobe/aio-cli-plugin-app-storage` version 1.3.0 or higher. +These are install automatically by updating `@adobe/aio-cli` to the latest version: ```bash -aio plugins:install @adobe/aio-cli-plugin-app@next -aio plugins:install @adobe/aio-cli-plugin-app-storage@next +npm install -g @adobe/aio-cli +``` + +In case you installed the pre-GA plugin during early access, these should be uninstalled before updating `@adobe/aio-cli`: + +```bash +aio plugins:uninstall @adobe/aio-cli-plugin-app +aio plugins:uninstall @adobe/aio-cli-plugin-app-storage ``` ## Region selection diff --git a/src/pages/guides/app_builder_guides/storage/db-runtime-actions.md b/src/pages/guides/app_builder_guides/storage/db-runtime-actions.md index 6ec79646f..31ab6a9d3 100644 --- a/src/pages/guides/app_builder_guides/storage/db-runtime-actions.md +++ b/src/pages/guides/app_builder_guides/storage/db-runtime-actions.md @@ -19,17 +19,21 @@ Connecting to App Builder Database Storage is where `aio-lib-db` most differs fr The following is the general pattern for loading and using `aio-lib-db`: ```javascript -const libDb = require('@adobe/aio-lib-db') +const {generateAccessToken} = require('@adobe/aio-sdk').Core.AuthClient; +const libDb = require('@adobe/aio-lib-db'); -async function main() { +async function main(params) { let client try { + // Generate IMS access token + const token = await generateAccessToken(params); + // Implicit region initialization - const db = await libDb.init() - + const db = await libDb.init({token: token.access_token}) + // Explicit region initialization - // const db = await libDb.init({region: "emea"}) + // const db = await libDb.init({token: token.access_token, region: "emea"}) // Set up a connection client = await db.connect() @@ -57,8 +61,8 @@ async function main() { A few things to note in comparison with the MongoDB Node Driver: -- You do not need to specify connection credentials because they are taken from the runtime context, specifically the runtime namespace and auth. - You do not need to specify the database URL because all requests go through the App Builder Storage Database Service. +- Authentication depends on IMS Tokens, which requires setting the `include-ims-credentials` flag for the runtime action. See [Initialization and Authentication](./database.md#initialization-and-authentication) for details. - The library must be initialized in the same region the database was provisioned in. - There is no option to select a different database because there is always a one-to-one relationship between an AIO Project Workspace and Workspace Database. diff --git a/src/pages/guides/app_builder_guides/storage/index.md b/src/pages/guides/app_builder_guides/storage/index.md index b116ef2a5..e92868860 100644 --- a/src/pages/guides/app_builder_guides/storage/index.md +++ b/src/pages/guides/app_builder_guides/storage/index.md @@ -191,4 +191,6 @@ npm install @adobe/aio-lib-db aio app db provision ``` -No additional configuration is needed. The libraries automatically use your App Builder credentials for authentication and authorization. +For State and Files no additional configuration is needed. These libraries automatically use your App Builder credentials for authentication and authorization. + +The Database library does require some additional configuration, but does not require any special entitlements beyond App Builder itself. See the [App Builder Data Services API](./database.md#app-builder-data-services-api) documentation for details.