@adobe/aio-lib-db

• Web action — HTTP-invokable (

  web: "yes"

  ); returns a response built with the

  responses

  helpers from

  @adobe/aio-commerce-lib-core

  .
• Event/webhook action — invoked by a Commerce event or webhook; referenced from

  app.commerce.config.ts

  via

  commerce-app-eventing

  (

  runtimeActions

  ) or

  commerce-app-webhooks

  (

  runtimeAction

  ).

• Verify the app is scaffolded and initialized, not merely that the config exists. Require both:

  • app.commerce.config.ts

    present in the project root, and
  • the project initialized — signalled by the generated

    src/commerce-extensibility-1/

    directory and installed

    node_modules

    (the

    @adobe/aio-commerce-lib-app

    dependency).
• If

  app.commerce.config.ts

  is missing, stop and invoke

  commerce-app-init

  first (it writes the config, then runs init).
• If the config is present but the project is not initialized (no

  src/commerce-extensibility-1/

  or

  node_modules

  ), run

  npx @adobe/aio-commerce-lib-app init

  before continuing. Init is idempotent — it finds the existing config, skips the interactive prompts, installs dependencies, and generates the project files.
• Actions and custom installation scripts can be authored in TypeScript only once the project has the TypeScript build setup (

  webpack-config.cjs

  + root

  tsconfig.json

  ) that

  init

  scaffolds for a TypeScript Commerce config — see

  commerce-app-init

  . Otherwise, author them in JavaScript.
• The App Builder Data Services API (API code

  AppBuilderDataServicesSDK

  ) must be added to the project in the Adobe Developer Console — in every workspace that uses the database (no special license beyond App Builder). Without it, runtime actions cannot authenticate to the database service.

app.config.yaml

aio app deploy

application:
  runtimeManifest:
    database:
      auto-provision: true
      region: emea # amer | apac | emea | aus — the single source of truth for the region

aio app

aio-lib-db

aio app deploy

application

extensions

application

application

post-app-build

application:
  hooks:
    post-app-build: "mkdir -p dist/application/actions" # provisioning expects this dir to exist
  runtimeManifest:
    packages: {} # empty map — required by the config schema so the application block validates with no actions
    database:
      auto-provision: true
      region: emea # single source of truth — see the region callout below

aio app run

aio app dev

aio app db …

aio plugins install @adobe/aio-cli-plugin-app-storage
aio app db provision --region <amer|apac|emea|aus>

Region is a single source of truth. The

region

in the manifest

database

block must match the

region

passed to every

initDb({ region })

call (or

AIO_DB_REGION

) — in every action and in the install step (Step 6). A mismatch fails the connection. Changing region is destructive:

aio app db delete

, update

database.region

in the manifest, then re-provision.

• Action type: web action or event/webhook action (see the two shapes above).
• Collection name and the operations needed (insert / find / update / delete).
• Region: must match the manifest

  database.region

  (see the region callout in Step 1). Pass it to

  init()

  or set

  AIO_DB_REGION

  .

src/commerce-extensibility-1/ext.config.yaml

app-management

include-ims-credentials: true

is required on every DB action. Without it,

aio-lib-db

has no IMS token to authenticate with and the connection fails at runtime (and the app installation fails if the action runs during install). Do not omit this annotation.

undefined

defineCustomInstallationStep

install

uninstall

context.params

config

close

createIndex

// ./scripts/setup-database.ts — referenced from config as ./scripts/setup-database.ts
import { defineCustomInstallationStep } from "@adobe/aio-commerce-lib-app/management";
import {
  getImsAuthProvider,
  resolveImsAuthParams,
} from "@adobe/aio-commerce-lib-auth";
import { init as initDb } from "@adobe/aio-lib-db";

export default defineCustomInstallationStep({
  install: async (config, context) => {
    let client;
    try {
      // context.params carries the injected IMS credentials — NOT config.
      const authProvider = getImsAuthProvider(
        resolveImsAuthParams(context.params),
      );
      const token = await authProvider.getAccessToken();
      const db = await initDb({ token, region: "emea" }); // must match the manifest database.region
      client = await db.connect();

      const orders = client.collection("held_orders"); // get the collection object first
      await orders.createIndex({ order_id: 1 }, { unique: true }); // createIndex on the collection, not a name string
      return { status: "success" };
    } finally {
      if (client) await client.close(); // always close — avoids connection leaks
    }
  },
  uninstall: async (config, context) => {
    // Tear down your database state here.
    // Leave empty to preserve data across reinstalls.
  },
});

Author the install script as an ES module with

export default

— never

module.exports

. The installation action loads each step via

import * as step from "<script>"

and reads

step.default

, so the script must default-export the

defineCustomInstallationStep(...)

result. CommonJS breaks this:

module.exports.default

