odac 1.4.8 → 1.4.10

package/src/Database.js

@@ -1,6 +1,7 @@
 'use strict'
 const {buildConnections} = require('./Database/ConnectionFactory')
 const nanoid = require('./Database/nanoid')
+const readCache = require('./Database/ReadCache')
 const writeBuffer = require('./Database/WriteBuffer')
 
 class DatabaseManager {
@@ -33,8 +34,11 @@ class DatabaseManager {
     // Runs on ALL processes (primary + workers) since every process may insert data.
     this._loadNanoidMeta()
 
+    // Initialize Read-Through Cache (all processes — every worker may read cached data)
+    readCache.init()
+
     // Initialize Write-Behind Cache (Primary holds state, Workers communicate via IPC)
-    await writeBuffer.init(this.connections)
+    await writeBuffer.init(this.connections, this._nanoidColumns)
   }
 
   /**
@@ -200,6 +204,54 @@ const tableProxyHandler = {
       flush: () => writeBuffer.flush(connectionKey, prop)
     }
 
+    // Read-Through Cache: Odac.DB.posts.cache(60).where({active: true}).select('id', 'title')
+    //                     Odac.DB.posts.cache().where({id: 5}).first()
+    //                     Odac.DB.posts.cache.clear()
+    // Why: Returns a Proxy that intercepts .then() to inject cache lookup before DB execution.
+    // The ttl parameter on cache() sets per-query TTL; omit for config default.
+    const cacheFactory = ttl => {
+      const cachedQb = knexInstance(prop)
+      cachedQb._odacCacheTtl = ttl || 0
+
+      // Capture the ORIGINAL .then() before overriding — prevents infinite recursion
+      // when ReadCache.get() needs to execute the actual DB query on cache MISS.
+      const originalCacheThen = cachedQb.then.bind(cachedQb)
+      cachedQb.then = function (resolve, reject) {
+        const executeFn = () => new Promise((res, rej) => originalCacheThen(res, rej))
+        return readCache.get(connectionKey, prop, this, executeFn, this._odacCacheTtl).then(resolve, reject)
+      }
+
+      return cachedQb
+    }
+
+    qb.cache = Object.assign(cacheFactory, {
+      clear: () => readCache.clear(connectionKey, prop)
+    })
+
+    // Automatic cache invalidation on write operations (insert/update/delete/truncate).
+    // Why: Prevents stale reads — any mutation on a table purges all cached SELECT results.
+    // Write methods are terminal (no further chaining after await), so wrapping the return
+    // as a simple thenable is safe and avoids .then() override conflicts with count/other wraps.
+    const wrapWithInvalidation = original =>
+      function (...args) {
+        const qbResult = original.apply(this, args)
+        const thenable = {
+          then: (resolve, reject) =>
+            qbResult.then(res => readCache.invalidate(connectionKey, prop).then(() => res), reject).then(resolve, reject),
+          catch: fn => thenable.then(undefined, fn)
+        }
+        return thenable
+      }
+
+    const originalUpdate = qb.update
+    const originalDelete = qb.delete
+    const originalDel = qb.del
+    const originalTruncate = qb.truncate
+    qb.update = wrapWithInvalidation(originalUpdate)
+    qb.delete = wrapWithInvalidation(originalDelete)
+    qb.del = wrapWithInvalidation(originalDel)
+    qb.truncate = wrapWithInvalidation(originalTruncate)
+
     // Odac DX Improvement: Wrap count() to return a clean number
     const originalCount = qb.count
     qb.count = function (...args) {
@@ -228,6 +280,24 @@ const tableProxyHandler = {
       }
     }
 
+    // Cache invalidation for insert — applied AFTER nanoid wrap so both paths are covered.
+    // IMPORTANT: Unlike update/delete/truncate, insert is NOT terminal — it supports
+    // chaining (e.g. .insert().onConflict().merge()). So we cannot use wrapWithInvalidation
+    // which returns a plain thenable. Instead, override .then() on the query builder to
+    // inject invalidation at execution time, preserving the full Knex chain.
+    const insertBeforeInvalidation = qb.insert
+    qb.insert = function (...args) {
+      const result = insertBeforeInvalidation.apply(this, args)
+      const origThen = result.then
+      result.then = function (resolve, reject) {
+        return origThen
+          .call(this)
+          .then(res => readCache.invalidate(connectionKey, prop).then(() => res))
+          .then(resolve, reject)
+      }
+      return result
+    }
+
     const originalThen = qb.then
     qb.then = function (resolve, reject) {
       if (this._odacIsCount) {
@@ -288,6 +358,13 @@ const rootProxy = new Proxy(manager, {
       }
     }
 
+    // Global ReadCache: Odac.DB.cache.clear(connection, table)
+    if (prop === 'cache') {
+      return {
+        clear: (connection, table) => readCache.clear(connection, table)
+      }
+    }
+
     // Access to specific database connection: Odac.DB.analytics
     if (target.connections[prop]) {
       return new Proxy(target.connections[prop], tableProxyHandler)

package/src/Validator.js

@@ -224,7 +224,7 @@ class Validator {
                     error = value && value !== '' && !this.#odac.Var(value).is('url')
                     break
                   case 'username':
-                    error = value && value !== '' && !/^[a-zA-Z0-9]+$/.test(value)
+                    error = value && value !== '' && !this.#odac.Var(value).is('username')
                     break
                   case 'xss':
                     error = value && value !== '' && /<[^>]*>/g.test(value)

package/src/Var.js

@@ -139,6 +139,7 @@ class Var {
           /([0-9#][\u20E3])|[\u00ae\u00a9\u203C\u2047\u2048\u2049\u3030\u303D\u2139\u2122\u3297\u3299][\uFE00-\uFEFF]?|[\u2190-\u21FF][\uFE00-\uFEFF]?|[\u2300-\u23FF][\uFE00-\uFEFF]?|[\u2460-\u24FF][\uFE00-\uFEFF]?|[\u25A0-\u25FF][\uFE00-\uFEFF]?|[\u2600-\u27BF][\uFE00-\uFEFF]?|[\u2900-\u297F][\uFE00-\uFEFF]?|[\u2B00-\u2BF0][\uFE00-\uFEFF]?|[\u1F000-\u1F6FF][\uFE00-\uFEFF]?/u.test(
             this.#value
           ))
+    if (args.includes('username')) result = (result || any) && ((any && result) || /^[a-zA-Z0-9]+$/.test(this.#value))
     if (args.includes('xss')) result = (result || any) && ((any && result) || this.#value == this.#value.replace(/<[^>]*>/g, ''))
     return result
   }

package/src/WebSocket.js

@@ -14,10 +14,26 @@ const OPCODE = {
   PONG: 0xa
 }
 
+/**
+ * RFC 6455 connection lifecycle states.
+ * Exposed as static constants on WebSocketClient for consumer-side checks.
+ */
+const READY_STATE = {
+  CONNECTING: 0,
+  OPEN: 1,
+  CLOSING: 2,
+  CLOSED: 3
+}
+
 class WebSocketClient {
+  static CONNECTING = READY_STATE.CONNECTING
+  static OPEN = READY_STATE.OPEN
+  static CLOSING = READY_STATE.CLOSING
+  static CLOSED = READY_STATE.CLOSED
+
   #socket
   #handlers = {}
-  #closed = false
+  #readyState = READY_STATE.CONNECTING
   #server
   #id
   #rooms = new Set()
@@ -26,6 +42,7 @@ class WebSocketClient {
   #rateLimitWindow
   #messageCount = 0
   #rateLimitTimer
+  #fragments = null
   data = {}
 
   constructor(socket, server, id, options = {}) {
@@ -47,10 +64,20 @@ class WebSocketClient {
     this.#setupListeners()
   }
 
+  /**
+   * Transitions the client from CONNECTING to OPEN and resumes the underlying socket.
+   * Must be called after the handler is attached to begin receiving frames.
+   */
   resume() {
+    this.#readyState = READY_STATE.OPEN
     this.#socket.resume()
   }
 
+  /** @returns {number} Current RFC 6455 ready state (0–3). */
+  get readyState() {
+    return this.#readyState
+  }
+
   get id() {
     return this.#id
   }
@@ -154,10 +181,36 @@ class WebSocketClient {
 
     switch (frame.opcode) {
       case OPCODE.TEXT:
-        this.#handleMessage(frame.payload.toString('utf8'))
-        break
       case OPCODE.BINARY:
-        this.#handleMessage(frame.payload)
+        if (frame.fin) {
+          if (this.#fragments) {
+            // Final fragment of a fragmented sequence
+            this.#fragments.buffers.push(frame.payload)
+            const merged = Buffer.concat(this.#fragments.buffers)
+            const opcode = this.#fragments.opcode
+            this.#fragments = null
+            this.#handleMessage(opcode === OPCODE.TEXT ? merged.toString('utf8') : merged)
+          } else {
+            // Single, unfragmented message
+            this.#handleMessage(frame.opcode === OPCODE.TEXT ? frame.payload.toString('utf8') : frame.payload)
+          }
+        } else {
+          // First fragment — start accumulating
+          this.#fragments = {opcode: frame.opcode, buffers: [frame.payload]}
+        }
+        break
+      case OPCODE.CONTINUATION:
+        if (!this.#fragments) {
+          this.close(1002, 'Protocol error: unexpected continuation frame')
+          return
+        }
+        this.#fragments.buffers.push(frame.payload)
+        if (frame.fin) {
+          const merged = Buffer.concat(this.#fragments.buffers)
+          const opcode = this.#fragments.opcode
+          this.#fragments = null
+          this.#handleMessage(opcode === OPCODE.TEXT ? merged.toString('utf8') : merged)
+        }
         break
       case OPCODE.PING:
         this.#sendFrame(OPCODE.PONG, frame.payload)
@@ -181,11 +234,16 @@ class WebSocketClient {
     }
   }
 
-  #handleClose() {
-    if (this.#closed) return
-    this.#closed = true
+  /**
+   * Centralised resource teardown — called by both close() and the socket 'close' event.
+   * Idempotent: subsequent calls are no-ops once state reaches CLOSED.
+   */
+  #cleanup() {
+    if (this.#readyState === READY_STATE.CLOSED) return
+    this.#readyState = READY_STATE.CLOSED
 
     if (this.#rateLimitTimer) clearInterval(this.#rateLimitTimer)
+    this.#fragments = null
 
     this.#socket.removeAllListeners()
 
@@ -197,8 +255,15 @@ class WebSocketClient {
     this.#server.removeClient(this.#id)
   }
 
+  #handleClose() {
+    this.#cleanup()
+  }
+
   #sendFrame(opcode, data) {
-    if (this.#closed && opcode !== OPCODE.CLOSE) return
+    if (this.#readyState === READY_STATE.CLOSED) return
+    if (this.#readyState === READY_STATE.CLOSING && opcode !== OPCODE.CLOSE) return
+    if (!this.#socket.writable) return
+
     const payload = Buffer.isBuffer(data) ? data : Buffer.from(data)
     const length = payload.length
 
@@ -247,28 +312,27 @@ class WebSocketClient {
   }
 
   send(data) {
-    if (this.#closed) return this
+    if (this.#readyState !== READY_STATE.OPEN) return this
     const payload = typeof data === 'object' ? JSON.stringify(data) : String(data)
     this.#sendFrame(OPCODE.TEXT, payload)
     return this
   }
 
   sendBinary(data) {
-    if (this.#closed) return this
+    if (this.#readyState !== READY_STATE.OPEN) return this
     this.#sendFrame(OPCODE.BINARY, data)
     return this
   }
 
   ping() {
+    if (this.#readyState !== READY_STATE.OPEN) return this
     this.#sendFrame(OPCODE.PING, Buffer.alloc(0))
     return this
   }
 
   close(code = 1000, reason = '') {
-    if (this.#closed) return
-    this.#closed = true
-
-    if (this.#rateLimitTimer) clearInterval(this.#rateLimitTimer)
+    if (this.#readyState === READY_STATE.CLOSED || this.#readyState === READY_STATE.CLOSING) return
+    this.#readyState = READY_STATE.CLOSING
 
     const reasonBuffer = Buffer.from(reason)
     const payload = Buffer.alloc(2 + reasonBuffer.length)
@@ -277,14 +341,7 @@ class WebSocketClient {
 
     this.#sendFrame(OPCODE.CLOSE, payload)
     this.#socket.end()
-    this.#socket.removeAllListeners()
-
-    for (const room of this.#rooms) {
-      this.#server.leaveRoom(this.#id, room)
-    }
-
-    this.#emit('close')
-    this.#server.removeClient(this.#id)
+    this.#cleanup()
   }
 
   join(room) {
@@ -448,4 +505,4 @@ class WebSocketServer {
   }
 }
 
-module.exports = {WebSocketServer, WebSocketClient}
+module.exports = {WebSocketServer, WebSocketClient, READY_STATE}

package/test/Database/Migration/migrate_column.test.js

@@ -49,4 +49,315 @@ describe('Migration.migrate() - Column Diff', () => {
 
     expect(dropOps).toEqual(expect.arrayContaining([expect.objectContaining({type: 'drop_column', column: 'obsolete', table: 'items'})]))
   })
+
+  it('should alter a column when its default value changes', async () => {
+    writeSchema('settings', {columns: {id: {type: 'increments'}, status: {type: 'string', default: 'active'}}})
+    await Migration.migrate()
+
+    writeSchema('settings', {columns: {id: {type: 'increments'}, status: {type: 'string', default: 'inactive'}}})
+    const result = await Migration.migrate()
+    const alterOps = result.default.schema.filter(op => op.type === 'alter_column')
+
+    expect(alterOps).toEqual(expect.arrayContaining([expect.objectContaining({type: 'alter_column', column: 'status', table: 'settings'})]))
+  })
+
+  it('should alter a column when its default value is removed', async () => {
+    writeSchema('settings', {columns: {id: {type: 'increments'}, status: {type: 'string', default: 'active'}}})
+    await Migration.migrate()
+
+    writeSchema('settings', {columns: {id: {type: 'increments'}, status: {type: 'string'}}})
+    const result = await Migration.migrate()
+    const alterOps = result.default.schema.filter(op => op.type === 'alter_column')
+
+    expect(alterOps).toEqual(expect.arrayContaining([expect.objectContaining({type: 'alter_column', column: 'status', table: 'settings'})]))
+  })
+
+  it('should not alter a column when its default value is unchanged', async () => {
+    writeSchema('settings', {columns: {id: {type: 'increments'}, status: {type: 'string', default: 'active'}}})
+    await Migration.migrate()
+
+    writeSchema('settings', {columns: {id: {type: 'increments'}, status: {type: 'string', default: 'active'}}})
+    const result = await Migration.migrate()
+    const alterOps = result.default.schema.filter(op => op.type === 'alter_column')
+
+    expect(alterOps).toHaveLength(0)
+  })
+})
+
+describe('Migration.migrate() - Foreign Key Diff', () => {
+  it('should add a foreign key to an existing column', async () => {
+    writeSchema('users', {columns: {id: {type: 'increments'}, name: {type: 'string'}}})
+    writeSchema('posts', {columns: {id: {type: 'increments'}, user_id: {type: 'integer', unsigned: true}}})
+    await Migration.migrate()
+
+    writeSchema('posts', {
+      columns: {
+        id: {type: 'increments'},
+        user_id: {type: 'integer', unsigned: true, references: {table: 'users', column: 'id'}, onDelete: 'CASCADE'}
+      }
+    })
+    const result = await Migration.migrate()
+    const fkOps = result.default.schema.filter(op => op.type === 'add_foreign_key')
+
+    expect(fkOps).toEqual(expect.arrayContaining([expect.objectContaining({type: 'add_foreign_key', column: 'user_id', table: 'posts'})]))
+  })
+
+  it('should drop a foreign key removed from schema', async () => {
+    writeSchema('users', {columns: {id: {type: 'increments'}, name: {type: 'string'}}})
+    writeSchema('posts', {
+      columns: {
+        id: {type: 'increments'},
+        user_id: {type: 'integer', unsigned: true, references: {table: 'users', column: 'id'}, onDelete: 'CASCADE'}
+      }
+    })
+    await Migration.migrate()
+
+    writeSchema('posts', {columns: {id: {type: 'increments'}, user_id: {type: 'integer', unsigned: true}}})
+    const result = await Migration.migrate()
+    const fkOps = result.default.schema.filter(op => op.type === 'drop_foreign_key')
+
+    expect(fkOps).toEqual(expect.arrayContaining([expect.objectContaining({type: 'drop_foreign_key', column: 'user_id', table: 'posts'})]))
+  })
+
+  it('should replace a foreign key when onDelete action changes', async () => {
+    writeSchema('users', {columns: {id: {type: 'increments'}, name: {type: 'string'}}})
+    writeSchema('posts', {
+      columns: {
+        id: {type: 'increments'},
+        user_id: {type: 'integer', unsigned: true, references: {table: 'users', column: 'id'}, onDelete: 'SET NULL'}
+      }
+    })
+    await Migration.migrate()
+
+    writeSchema('posts', {
+      columns: {
+        id: {type: 'increments'},
+        user_id: {type: 'integer', unsigned: true, references: {table: 'users', column: 'id'}, onDelete: 'CASCADE'}
+      }
+    })
+    const result = await Migration.migrate()
+    const dropOps = result.default.schema.filter(op => op.type === 'drop_foreign_key')
+    const addOps = result.default.schema.filter(op => op.type === 'add_foreign_key')
+
+    expect(dropOps).toHaveLength(1)
+    expect(addOps).toHaveLength(1)
+    expect(addOps[0]).toMatchObject({column: 'user_id', table: 'posts'})
+  })
+
+  it('should not produce FK ops when references are unchanged', async () => {
+    writeSchema('users', {columns: {id: {type: 'increments'}, name: {type: 'string'}}})
+    writeSchema('posts', {
+      columns: {
+        id: {type: 'increments'},
+        user_id: {type: 'integer', unsigned: true, references: {table: 'users', column: 'id'}, onDelete: 'CASCADE'}
+      }
+    })
+    await Migration.migrate()
+
+    const result = await Migration.migrate()
+    const fkOps = result.default.schema.filter(op => op.type === 'add_foreign_key' || op.type === 'drop_foreign_key')
+
+    expect(fkOps).toHaveLength(0)
+  })
+
+  it('should clean orphan rows before adding a foreign key constraint', async () => {
+    writeSchema('users', {columns: {id: {type: 'increments'}, name: {type: 'string'}}})
+    writeSchema('posts', {columns: {id: {type: 'increments'}, user_id: {type: 'integer', nullable: true}}})
+    await Migration.migrate()
+
+    // Insert a valid parent and an orphan child
+    await db('users').insert({name: 'Alice'})
+    await db('posts').insert({user_id: 1})
+    await db('posts').insert({user_id: 999}) // orphan — user 999 does not exist
+
+    // Now add FK constraint
+    writeSchema('posts', {
+      columns: {
+        id: {type: 'increments'},
+        user_id: {type: 'integer', nullable: true, references: {table: 'users', column: 'id'}, onDelete: 'CASCADE'}
+      }
+    })
+    await Migration.migrate()
+
+    // Orphan row should have user_id set to NULL (nullable column)
+    const orphan = await db('posts').where('id', 2).first()
+    expect(orphan.user_id).toBeNull()
+
+    // Valid row should be untouched
+    const valid = await db('posts').where('id', 1).first()
+    expect(valid.user_id).toBe(1)
+  })
+
+  it('should skip FK and warn when non-nullable column has orphan rows', async () => {
+    writeSchema('users', {columns: {id: {type: 'increments'}, name: {type: 'string'}}})
+    writeSchema('posts', {columns: {id: {type: 'increments'}, user_id: {type: 'integer', nullable: false}}})
+    await Migration.migrate()
+
+    await db('users').insert({name: 'Alice'})
+    await db('posts').insert({user_id: 1})
+    await db('posts').insert({user_id: 999}) // orphan
+
+    const warnSpy = jest.spyOn(console, 'error').mockImplementation(() => {})
+
+    writeSchema('posts', {
+      columns: {
+        id: {type: 'increments'},
+        user_id: {type: 'integer', nullable: false, references: {table: 'users', column: 'id'}, onDelete: 'CASCADE'}
+      }
+    })
+    await Migration.migrate()
+
+    // Orphan row must NOT be deleted — all data preserved
+    const rows = await db('posts').select()
+    expect(rows).toHaveLength(2)
+
+    // Warning must have been emitted
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Skipping foreign key'))
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('1 orphan row(s)'))
+
+    warnSpy.mockRestore()
+  })
+})
+
+describe('Migration.migrate() - Column Type Change', () => {
+  it('should alter a column when its type changes (string → text)', async () => {
+    writeSchema('articles', {columns: {id: {type: 'increments'}, body: {type: 'string'}}})
+    await Migration.migrate()
+
+    writeSchema('articles', {columns: {id: {type: 'increments'}, body: {type: 'text'}}})
+    const result = await Migration.migrate()
+    const alterOps = result.default.schema.filter(op => op.type === 'alter_column')
+
+    expect(alterOps).toEqual(expect.arrayContaining([expect.objectContaining({type: 'alter_column', column: 'body', table: 'articles'})]))
+  })
+
+  it('should alter a column when its type changes (integer → bigInteger)', async () => {
+    writeSchema('counters', {columns: {id: {type: 'increments'}, value: {type: 'integer'}}})
+    await Migration.migrate()
+
+    writeSchema('counters', {columns: {id: {type: 'increments'}, value: {type: 'bigInteger'}}})
+    const result = await Migration.migrate()
+    const alterOps = result.default.schema.filter(op => op.type === 'alter_column')
+
+    expect(alterOps).toEqual(expect.arrayContaining([expect.objectContaining({type: 'alter_column', column: 'value', table: 'counters'})]))
+  })
+
+  it('should not alter a column when its type is unchanged', async () => {
+    writeSchema('logs', {columns: {id: {type: 'increments'}, message: {type: 'text'}}})
+    await Migration.migrate()
+
+    writeSchema('logs', {columns: {id: {type: 'increments'}, message: {type: 'text'}}})
+    const result = await Migration.migrate()
+    const alterOps = result.default.schema.filter(op => op.type === 'alter_column')
+
+    expect(alterOps).toHaveLength(0)
+  })
+
+  it('should not produce alter for nanoid columns stored as string', async () => {
+    writeSchema('tokens', {columns: {id: {type: 'nanoid', length: 21}, name: {type: 'string'}}})
+    await Migration.migrate()
+
+    // Re-run with same schema — nanoid maps to varchar in DB, should not trigger false alter
+    writeSchema('tokens', {columns: {id: {type: 'nanoid', length: 21}, name: {type: 'string'}}})
+    const result = await Migration.migrate()
+    const alterOps = result.default.schema.filter(op => op.type === 'alter_column')
+
+    expect(alterOps).toHaveLength(0)
+  })
+})
+
+describe('Migration.migrate() - Nullable Preservation on Alter', () => {
+  it('should preserve NOT NULL when altering a column that has no explicit nullable in schema', async () => {
+    // Create table with a NOT NULL column
+    writeSchema('domains', {columns: {id: {type: 'increments'}, code: {type: 'string', nullable: false, default: 'A'}}})
+    await Migration.migrate()
+
+    // Change default value but omit nullable — should preserve NOT NULL from DB
+    writeSchema('domains', {columns: {id: {type: 'increments'}, code: {type: 'string', default: 'B'}}})
+    const result = await Migration.migrate()
+    const alterOps = result.default.schema.filter(op => op.type === 'alter_column')
+
+    expect(alterOps).toHaveLength(1)
+    expect(alterOps[0]).toMatchObject({column: 'code', currentNullable: false})
+  })
+
+  it('should preserve NULLABLE when altering a column that has no explicit nullable in schema', async () => {
+    // Create table with a NULLABLE column
+    writeSchema('logs', {columns: {id: {type: 'increments'}, note: {type: 'string', nullable: true, default: 'x'}}})
+    await Migration.migrate()
+
+    // Change default but omit nullable — should preserve nullable from DB
+    writeSchema('logs', {columns: {id: {type: 'increments'}, note: {type: 'string', default: 'y'}}})
+    const result = await Migration.migrate()
+    const alterOps = result.default.schema.filter(op => op.type === 'alter_column')
+
+    expect(alterOps).toHaveLength(1)
+    expect(alterOps[0]).toMatchObject({column: 'note', currentNullable: true})
+  })
+})
+
+describe('Migration - PG Primary Key Alter Safety', () => {
+  it('should carry primary flag in alter_column diff for PK columns', async () => {
+    // Create table with a primary nanoid column
+    writeSchema('domains', {columns: {id: {type: 'nanoid', primary: true}, name: {type: 'string'}}})
+    await Migration.migrate()
+
+    // Simulate a type mismatch by changing to a different length — triggers alter
+    writeSchema('domains', {columns: {id: {type: 'nanoid', primary: true, length: 30}, name: {type: 'string'}}})
+    const result = await Migration.migrate({dryRun: true})
+    const alterOps = result.default.schema.filter(op => op.type === 'alter_column' && op.column === 'id')
+
+    expect(alterOps).toHaveLength(1)
+    expect(alterOps[0].definition.primary).toBe(true)
+  })
+
+  it('should map ODAC types to PG types correctly via _pgColumnType', () => {
+    const m = Migration
+    expect(m._pgColumnType({type: 'nanoid'})).toBe('varchar(21)')
+    expect(m._pgColumnType({type: 'nanoid', length: 30})).toBe('varchar(30)')
+    expect(m._pgColumnType({type: 'string'})).toBe('varchar(255)')
+    expect(m._pgColumnType({type: 'string', length: 100})).toBe('varchar(100)')
+    expect(m._pgColumnType({type: 'text'})).toBe('text')
+    expect(m._pgColumnType({type: 'integer'})).toBe('integer')
+    expect(m._pgColumnType({type: 'bigInteger'})).toBe('bigint')
+    expect(m._pgColumnType({type: 'boolean'})).toBe('boolean')
+    expect(m._pgColumnType({type: 'uuid'})).toBe('uuid')
+    expect(m._pgColumnType({type: 'jsonb'})).toBe('jsonb')
+    expect(m._pgColumnType({type: 'timestamp'})).toBe('timestamp')
+    expect(m._pgColumnType({type: 'binary'})).toBe('bytea')
+    expect(m._pgColumnType({type: 'decimal'})).toBe('numeric(10,2)')
+    expect(m._pgColumnType({type: 'decimal', precision: 8, scale: 4})).toBe('numeric(8,4)')
+    expect(m._pgColumnType({type: 'specificType', length: 'text[]'})).toBe('text[]')
+  })
+})
+
+describe('Migration - specificType handling', () => {
+  it('should create a specificType column using the length field as the raw DB type', async () => {
+    writeSchema('events', {
+      columns: {
+        id: {type: 'increments'},
+        tags: {type: 'specificType', length: 'text'}
+      }
+    })
+    await Migration.migrate()
+
+    const info = await db('events').columnInfo()
+    expect(info).toHaveProperty('tags')
+  })
+
+  it('should not produce false alter for specificType when DB type matches', async () => {
+    writeSchema('events', {
+      columns: {
+        id: {type: 'increments'},
+        tags: {type: 'specificType', length: 'text'}
+      }
+    })
+    await Migration.migrate()
+
+    // Re-run with same schema — should not trigger alter
+    const result = await Migration.migrate()
+    const alterOps = result.default.schema.filter(op => op.type === 'alter_column')
+
+    expect(alterOps).toHaveLength(0)
+  })
 })