README.md

cache-pg — feature cookbook

Exhaustive, example-driven reference for every exported identifier in github.com/ubgo/cache-pg (package pgcache).

Import path:

import pgcache "github.com/ubgo/cache-pg"

pgcache.Cache implements cache.Cache over the standard library database/sql, targeting Postgres 14+ in production and SQLite for in-process tests. It passes the shared cachetest.Run suite.

Pages

• Construction & options — New, WithDialect, WithTable, WithClock, the Cache/Option/Dialect types and the Postgres/SQLite constants.
• Schema operations — Migrate, Vacuum.
• Cache methods — every cache.Cache method and its exact SQL.

Capability matrix

Exported symbol	Kind	SQL behavior	Page
New	constructor	wraps a *sql.DB	Construction
Cache	type	the adapter	Construction
Option	type	functional option	Construction
Dialect	type	placeholder/DDL selector	Construction
Postgres	const	$1 placeholders (default)	Construction
SQLite	const	? placeholders	Construction
WithDialect	option	select dialect	Construction
WithTable	option	table name (default cache_entries)	Construction
WithClock	option	time source (tests)	Construction
Migrate	method	CREATE TABLE/INDEX IF NOT EXISTS	Schema
Vacuum	method	DELETE expired rows	Schema
Get	method	SELECT … WHERE key=$1 AND not-expired	Cache methods
GetMulti	method	per-key Get loop	Cache methods
Has	method	Get + not-found check	Cache methods
TTL	method	SELECT expires_at	Cache methods
Set	method	INSERT … ON CONFLICT DO UPDATE	Cache methods
SetMulti	method	upserts in one tx	Cache methods
SetNX	method	tx: delete-expired then INSERT … DO NOTHING	Cache methods
Expire	method	UPDATE expires_at	Cache methods
Touch	method	Expire 1h	Cache methods
Incr / Decr	method	tx select+upsert, 8-byte int64	Cache methods
Del	method	per-key DELETE	Cache methods
DeleteByPrefix	method	DELETE … LIKE $1 ESCAPE '\'	Cache methods
Flush	method	DELETE FROM table	Cache methods
Iterate	method	SELECT … ORDER BY key	Cache methods
Ping	method	db.PingContext	Cache methods
Close	method	marks closed only	Cache methods
Stats	method	live COUNT(*) → Entries	Cache methods

There are no ErrUnsupported cases — the SQL adapter serves the full contract. Expired rows are filtered on every read, so Vacuum is purely space reclamation, never a correctness concern.