Partitions and transactions.

Partitions and resizing

A named partition is a separate database (its own bundle, data, timers and retry receipts) that you can move between Raft groups. Several partitions share one group.

• Choose partitions when you create a database. Data in the default database can't be turned into a partition later.
• A partition can't read another partition's data directly. A transaction can call exposed methods in several partitions at once.

import { FlowerAdmin, FlowerClient } from "@flower-js/sdk/client";
import { buildBundle } from "@flower-js/sdk/bundle";

const admin = new FlowerAdmin("http://catalog-1:7101", { adminToken: process.env.FLOWER_ADMIN_TOKEN });
await admin.registerGroup({ id: "west", addresses: ["west-1:7101", "west-2:7101", "west-3:7101"] });
await admin.registerGroup({ id: "east", addresses: ["east-1:7101", "east-2:7101", "east-3:7101"] });
await admin.createPartition("tenant-a", "west", { requestId: "create-tenant-a" });
await admin.waitForPartition("tenant-a");
await admin.partition("tenant-a").deploy(await buildBundle("app.ts"), { requestId: "deploy-tenant-a" });
const tenant = new FlowerClient("http://catalog-1:7101").partition("tenant-a"); // Calls its exposed methods.
await admin.resize(["west", "east"], { requestId: "grow-two-groups" });
console.log(await admin.layout()); // Durable progress; resize continues after this client exits.

Running partitions

Configure every server with:

• FLOWER_GROUP: this server's group.
• FLOWER_CATALOG_GROUP: the group that stores placements.
• FLOWER_GROUPS: JSON map of group IDs to host:port lists, including this group and the catalog.
• The same peer secret everywhere, and a separate operator token.

Initialize each group on its own. Put applications in named partitions, not the catalog's default database.

During a move

• The source keeps serving while it copies, then briefly freezes to send the final changes. Writes either land before the freeze or fail; none are lost.
• The freeze can take longer for large partitions or slow networks. It is not guaranteed to be milliseconds.
• If a group loses quorum after the freeze, the move pauses until it recovers.
• Pending cross-group transactions delay the freeze.
• Live watches end with an error when the owner changes. Reconnect through the partition client; there's no automatic replay.
• Other partitions on the same group keep working but share CPU, disk and the Raft log.

Cross-group transactions

A transaction method calls exposed methods in several partitions or groups and commits them all or none. The methods guide has a complete example.

• Check business rules inside the participant methods. Later calls to the same target see earlier ones.
• If a participant fails, nothing commits and the caller gets 422 TRANSACTION_ABORTED with that participant’s failure. It is final for that request ID; fix the problem and use a new ID.
• Participants are authorized with the coordinator’s principal; see delegation.
• While a transaction is prepared, each participating database blocks fresh reads, watches, writes, deploys and maintenance, even for unrelated keys. Other partitions on the same group are unaffected.
• Replica-local reads may not see the transaction atomically.
• If the coordinator is unreachable, participants stay blocked until it recovers. Nothing times out on its own.
• TRANSACTION_PREPARED: wait for recovery and retry with the same ID and content.
• Completed transaction records are cleaned up only by operator action; see retry retention and transaction closure.
• Every participant needs FLOWER_GROUP, FLOWER_GROUPS and the shared peer secret; named partitions also need FLOWER_CATALOG_GROUP.

Full protocol: transactions and recovery.