Episode 3 used State to remember which orders had already triggered an alert. That's the right tool for a flag with a time to live. It's the wrong tool for a sync log you want to search ("show me every failed export for SKU X this week"), because State only answers "what's the value of this key?". An Adobe Commerce (Magento 2) module would have created a table. App Builder now has its own answer: Database Storage, a document database for Runtime actions.
On one Mirakl to Adobe Commerce warehouse sync, my module kept a custom table of last-sync dates. Database Storage covers that table, and it could hold the synced records as well, not only the dates.
State, Database Storage, or neither
| Need | Use |
|---|---|
| A flag, a lock, a cursor or a cache entry with a time to live | State (aio-lib-state). Values up to 1 MB, keys up to 1,024 bytes, time to live up to 365 days |
| Records you query by field, update in place, or keep without expiry | Database Storage (aio-lib-db) |
| Large files, exports, reports | Files (aio-lib-files) |
| Data another system owns (orders, products, customers) | Neither. Read it from that system's API |
Database Storage is a document store. Its client library is modelled on the MongoDB Node.js driver, and Adobe's App Builder docs say it's backed by AWS DocumentDB. It's not a relational database, and it's completely separate from the Commerce database. Each workspace has its own isolated database, so Stage and Production are two separate databases.
You’ll need
- The project from the earlier episodes, with the latest CLI:
npm install -g @adobe/aio-cli - In Developer Console, the App Builder Data Services API added to your workspace (the I/O Management API is optional)
- The OAuth server-to-server credential for that workspace, with a new access token generated after adding the API
Provision the database in app.config.yaml
Each workspace gets one database in one region: amer (the default), emea, apac or aus. Pick the region closest to your Commerce instance, because moving it later means deleting and reprovisioning.
application:
runtimeManifest:
database:
auto-provision: true
region: emea
Auto-provisioning happens on aio app deploy, not on aio app run or aio app dev. To do it by hand instead, run aio app db provision --region emea. That command also writes a database block for you, with auto-provision: false and the region. Either way, the provisioning step writes app.config.yaml back as plain YAML and every comment in the file is lost, on the first aio app deploy that provisions as well. Commit first and check git diff afterwards.
aio app db status
aio app db ping
Get the auth right first
This is where most first attempts fail. The library needs an IMS token, and the action only receives credentials to create one if you ask for them. Add the annotation to every action that uses the database:
actions:
sync-log:
function: actions/sync-log/index.js
runtime: nodejs:20
annotations:
include-ims-credentials: true
final: true
Tip: If init fails with an authorisation error, check three things in order. Is the Data Services API on the workspace? Was a new access token generated after you added it? Is the annotation on this action?
Write and read from an action
Install the library with npm install @adobe/aio-lib-db. Then connect, use a collection, and always close the client in finally.
const { Core } = require('@adobe/aio-sdk')
const libDb = require('@adobe/aio-lib-db')
async function main (params) {
const logger = Core.Logger('sync-log', { level: params.LOG_LEVEL || 'info' })
let client
try {
const token = await Core.AuthClient.generateAccessToken(params)
const db = await libDb.init({ token: token.access_token, region: 'emea' })
client = await db.connect()
const runs = await client.collection('export_runs')
await runs.insertOne({
sku: params.sku,
status: params.status,
error: params.error || null,
at: new Date().toISOString()
})
const [failed = null] = await runs.find({ sku: params.sku, status: 'failed' }).sort({ at: -1 }).limit(1).toArray()
return { statusCode: 200, body: { lastFailure: failed } }
} catch (e) {
logger.error(e.message)
return { statusCode: 500, body: { error: e.name === 'DbError' ? 'database error' : e.message } }
} finally {
if (client) await client.close()
}
}
exports.main = main
The region passed to init must match the provisioned one.
findOne with no match
The snippet uses find with limit(1), which gives an empty array when nothing matches. findOne behaves differently: on aio-lib-db 1.1.0 it throws a DbError ("Document not found") instead of returning null. If you use it, catch that error and treat it as null, as episode 10 does.
Create indexes on deploy, not by hand
Queries by sku and status need an index once the collection grows. Put index creation in a post-deploy hook, so every workspace gets the same indexes:
application:
hooks:
post-app-deploy: node scripts/post-deploy-db-setup.js
The script runs after aio app deploy, reads the workspace's OAuth credentials from .env, and calls createIndex. If an index already exists, it skips it. Check the result with:
aio app db index list export_runs
Tip: The indexed fields of one document can't exceed 2,048 bytes combined. Index the SKU, not the error message.
Look inside without writing code
The CLI covers what you'd otherwise do in a database client:
aio app db collection list
aio app db document find export_runs '{}'
aio app db document count export_runs
aio app db stats
document find returns 20 documents by default, and 100 at most. Run aio app db document find --help for the filter options in your CLI version. It's for checking, not reporting.
Decide what not to store
Every record you keep is data you have to protect, and Stage and Production can't be merged later. Keep IDs, statuses and timestamps. Look up customer and order details from Commerce when you need them, instead of copying them into the database.
Tested on: a real Stage workspace. There aio app deploy provisioned the database in emea, the post-deploy hook created its indexes with the workspace's OAuth credential, and an action with include-ims-credentials wrote and read documents. The sync-log action, invoked by hand, inserted a row and returned it, and answered 400 when sku was missing. One thing the real run caught: aio app use writes IMS_OAUTH_S2S_SCOPES into .env as a JSON array and the namespace as AIO_runtime_namespace, while the first version of the hook expected a comma list and AIO_RUNTIME_NAMESPACE. The hook now accepts both.
Not tested: see the current list in the repo README.
Done!
Your sync log now lives in a database you can query. Episode 5 sends the actions' logs somewhere your team already looks: New Relic.
