Droplet ORM
Guide
GitHub
Guide
GitHub
    • Introduction
    • Registry
    • Data Pools
    • Entities
    • Entity Fields
    • MySQL Indexes
    • Code Generation
    • Engine
    • Context
    • Schema Update
    • CRUD Operations
    • Transactions
    • Search
    • Elasticsearch
    • MySQL Queries
    • ClickHouse Queries
    • ClickHouse Schema
    • NATS and JetStream
    • Entity Change Events (CDC)
    • Consumers
    • Tasks and Job Runs
    • Transactional Outbox
    • Context Cache
    • Redis Cache
    • Fake Delete
    • Lifecycle Callbacks
    • Metrics
    • Redis Operations
    • Distributed Lock
    • Queries Log
    • Testing
    • Migrating from fluxaorm

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.

fluxaormDroplet ORM
Modulegithub.com/latolukasz/fluxaorm/v2github.com/DropletLive/orm
Packagefluxaormorm
Entity streamFLUXA_ENTITY, subjects fluxa.entity.*, fluxa.replay.*ORM_ENTITY, subjects orm.entity.*, orm.replay.*
Task streamFLUXA_TASK, subjects fluxa.task.*ORM_TASK, subjects orm.task.*
Change feednoneCDC, subjects cdc.<database>.<table>
Job-run headerFluxa-Job-Run-IDOrm-Job-Run-ID
Prometheus metricsfluxaorm_*orm_*

Releases restart at v1: the module path has no major-version suffix.

1. Code

  1. Replace the import path with github.com/DropletLive/orm.
  2. Replace fluxaorm. with orm..
  3. 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.Before and DirtyEvent.After are read-only entities. Handlers read them with getters, for example ev.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.*.

  1. Stop every writer of tasks and entity events.
  2. Let the old consumers drain both streams to zero pending. Check with nats consumer report FLUXA_ENTITY and nats consumer report FLUXA_TASK.
  3. Stop the old consumers.
  4. Deploy the whole fleet on the new version at once, not as a rolling deploy across the two versions.
  5. Delete the old streams: nats stream rm FLUXA_ENTITY and nats 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() adds interpolateParams=true to every MySQL DSN that does not set it, so a parametrized query takes one round trip. Set MySQLOptions.ServerSidePreparedStatements to 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, SearchManyWithTotal and SearchOne read 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.
Edit this page
Last Updated: 11/16/26, 1:49 PM
Prev
Testing