Repository navigation
tellus-persistence-postgres-v0.3.0
Release notes
migrate records its migrations in a table of its own
PostgresStore::migrate records what it has applied in _tellus_persistence_migrations instead of
sqlx's shared _sqlx_migrations, so the store and an application's own sqlx migrations can share a
database. In a database which 0.2.14 or earlier has migrated, the old row stays in
_sqlx_migrations. It does no harm: migrate no longer reads that table.
If the application adds its own sqlx migrator to such a database, remove that row first, or the
migrator fails with VersionMissing(1) or VersionMismatch(1). The statement which removes it, and
when it is safe to run, are under
Usage.
The store's tables are now tellus_events and tellus_snapshots
The tables were called events and snapshots. An application sharing the database may have a
table of such a name itself. migrate then left that table as it was and reported success, and the
store failed at its first statement against that table. With the new names migrate also no longer
adopts a table: it fails if tellus_events or tellus_snapshots exists and it has not created it.
0.3 does not read the old tables. In a database which 0.2.14 or earlier has migrated, the events
and snapshots stay in events and snapshots until they are moved. To move them, stop every
process which uses the store, those of the earlier release too. Then call migrate of 0.3, which
creates the two new tables next to the old ones, and run these statements before any process uses
the store again:
BEGIN;
INSERT INTO tellus_events SELECT * FROM events;
DROP TABLE events;
INSERT INTO tellus_snapshots SELECT * FROM snapshots;
DROP TABLE snapshots;
COMMIT;An application which calls migrate at its start needs a run which stops after it. Started without
the move, it finds every entity empty. What it then persists for an entity of the old tables makes
the copy fail, and the old tables stay as they are.
An application which created the two tables itself renames them with the tool which manages its
schema. It no longer calls migrate, which had adopted them. The definition with the new names is
under
Schema
in the README.
Bound the pool's calls below tellus's store timeout
tellus now bounds every store call by the timeout of Persistence, 10 s by default, and gives up
on a call which exceeds it by dropping it. A dropped call does not end a statement which has
reached PostgreSQL. sqlx sends no cancel request, so the statement runs on and keeps its pool
connection, and a dropped append can still commit after the actor's next incarnation has replayed.
The next append of that actor then conflicts and fails its command.
Configure the pool to bound its calls itself: a statement_timeout on its connections, for example
through PgConnectOptions::options, and an acquire timeout through
PgPoolOptions::acquire_timeout. Keep the acquire timeout plus twice the statement timeout below
the Persistence timeout, with room for the network round trips. The statement timeout does not
count the wait for a connection, and it can count twice. sqlx prepares a statement on its first use
on a connection in a separate round trip which ends with a Sync. PostgreSQL cancels the statement
timeout when that Sync completes and starts it again with the Bind which follows. sqlx's default
acquire timeout, 30 s, is above tellus's default. Neither the statement timeout nor
transaction_timeout covers the commit which ends a statement, so an append which fails while it
commits stays ambiguous. The README shows the configuration under
Usage,
and its new section
Timeouts
explains it and what stays ambiguous.
A shutdown of an event-sourced actor now waits for an append under way at most the Persistence
timeout, where it used to wait until the append settled.
This release requires tellus 0.6
PostgresStore implements tellus::EventStore and tellus::SnapshotStore, so the tellus it is
built against is part of this crate's API. This release depends on tellus 0.6, and its
PostgresStore cannot back an event-sourced actor of tellus 0.5. Upgrade tellus to 0.6 together
with this crate.
Changelog
Features
- (persistence) [breaking] Bound every store call by a timeout (#409)
- Add stashing, opt-in per actor via Actor::Stash (#201)
Bug Fixes
- (postgres) [breaking] Rename the store's tables so they cannot collide (#328)
- [breaking] Refuse a NUL in a persistence ID, map positions beyond BIGINT (#308)
- Record the PostgreSQL store's migrations in a table of its own (#305)
Refactor
- Replace Infallible with ! and require Rust 1.100 (#516)
Documentation
- (postgres) Count the statement timeout twice in the pool bounds (#507)
- Regenerate changelogs with the unified config (#505)
- Qualify the replay claim in the postgres readme and the roadmap (#501)
- Clarify cluster guarantees and complete the READMEs (#475)
- Fix review findings in READMEs, roadmap, demo and examples (#477)
- Fix the review's core and persistence doc findings (#476)
- Add release notes for the breaking changes since 0.5.3 (#321)
- Give the PostgreSQL store's schema as the supported definition (#315)
Styling
- Trim example comments, rename the manager's message, per review (#474)
- (persistence) Order items, narrow fields, shorten paths per review (#469)
Miscellaneous Tasks
- Rename docker-compose.yaml to compose.yaml (#241)