BTST Database Adapters: Check Transaction Support Before Choosing

An adapter can connect to your database and still be unsuitable for a particular plugin operation. Before selecting a BTST adapter, check both the ORM you already use and the transaction behavior required by the plugins you plan to enable.

BTST 3.0.2 separates the core stack from its database adapters. The adapter translates the merged plugin schema and data operations into the chosen ORM or driver. It does not make every database configuration support the same guarantees. Start with the database adapter reference.

Match the existing data stack#

Choose the provider setting that matches the actual connection, then verify your plugin set against that adapter. A package appearing in this table means an adapter exists; it does not establish support for every plugin on every database topology.

Reusing the application's ORM usually avoids introducing another connection and migration system solely for BTST. The memory adapter is useful for disposable local work, but its process-local data and execution model should not be treated as a production database substitute.

Check atomic-write requirements#

AI Chat, Form Builder, Kanban, and Media include operations that need isolated transactions. An operation may read ownership or record state, authorize against those facts, invoke lifecycle behavior, and write a change. Those steps need a consistent transaction boundary when the operation requires it.

The released documentation requires transaction: true for the relevant Prisma, Drizzle, or Kysely adapter configuration. The 0.2.1 generator adds that option when one of those four plugins is selected. The flag enables the adapter's transaction implementation; it does not add a capability that the underlying connection lacks.

For example, this is the adapter configuration fragment for an existing Prisma PostgreSQL connection. prisma is your initialized Prisma client, and db is the merged schema passed by createBackendStack:

adapter: (db) => createPrismaAdapter(prisma, db, {
  provider: "postgresql",
  transaction: true,
})({})

Keep the import from @btst/adapter-prisma and use the provider for your actual database. See the adapter examples for complete stack initialization and equivalent Drizzle and Kysely configuration.

Understand the generated compatibility limits#

The released scaffold rejects Form Builder with the memory or native MongoDB adapter. It also rejects Media with the native MongoDB adapter. That is a concrete generator boundary, not a statement that MongoDB as a database can never support transactions.

The release's scaffold configuration records those combinations. Do not remove the check to make generation succeed. Choose a supported configuration for the desired plugins, or investigate a custom integration with evidence for every required operation.

Likewise, a combination that passes generation still needs runtime verification. A working read page does not prove that ownership-sensitive moves, submissions, or file operations have the required isolation.

Treat the transaction error as a capability signal#

ATOMIC_TRANSACTION_REQUIRED indicates that the operation did not find the required isolated transaction support. Check the adapter option, installed adapter version, driver, and connection configuration before changing application permissions.

The affected operations are designed to fail before lifecycle hooks or writes when that capability is missing. Replacing an isolated transaction with a callback that executes statements sequentially is not an equivalent fix. A partial write or a stale ownership decision can survive such a substitution.

In a disposable database, exercise one representative write from each installed plugin. Include a rejected operation and verify that it leaves the intended records unchanged. Where concurrent edits matter, test two conflicting requests as well as the successful single-request path. The Kanban persistence guide explains a concrete example involving task movement and board state.

Keep schema generation and migration distinct#

Selecting an adapter does not create production tables. BTST combines the enabled plugins' schema definitions; the tooling then generates the ORM schema or migration inputs for your chosen setup. Review the generated change and apply it using the application's normal migration process.

Avoid mixing sample credentials, local memory data, and the production connection while checking generation. The CLI reference covers the schema workflow. A complete adapter evaluation should establish that the schema can be applied, ordinary reads work, required writes are atomic, and data persists across the deployment model you intend to use.