surfaces as

step.default.default

and validation fails. The

script

path must end in

.js

or

.ts

— author it directly in TypeScript, no separate compile step needed.

app.commerce.config.ts

installation.customInstallationSteps

script

.ts

// app.commerce.config.ts
installation: {
  customInstallationSteps: [
    {
      script: "./scripts/setup-database.ts",
      name: "Set up held-orders collection",
      description: "Creates the held_orders collection and a unique index on order_id",
    },
  ],
},

script

export default

.js

.ts

name

description

• Always close connections in a

  finally

  block — leaked connections exhaust resources.
• Match the region — the manifest

  database.region

  is the single source of truth; every

  init()

  call and the install step must use it (see the region callout in Step 1). A mismatch fails the connection silently from the caller's view.
• Use projections (

  .project({ field: 1 })

  ) and indexes (

  createIndex

  ) for frequently queried fields; index fields must total ≤ 2048 bytes.
• Iterate large result sets with cursors (

  for await (const doc of collection.find(...))

  ) instead of

  toArray()

  to bound memory.
• Don't hardcode the region or secrets — prefer

  AIO_DB_REGION

  and the injected IMS token over inline values.
• Prefer the most specific Adobe I/O library in runtime actions over the

  @adobe/aio-sdk

  umbrella — e.g.

  @adobe/aio-commerce-lib-auth

  for IMS auth and

  @adobe/aio-lib-core-logging

  for the logger — to keep action bundles small.
• Set up collections and indexes during installation with a custom installation step (

  defineCustomInstallationStep

  , see Step 6) rather than ad-hoc on the first request — it runs once when the app is installed from the Commerce Admin and is reversible on uninstall. A generic App Builder

  post-app-deploy

  hook is only an alternative when the app is not installed through App Management.

• Connection fails despite a valid token: the action is missing

  include-ims-credentials: true

  , or the App Builder Data Services API has not been added to the project in the Adobe Developer Console (see Prerequisites).
• DB not provisioned after

  aio app deploy

  (extension-only app): a bug in the

  aio app

  CLI plugin (not

  aio-lib-db

  ) skips declarative auto-provision when the

  application

  runtime manifest has no runtime action. Apply the extension-only workaround from Step 1 — add

  packages: {}

  and a

  post-app-build: "mkdir -p dist/application/actions"

  hook under

  application

  — or provision once with the CLI fallback for local dev.
• Connection fails after a region change: the library region doesn't match the manifest

  database.region

  . Moving regions is destructive —

  aio app db delete

  , update

  database.region

  in the manifest, then re-provision (

  aio app deploy

  , or the CLI fallback for local dev).
• Querying by

  _id

  from a string returns nothing: convert it first —

  new ObjectId(idString)

  from

  bson

  . A raw string never matches the stored

  ObjectId

  .

• DbError

  vs unexpected error: errors thrown by the service have

  name === "DbError"

  ; branch on it to separate database failures from application bugs.
• Auth fails inside an installation step: resolve the IMS auth params from

  context.params

  (

  resolveImsAuthParams(context.params)

  ) — which carries the injected

  AIO_COMMERCE_AUTH_IMS_*

  credentials — not from

  config

  , which holds no credentials. Use

  @adobe/aio-commerce-lib-auth

  , not

  @adobe/aio-lib-core-auth

  : the latter's

  generateAccessToken

  expects

  clientId

  /

  clientSecret

  directly and cannot consume the injected params.
• Installation step fails to load (

  must export a default function or object

  ): the script was authored as CommonJS. Author it as an ES module with

  export default

  ;

  module.exports

  (or

  module.exports.default

  ) surfaces through the framework's

  import * as

  loader as

  .default.default

  and fails validation.

• createIndex

  errors or has no effect: it must be called on a collection object (

  client.collection("name").createIndex({ field: 1 })

  ), not with a collection-name string. Get the collection first, then call

  createIndex

  on it.

• aio app build

  completes without errors
• Every user-authored DB action declares

  include-ims-credentials: true

  in its annotations
• The action closes the client in a

  finally

  block and initializes the library in the region declared in the manifest

  database

  block

• Wire the action to an event — invoke

  commerce-app-eventing

  and reference this action in an event's

  runtimeActions

  .
• Wire the action to a webhook — invoke

  commerce-app-webhooks

  and reference this action via

  runtimeAction

  .
• Trigger the action from Admin UI — invoke

  commerce-app-admin-ui

  to add a mass action, order view button, or grid column that invokes this runtime action.

• assets/db-action.ts — Full annotated handler: init/connect, CRUD, cursor iteration, and the close lifecycle
• assets/setup-database.ts — Full annotated custom installation step: install creates a collection and a unique index, uninstall drops it, with the

  context.params

  and

  createIndex

  -on-collection patterns