Configuration

Control how much memory a database gets, when it stops and archives, and how much storage it can use. Configuration can be set per-database, per-scope, or via reusable templates at the organization level.

Database settings

Each database has these configurable settings:

Setting	What it controls	Default
memory_mb	Memory allocated to the database when active	1 MB (Redis/SQL), 64 MB (Graph)
memory_percent	Memory as a percentage of database size (alternative to fixed MB)	From org config
idle_timeout_secs	Seconds of inactivity before the database stops (frees memory)	300 (5 minutes)
sleep_timeout_secs	Seconds after stopping before the database archives to cold storage (frees disk)	86400 (24 hours)
max_storage_mb	Maximum storage the database can use	Based on your plan

Set these when creating a database:

from cinchdb import Cinch

client = Cinch(api_key="ck_live_...", org="acme")
scope = client.scope("my-app", environment="production", project="api")

# Create a database with custom settings
db = scope.create_database(
    type="redis",
    name="high-memory-cache",
    memory_mb=256,              # 256 MB memory allocation
    idle_timeout_secs=600,      # stop after 10 minutes idle
    sleep_timeout_secs=3600,    # archive after 1 hour idle
)

Lifecycle recap

Active: database is in memory, serving requests at ~1.4ms. After idle_timeout_secs, it stops (frees memory, stays on disk, ~10ms to wake). After sleep_timeout_secs, it archives to cold storage (frees disk, ~25ms to wake).

Config templates

Instead of setting memory and timeouts on every database, you can create reusable config templates at the organization level. Assign a template to a database and it inherits the settings.

# Create a database using an org-level config template
db = scope.create_database(
    type="redis",
    name="cache",
    database_config_id="high-performance",  # org-level template
)
# memory_mb, idle_timeout_secs, etc. come from the template

Templates can be type-specific (only for Redis, or only for Graph databases) or generic. When a template is assigned, its settings override any inline values.

Template field	Description
database_type	Optional. Restrict to redis, sql, graph, or bucket.
memory_percent	Memory as percentage of database size.
min_memory_mb	Floor for memory allocation.
idle_timeout_secs	Idle timeout before stopping.
sleep_timeout_secs	Sleep timeout before archiving.

How settings resolve

When Cinch needs a setting (like memory or idle timeout), it checks in order:

Database-level inline value (highest priority)
Database-level config template
Environment-level config
Project-level config
Organization type-specific config (e.g. "all Redis databases")
Organization default config
System defaults (lowest priority)

This means you can set org-wide defaults and override them at any level. For example, set a 10-minute idle timeout for all databases in your org, but override it to 1 hour for your production cache.

Scope configs (experimental)

Scope configs let you define a schema template that scopes inherit. When you create a new scope with a scope config, it can automatically set up the right database primitives (Redis, SQL, Graph) with the right schema.

Scope configs are versioned and immutable. Each update creates a new version. The system tracks which scopes are on which version and can run migrations to bring them up to date.

Experimental

Scope configs and managed migrations are in active development. The API may change. Use config templates (above) for production workloads today.

See the Python SDK or TypeScript SDK docs for the full configuration API.