Database Clusters

Database clusters are the core of CredVault. A cluster is the user's isolated database workspace: collections, documents, API access, rules, functions, backups, scaling, maintenance, and monitoring all attach to a cluster.

Where Users Manage Clusters

How A Cluster Works

When a user creates a cluster:

1. CredVault validates the user's tenant and billing state.
2. The backend stores cluster metadata.
3. The platform creates database access details.
4. The dashboard shows the cluster in /cluster.
5. Collections and documents can be managed through /cluster/{clusterId}.
6. API keys can be scoped to the cluster for application access.

Collections And Documents

Collections and documents are managed through the data routes:

Test It In The API Explorer

Open /api-docs, authorize, then run:

GET /api/clusters
GET /api/data/clusters/{clusterId}/collections
GET /api/data/clusters/{clusterId}/collections/{collectionName}/documents

What you should see: the explorer should show an HTTP status, request URL, response headers, and a JSON response. A successful cluster request returns the clusters your account can access. If you are not logged in or your token is wrong, you should see an authentication error.

You can also test with curl:

curl https://credvault-production.up.railway.app/api/clusters \
  -H "Authorization: Bearer <your-session-token>"

What you should see: a JSON list of clusters, or an empty list if your account has not created one yet.

Create a collection:

curl -X POST https://credvault-production.up.railway.app/api/data/clusters/<clusterId>/collections \
  -H "Authorization: Bearer <your-session-token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"customers"}'

What you should see: a success response confirming that the customers collection exists. If the collection already exists, the API should return a clear conflict or validation message.

Insert a document:

curl -X POST https://credvault-production.up.railway.app/api/data/clusters/<clusterId>/collections/customers/documents \
  -H "Authorization: Bearer <your-session-token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada","plan":"team","active":true}'

What you should see: a JSON response with the inserted document or document ID. After that, the same record should appear in the dashboard collection view.

SQL Through LakeVault

CIE exposes a SQL route for authenticated users:

cie sql "SELECT name, plan FROM customers WHERE active = true LIMIT 20"

Behind the scenes, the backend receives:

POST /api/cie/sql

The SQL engine translates supported SQL into database operations. Read queries return rows. Write queries are audited.

Security Around Clusters

Cluster APIs are protected by:

• User authentication
• Tenant access checks
• Cluster access checks
• IP allowlist enforcement on sensitive paths
• Activity logging for create, update, delete, pause, unpause, scale, credential rotation, and maintenance actions
• Credit and account-lock middleware before API usage

Performance Features

CredVault exposes the building blocks users expect in a managed database platform:

• Collection-level document operations
• Query pagination
• Cluster stats
• Scaling routes
• Maintenance windows
• Backup settings
• Credential rotation
• Activity tracking

What To Document In Runbooks

For production users, document:

• Cluster naming convention
• Which API keys can access the cluster
• Backup schedule
• Maintenance window
• Scaling policy
• IP allowlist
• Rotation schedule for credentials
• Owner responsible for cost and usage