Understanding Buckets

Buckets and PostgreSQL Schemas Explained

At a technical level, a bucket in Formance is directly mapped to a PostgreSQL schema. To fully understand what this means, let’s break it down:

What is a PostgreSQL Schema?

In PostgreSQL, a schema is a namespace that groups together database objects (such as tables, views, indexes, and functions). Think of it as a logical folder inside a single database:

• Without schemas, all tables would live in one big global namespace, which could quickly become messy.

• With schemas, you can organize and separate data logically, avoid name collisions, and apply different permissions.

Two tables with the same name can exist in different schemas

Both are valid because they live under different schema namespaces.

How Formance Uses Schemas as Buckets

When you create a ledger, Formance stores its data inside a PostgreSQL schema (the bucket). In v2, Ledgers default to the name "_default", you can specify a different one upon ledger creation.

This has several implications:

• Isolation: Each bucket/schema provides a clean separation of ledger data. Two ledgers in different buckets won’t share tables, which reduces the risk of accidental data mixing.

• Shared storage within a bucket: Multiple ledgers inside the same bucket share the same underlying tables, which can be efficient but means their data is less isolated.

• Scaling strategy: By using multiple buckets, you can spread data across different schemas to avoid a single schema growing too large and becoming a performance bottleneck.

System Schema

Formance also uses a special internal schema called _system. This schema tracks metadata about your ledgers and buckets.

Practical Considerations

• Data Isolation: Buckets are a good fit if you need strong separation (e.g., per-tenant ledgers in a multi-tenant system).

• Performance Management: For high-volume workloads, spreading ledgers across multiple buckets can reduce contention and keep queries fast.

• Simplicity: If isolation isn’t critical, sticking with the _default bucket keeps things straightforward.