README
¶
Progressive usage examples
These programs use the sqlc-generated internal/sharded account package and
the internal/one unsharded settings package, building from the simplest
deployment to the full runtime topology.
Account commands are accessed through the generated Accounts() group,
tenant reports through Reports(), and settings through Settings(). Helper
functions use narrower generated reader and writer interfaces where
appropriate.
| Example | Topology | Features |
|---|---|---|
01-single-database |
One PostgreSQL database | Generated Store with a Singleton topology |
02-read-write-split |
One primary and one or more replicas | The same Store, replica reads, round-robin selection, strong reads |
03-sharded-read-write |
Two physical shards, each with a replica | One Store with Accounts and Reports groups, virtual shards, separate settings store |
04-mirrors-and-transactions |
Two sharded primary/replica sets plus future-shard mirrors | Staged shard-expansion dual writes, primary-pinned transactions, mirror suppression in transactions |
The source schema and annotated queries are in sqlc. The examples
have their own justfile, which uses the repository's pinned sqlc
version. From the module root, regenerate the shared package with:
cd examples
just generate
Every program reads DSNs from environment variables. Apply sqlc/schema.sql
to each database before running one. For example:
SINGLE_DATABASE_DSN='postgres://user:pass@localhost/accounts?sslmode=disable' \
go run ./examples/01-single-database
Replica examples assume PostgreSQL replication is configured outside this
library. A write followed immediately by a default replica read can therefore
observe normal replication lag; use the generated ReadFromPrimary() option
when read-your-write consistency is required.
just verify starts the module's local PostgreSQL topology and runs all four
programs as smoke tests after the integration suite. For the read/write-only
smoke test, the same local endpoint is used as both primary and replica; the
dedicated integration tests separately prove selection across distinct read
endpoints.
Directories