Migrating from fluxaorm
Droplet ORM is github.com/latolukasz/fluxaorm/v2 v2.4.4 moved to github.com/DropletLive/orm, with the changes made after the move. This page lists everything an application coming from fluxaorm has to do.
| fluxaorm | Droplet ORM | |
|---|---|---|
| Module | github.com/latolukasz/fluxaorm/v2 | github.com/DropletLive/orm |
| Package | fluxaorm | orm |
| Entity stream | FLUXA_ENTITY, subjects fluxa.entity.*, fluxa.replay.* | ORM_ENTITY, subjects orm.entity.*, orm.replay.* |
| Task stream | FLUXA_TASK, subjects fluxa.task.* | ORM_TASK, subjects orm.task.* |
| Change feed | none | CDC, subjects cdc.<database>.<table> |
| Job-run header | Fluxa-Job-Run-ID | Orm-Job-Run-ID |
| Prometheus metrics | fluxaorm_* | orm_* |
Releases restart at v1: the module path has no major-version suffix.
1. Code
- Replace the import path with
github.com/DropletLive/orm. - Replace
fluxaorm.withorm.. - Regenerate the entities with
orm.Generate(), see Code Generation.
The package is now called orm. A local variable named orm shadows it for the rest of its scope:
func load(orm orm.Context) { // compiles
pager := orm.NewPager(1, 10) // does not: orm is the Context here
}
Rename the locals that shadow a package reference; the compiler lists them. Generated code uses ctx. A file that also imports another package named orm needs an alias for one of them.
2. Redis Search
Redis Search support is removed. There are no FT.* indexes, no *InRedis search methods and no GetRedisSearchAlters().
Validate() returns an error for an entity that still uses the redisSearch, searchable or sortable tag. Remove the tags and move those queries to MySQL search or to Elasticsearch.
Nothing deletes the indexes fluxaorm left in Redis, and ClearRedisCache does not reach them. List them with FT._LIST and drop each one together with its hashes:
FT.DROPINDEX <index> DD
3. Entity events
Changes of cdc and outbox entities are now published to the CDC stream as Debezium envelopes. A CDC reader forwards them to ORM_ENTITY, where your consumers read them. See Entity Events.
- Run the CDC reader (
orm.NewCDCReader(engine)) in a loop, like any other consumer. Without it no consumer receives entity events. DirtyEvent.BeforeandDirtyEvent.Afterare read-only entities. Handlers read them with getters, for exampleev.After.GetStatus().
4. NATS stream cutover
The first deploy creates empty CDC, ORM_ENTITY and ORM_TASK streams with new durable consumers. Nothing reads the FLUXA_* streams any more, and GetNatsAlters() never deletes them: it only removes unregistered streams whose name starts with ORM_ or orm_.
Messages still in the old streams are stranded: unconsumed entity events and pending or retrying tasks. A rolling deploy also splits the fleet, because old processes publish to fluxa.* and new processes consume orm.*.
- Stop every writer of tasks and entity events.
- Let the old consumers drain both streams to zero pending. Check with
nats consumer report FLUXA_ENTITYandnats consumer report FLUXA_TASK. - Stop the old consumers.
- Deploy the whole fleet on the new version at once, not as a rolling deploy across the two versions.
- Delete the old streams:
nats stream rm FLUXA_ENTITYandnats stream rm FLUXA_TASK.
Entity events lost in a failed drain can be recovered with a replay. Outbox entities are republished by RelayCDCOutbox while their rows are still pending.
5. Metrics
Rename fluxaorm_ to orm_ in dashboards and alert rules. History stays under the old names. See Metrics.
6. Behavior changes
- Redis version.
Validate()accepts Redis 8.2 or later and Valkey 9.0 or later. - MySQL parameters.
Validate()addsinterpolateParams=trueto every MySQL DSN that does not set it, so a parametrized query takes one round trip. SetMySQLOptions.ServerSidePreparedStatementsto keep server-side prepared statements. This is required for the connection charsets big5, cp932, gb2312, gbk and sjis. See Data Pools. - Search on entities without
redisCache.SearchMany,SearchManyWithTotalandSearchOneread full rows in one query instead of selecting IDs and loading them. See Search. - Consumers bind to their stream. A consumer reads the durable on the stream it was declared on. Before, it could pick a durable with the same name on another stream.