import { setup } from '@backtest-kit/pg';
setup({
  CC_POSTGRES_CONNECTION_STRING: 'postgres://backtest:secret@postgres:5432/mydb',
  CC_REDIS_HOST: 'redis', CC_REDIS_PORT: 6379, CC_REDIS_PASSWORD: 'secret',
});

Values passed to setup() / setConfig() always take precedence over env vars. Within the CLI, put setup() in config/setup.config.ts — when present, the CLI skips its default file-adapter registration and your config owns persistence.

• Candle is immutable — first write wins; subsequent writes to the same (exchangeName, symbol, interval, timestamp) are silently ignored via a no-op DO UPDATE that never touches the OHLCV columns (historical OHLCV never changes).
• All others use DO UPDATE SET payload = EXCLUDED.payload — each write replaces the previous value.
• Measure / Interval / Memory soft-delete — removeMeasureData / removeIntervalData / removeMemoryData set removed = true rather than deleting; listings filter on removed = false, keeping a full audit trail.

Every domain is two layers: a DbService (PostgreSQL) and a CacheService (Redis). Reading state for a context key asks Redis for the Postgres id first; a hit is two O(1) ops, a miss falls back to an indexed findOne and backfills Redis.

read signal for (BTCUSDT, my_strategy, binance)
  ├─ Redis GET → hit  → Postgres findByFilter({ id })   ← O(1) + O(1)
  └─ Redis GET → miss → Postgres findByFilter(filter) → Redis SET → return

After every write the Redis entry is refreshed in the same call, so write-then-read always hits the cache.

backtest-kit requires that once write*Data() returns, the next read*Data() sees the new value. Every write is one INSERT … ON CONFLICT … RETURNING round-trip:

const { raw } = await repo
  .createQueryBuilder()
  .insert()
  .values({ symbol, strategyName, exchangeName, payload })
  .orUpdate(["payload"], ["symbol", "strategyName", "exchangeName"])
  .returning("*")
  .execute();
await signalCacheService.setSignalId(raw[0]);

The conflict target matches the unique compound index, so PostgreSQL serializes any concurrent duplicate insert at the storage engine — the loser takes the DO UPDATE branch instead of throwing; the returned row is written straight to Redis, making the next read O(1) on fresh data.

Adapters whose data influences decisions (Risk, Partial, Breakeven, Recent, State, Budget, Session, Memory, Interval) store when: bigint — the simulation timestamp in ms — alongside the payload, so backtest-kit can verify no read returns data written at a future simulation time. Measure is exempt because it caches LLM / external-API responses, where look-ahead bias is not meaningful.

Public surface — functions/setup.ts (setup/install/setLogger), config/params.ts (setConfig/getConfig), index.ts re-exports + getPostgres/getRedis.

Adapter classes (classes/Persist*Instance.ts, 17) — each implements one backtest-kit IPersist*Instance contract and delegates to its domain DbService: PersistCandleInstance, PersistSignalInstance, PersistStrategyInstance, PersistScheduleInstance, PersistRiskInstance, PersistPartialInstance, PersistBreakevenInstance, PersistStorageInstance, PersistNotificationInstance, PersistLogInstance, PersistMeasureInstance, PersistIntervalInstance, PersistMemoryInstance, PersistRecentInstance, PersistStateInstance, PersistBudgetInstance, PersistSessionInstance.

Service layer (lib/services/):

• base/ — PostgresService (lazy TypeORM DataSource), RedisService (lazy ioredis), LoggerService.
• db/ — one *DbService per domain: the TypeORM entity schemas, unique compound indexes, and INSERT … ON CONFLICT … RETURNING upsert logic.
• cache/ — one *CacheService per domain (CandleCacheService, SignalCacheService, BreakevenCacheService, IntervalCacheService, LogCacheService, MeasureCacheService, MemoryCacheService, NotificationCacheService, PartialCacheService, RecentCacheService, …): Redis id mapping for O(1) lookups.

Shared primitives (lib/common/) — BaseCRUD (the upsert/read/remove pattern every DbService reuses) and BaseMap (the Redis key-mapping pattern every CacheService reuses).

DI & config — lib/core/{di,provide,types}.ts (IoC container wiring Db/Cache/base services), lib/index.ts (container bootstrap), config/{postgres,redis,params}.ts (connection builders + merged params), interfaces/Logger.interface.ts.