Repositories
Cleave connects transactional resources to operational repositories through configured repository adapters.
The public resource interface should stay stable, but the repository adapter owns important differences such as UUID representation, binary values, placeholders, pagination syntax, and upsert syntax.
Choose a repository
Choose a server build containing the adapter you need. Applications use Cleave's resource API while each adapter handles its repository's native operations.
MySQL and MariaDB
Use mysql for MySQL and compatible MariaDB deployments. Configure a database
account for the application's resources and use port 3306 unless your deployment
specifies another port. UUID identities use BINARY(16) storage.
[dbms]
adapter = "mysql"
writer_endpoint = "mysql:3306"
reader_endpoint = "mysql:3306"PostgreSQL
Use postgres for PostgreSQL. Its native uuid type stores resource identities;
applications continue to use the same resource IDs and request conventions.
The standard PostgreSQL port is 5432.
[dbms]
adapter = "postgres"
writer_endpoint = "postgres:5432"
reader_endpoint = "postgres:5432"MongoDB
Use mongodb for MongoDB collections. The adapter handles document operations
behind Cleave's resource interface. Configure the application database and the
authentication database appropriate to your MongoDB account. The standard port
is 27017.
[dbms]
adapter = "mongodb"
writer_endpoint = "mongo:27017"
reader_endpoint = "mongo:27017"
mongo_auth_source = "admin"
These snippets show adapter selection and endpoints, not complete configurations. Add the repository username, password, database, and address settings described in Deployment: Repository Network Access. The hostnames above are example Docker service names; use the names reachable from your Cleave service.
Reader and writer access
Cleave distinguishes reader and writer repository access:
[dbms]
writer_endpoint = "writer.example.internal:5432"
reader_endpoint = "reader.example.internal:5432"
[dbms.pool]
writer_min_size = 1
writer_max_size = 10
reader_min_size = 1
reader_max_size = 20
This PostgreSQL example allows more reader than writer connections. Choose pool limits alongside the repository's connection budget, rather than treating these values as a universal recommendation.
GET operations use reader access. POST, PUT, PATCH, and DELETE use writer access.
This lets operators tune read-heavy and write-heavy services differently. A public catalog API, internal administrative tool, and write-heavy system of record may need different pool sizes, endpoints, timeouts, and repository topology.
Value binding
[dbms]
value_binding = "parameterized"
Unlike traditional applications, where SQL is often constructed across numerous endpoints, Cleave centralizes query generation into a single, validated pipeline. Clients submit structured filters, sorting, and relationship requests, not raw SQL, which are translated into database-specific queries by the repository layer.
Prepared statements remain the recommended implementation for parameter binding and performance, but they serve as the final safeguard within an architecture that substantially reduces the opportunity for SQL injection by design.
inline and parameterized value-binding modes sit behind this validation and compilation
pipeline. The request is parsed, checked, and converted into repository operations before the
adapter decides how values are represented for the selected repository.
Repository boundaries
Cleave does not expose SQL to clients. Clients express resource requests; Cleave validates resource names, field names, operators, values, page limits, JWT claims, and ACL rules before constructing repository operations.
Repository-specific behavior remains visible where correctness requires it:
- UUID storage and conversion;
- binary storage and conversion;
- upsert behavior;
- pagination syntax;
- supported connection pool behavior;
- transaction and locking semantics;
- indexing requirements.
Do not assume that a schema tuned for one repository will automatically behave the same way on another repository.

