Merge pull request #36 from flippercloud/sequelize-use-primary

Add configurable useMaster option to Sequelize adapter

Author: jonmagic

docs/adapters/sequelize.md

@@ -98,6 +98,20 @@ await flipper.enable('search')
 const enabled = await flipper.isFeatureEnabled('search')
 ```
 
+### Primary Reads (Replication Consistency)
+
+If your Sequelize setup uses read replicas, there can be a lag between writes (e.g. calling `enable`) and subsequent reads on a replica. To guarantee read-after-write consistency for Flipper operations, construct the adapter with `useMaster: true` which passes `useMaster` to all Sequelize `find` queries, ensuring they target the primary connection.
+
+```typescript
+const adapter = new SequelizeAdapter({
+  Feature: models.Feature,
+  Gate: models.Gate,
+  useMaster: true, // force reads to primary DB
+})
+```
+
+Default is `false`, allowing replicas to serve reads. Enable this only where strict consistency is required (e.g. synchronous feature toggling during a request lifecycle).
+
 ## API surface
 
 The adapter implements the full Flipper adapter contract:

packages/flipper-sequelize/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@flippercloud/flipper-sequelize",
   "description": "Sequelize adapter for Flipper feature flags",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "author": "Jonathan Hoyt",
   "license": "MIT",
   "main": "./dist/cjs/index.js",

packages/flipper-sequelize/src/SequelizeAdapter.ts

@@ -20,6 +20,13 @@ export interface SequelizeAdapterOptions {
    * Whether the adapter is read-only (default: false)
    */
   readOnly?: boolean
+  /**
+   * Force all read queries to use the primary database connection in a
+   * replicated setup (default: false). This passes `useMaster: true` to
+   * Sequelize find calls so they bypass replicas. Helpful when you have
+   * just written feature changes and need read-after-write consistency.
+   */
+  useMaster?: boolean
 }
 
 /**
@@ -62,18 +69,24 @@ class SequelizeAdapter implements IAdapter {
    */
   private _readOnly: boolean
 
+  /**
+   * Whether read queries should be forced to the primary (master) connection.
+   */
+  private _useMaster: boolean
+
   constructor(options: SequelizeAdapterOptions) {
     this.Feature = options.Feature
     this.Gate = options.Gate
     this._readOnly = options.readOnly ?? false
+    this._useMaster = options.useMaster ?? false
   }
 
   /**
    * Get all features.
    * @returns Array of all Feature instances
    */
   async features(): Promise<FeatureClass[]> {
-    const features = await this.Feature.findAll({ raw: true })
+    const features = await this.Feature.findAll({ raw: true, useMaster: this._useMaster })
     // We need to import Feature dynamically to avoid circular dependencies
     const module = await import('@flippercloud/flipper')
     const Feature = module.Feature
@@ -132,6 +145,7 @@ class SequelizeAdapter implements IAdapter {
     const dbFeature = await this.Feature.findOne({
       where: { key: feature.key },
       raw: true,
+      useMaster: this._useMaster,
     })
 
     if (!dbFeature) {
@@ -142,6 +156,7 @@ class SequelizeAdapter implements IAdapter {
       where: { featureKey: feature.key },
       attributes: ['key', 'value'],
       raw: true,
+      useMaster: this._useMaster,
     })
 
     return this.resultForGates(feature, gates as Array<{ key: string | null; value: string | null }>)
@@ -186,12 +201,14 @@ class SequelizeAdapter implements IAdapter {
     // Ensure feature exists
     let dbFeature = await this.Feature.findOne({
       where: { key: feature.key },
+      useMaster: this._useMaster,
     })
 
     if (!dbFeature) {
       await this.add(feature)
       dbFeature = await this.Feature.findOne({
         where: { key: feature.key },
+        useMaster: this._useMaster,
       })
     }
 
@@ -234,6 +251,7 @@ class SequelizeAdapter implements IAdapter {
 
     const dbFeature = await this.Feature.findOne({
       where: { key: feature.key },
+      useMaster: this._useMaster,
     })
 
     if (!dbFeature) {
@@ -276,6 +294,7 @@ class SequelizeAdapter implements IAdapter {
 
     const dbFeature = await this.Feature.findOne({
       where: { key: feature.key },
+      useMaster: this._useMaster,
     })
 
     if (!dbFeature) {

packages/flipper-sequelize/src/index.test.ts

@@ -313,6 +313,49 @@ describe('SequelizeAdapter', () => {
     })
   })
 
+  describe('useMaster option', () => {
+    it('passes useMaster to read queries when true', async () => {
+      // Spy on findAll and findOne
+      const spyFindAll = jest.spyOn(FeatureModel, 'findAll')
+      const spyFindOne = jest.spyOn(FeatureModel, 'findOne')
+
+      const masterAdapter = new SequelizeAdapter({
+        Feature: FeatureModel,
+        Gate: GateModel,
+        useMaster: true,
+      })
+
+      // Trigger reads
+      await masterAdapter.features()
+
+      // Add then get to trigger findOne path with useMaster
+      const feature = new Feature('master-read-feature', masterAdapter, {})
+      await masterAdapter.add(feature)
+      await masterAdapter.get(feature)
+
+      // Assertions
+      expect(spyFindAll).toHaveBeenCalled()
+      const findAllArgs = spyFindAll.mock.calls[0]?.[0]
+      expect(findAllArgs).toMatchObject({ useMaster: true })
+
+      // Ensure at least one findOne received useMaster true
+      const findOneCallWithUseMaster = spyFindOne.mock.calls.find(call => call[0]?.useMaster === true)
+      expect(findOneCallWithUseMaster).toBeTruthy()
+
+      // Cleanup spies
+      spyFindAll.mockRestore()
+      spyFindOne.mockRestore()
+    })
+
+    it('defaults to replica (no useMaster) when option not set', async () => {
+      const spyFindAll = jest.spyOn(FeatureModel, 'findAll')
+      await adapter.features()
+      const findAllArgs = spyFindAll.mock.calls[0]?.[0]
+      expect(findAllArgs?.useMaster).toBe(false)
+      spyFindAll.mockRestore()
+    })
+  })
+
   describe('isFeatureEnabled checks', () => {
     it('enabled feature returns true', async () => {
       await flipper.enable('enabled-feature')