🚀 What's New

📦 Modular packages (#2321)

Advanced capabilities are split out of the monolith so ORM-only apps get a smaller dependency footprint and fewer surprises from transitive packages during Forge bundling and lint (see also #2128). Keeping everything in one package with optionalDependencies was not sufficient: Forge often still resolves and analyzes those dependencies even when a feature is unused.

The core package remains fully usable without installing forge-sql-orm-extra.

🧩 Cache SPI (Level 2)

• New Cache interface in core (getQueryResultsFromCache, setQueryResult, clearExpiredCache, clearTablesCache).
• NopCache in core — default on forge-sql-orm; global cache methods do not persist to KVS.
• KVSCache in forge-sql-orm-extra — default on forge-sql-orm-extra; Forge KVS backend (cursor pagination, batched deletes, retry with backoff).
• cacheImplementation on ForgeSqlOrmOptions to plug in a custom backend or tests.

Level 1 (local / in-memory) cache (executeWithLocalContext, selectFrom, execute, …) stays in core and works the same with either import.

Manual global cache eviction is simplified:

await forgeSQL.evictCache(["users", "orders"]);
await forgeSQL.evictCacheEntities([Users, Orders]);

📖 Documentation split between README.md (core) and forge-sql-orm-extra/README.md (L2 cache + Rovo).

⚠️ Migration to 2.2.x

Why this release

• Smaller core for users who only need SQL + Drizzle + migrations.
• Fewer transitive risks (node-sql-parser, @forge/kvs, Rovo code paths) for apps that never enable those features.
• Clear boundaries between core, extensions, and CLI — easier maintenance and future optional modules.

If you only use the ORM (no global KVS cache, no Rovo)

No migration required.

npm install forge-sql-orm @forge/sql drizzle-orm -S

import ForgeSQL from "forge-sql-orm";
const forgeSQL = new ForgeSQL();

Local cache, versioning, and Drizzle helpers behave as before. Core defaults to NopCache() for Level 2.

If you use global cache (Level 2) and/or Rovo

1. Install the extension (keep core deps):

   npm install forge-sql-orm-extra @forge/kvs -S

2. Change the import — logic, options, and queries stay the same:

   // Before (monolith ≤ 2.1.x)
   import ForgeSQL from "forge-sql-orm";
   
   // After (2.2.x)
   import ForgeSQL from "forge-sql-orm-extra";

3. Keep existing cache configuration, for example:

   const forgeSQL = new ForgeSQL({
     cacheEntityName: "cache",
     cacheTTL: 300,
   });

4. Update moved imports, for example:

   import { clearCacheSchedulerTrigger } from "forge-sql-orm-extra";

5. Replace manual eviction via modifyWithVersioningAndEvictCache().evictCache* with:

   await forgeSQL.evictCache(["users", "orders"]);
   await forgeSQL.evictCacheEntities([Users, Orders]);

forge-sql-orm-extra defaults to new KVSCache() — equivalent to the old monolith behaviour once you switch the import.

Full details: README — Breaking Changes (2.2.x) and forge-sql-orm-extra README.

🧪 CLI Test Suite & Merged Coverage

forge-sql-orm-cli now has its own test safety net, and coverage from the library and the CLI is reported together.

• Added Vitest unit tests for the CLI (command wiring, model generation, migration create/update/drop, schema diffing) behind an 80% coverage gate.
• Library and CLI lcov reports are merged into a single report for SonarCloud and Qlty.

🧹 Quality & Static Analysis

• Banned explicit any in the CLI (@typescript-eslint/no-explicit-any) and replaced any in catch blocks across the codebase.
• Lowered cognitive complexity in the CLI model/migration generators and applied SonarCloud fixes (node: import prefixes, Number.parseInt, locale-aware sorting, and more).
• Stricter Knip configuration, SPDX/REUSE license headers, and a license-compliance check that fails on GPL/LGPL/AGPL/copyleft dependencies.
• Documented the console-based logging policy (NFR-11).

🛠 CI / Release Automation

• Split the monolithic pipeline into separate quality / CLI / examples jobs; example deploys are capped at max-parallel: 5.
• Randomized Forge deploy/install retry backoff to ride out transient Atlassian failures.
• Codacy exclude_paths tuning and a Codacy badge in the README.
• Weekly GitHub Packages (latest) — workflow .github/workflows/weekly-gpr.yml runs every Sunday 02:00 UTC (and on manual dispatch). It checks out master, runs the same quality gate as CI (REUSE, Knip, license, lint, build, format, tests for core / extra / CLI), then publishes all three packages to GitHub Packages with dist-tag latest (version {semver}-weekly.{YYYYMMDD}). Ephemeral ci.* GPR versions are cleaned up after each weekly run. Official semver releases stay on npmjs.com — see Installing from GitHub Packages (weekly latest) in the README.

📦 Dependency Updates

Updated npm dependencies to their latest versions to ensure improved compatibility, security, and overall performance.

🚀 What's New

⬆️ TypeScript 6 & ESLint 10 Upgrade

The toolchain jumped a full major on both fronts. The codebase and example apps were adapted so they keep building cleanly under the stricter compiler.

• TypeScript: bumped from 5.9.3 to 6.0.3 (root + CLI).
• ESLint: now on 10.4.x with matching @typescript-eslint 8.59.4.
• Imports: restored the explicit node: prefix on async_hooks / crypto so module resolution stays predictable on TS 6.

🧹 Cyclomatic Complexity Cleanup

Several utilities were refactored to lower complexity flagged by Qlty while keeping behaviour identical. The result is shorter, flatter helpers that are easier to read and test.

🛠 CI / Release Automation

The release pipeline got a noticeable hardening pass.

• Daily autoupdate workflow: new autoupdate.yml that runs npm-check-updates
  so opened PRs actually trigger CI.
• Dependabot auto-merge: PRs get merged automatically once green.
• Pinned third-party actions to commit SHA for supply-chain safety.
• Concurrency: added concurrency settings to the Node.js workflow so duplicate runs cancel themselves on rapid pushes.
• Husky portability: pre-commit no longer uses pushd / popd — it now runs in a ( … ) subshell so /bin/sh is happy on every platform.

📦 Dependency Updates

Bumped runtime + dev dependencies to their latest compatible versions.

• Peer: @forge/sql ^3.0.23 → ^3.0.24.
• Runtime: @forge/api ^7.1.4 → ^7.2.0.
• Dev: vitest 4.1.5 → 4.1.7, knip 6.11.0 → 6.14.1, @types/node 25.6.0 → 25.9.1, inquirer 13.4.2 → 13.4.3, vite 8.0.10 → 8.0.14, plus alignments across all example apps.

🚀 What’s New

📦 Bundle Optimization & Forge Lint Fix
Moved advanced integration dependencies to optionalDependencies to optimize bundle size and resolve strict build errors in Atlassian Forge environments.

Optional Dependencies: node-sql-parser and @forge/events are now marked as optional. They are no longer bundled by default unless you explicitly use the advanced features.

🚀 What’s New

🧬 Binary & UUID Custom Types Support

Introducing a set of custom types for compact binary storage and optimized UUID handling in Atlassian Forge.

• uuidBinary: Store UUID primary keys in a compact VARBINARY(16) form. It automatically handles UUID_TO_BIN on writes and returns clean UUID strings on reads.
• forgeBLOB & Friends: New types for binary payloads: forgeBLOB, forgeTinyBLOB, forgeMediumBLOB, forgeBinary, and forgeVarBinary.

🤖 New AI Semantic Search Examples

Added two new real-world example projects demonstrating different architectural approaches for AI in Forge:

• Frontend Embeddings (Custom UI): Computes embeddings directly in the browser. Forge SQL is used to store document + embedding and perform vector similarity search.
• Backend Embeddings (Forge Resolvers): Computes embeddings server-side using the ai-lib sidecar. The UI only sends raw text, keeping the logic entirely on the backend.

Article: AI Magic in Atlassian Forge: Local Semantic Search with Forge SQL

🛠️ Comprehensive TiDB SQL Function Helpers

Added a massive collection of ready-to-use SQL helper modules. These helpers return Drizzle sql fragments, making it easy to use TiDB-specific functions inside your query builders:

• String & Numeric: concat, substring, trim, round, trigonometry, and more.
• JSON & Date: Specialized helpers for JSON mutation/validation and complex DATE_ADD/DATE_SUB calculations.
• Advanced: Bitwise operators, Encryption/Hashing (AES, SHA, MD5), and Window functions (rowNumber, rank, lag, lead).

🛡️ Parameterized Vector Inputs (Security Fix)

Improved the security and reliability of vector operations in VectorTiDB helpers.

• Placeholder Support: Inputs for VEC_FROM_TEXT are now properly parameterized using placeholders (?) instead of being inlined as raw strings.
• Injection Prevention: This change eliminates potential SQL injection risks when handling vector strings and ensures more predictable query execution.

📦 Dependency Updates

Updated npm dependencies to their latest versions to ensure improved compatibility, security, and overall performance.

🚀 What’s New

🔢 TiDB VECTOR Type Support for Forge SQL
Forge SQL ORM now supports the TiDB VECTOR data type and vector SQL helpers.

This means Forge SQL can now be used for vector search workloads on top of TiDB vector capabilities.

Typical use cases include:
• semantic search
• retrieval-augmented generation (RAG)
• recommendation scenarios
• storing embeddings directly in Forge SQL and querying them with vector distance functions

This release adds the foundation for AI-oriented SQL workflows while keeping relational data and vector embeddings in the same database.

📚 New Official-Style Vector Example
Added a new example project:
forge-sql-orm-example-vector

This example follows the same flow as the official TiDB SQL quickstart for vector search:
• create a vector table
• insert embeddings
• fetch stored rows
• run cosine-distance vector search

The goal is to make it easier to start with vector search in Forge using a practical example that mirrors the official TiDB documentation.

🕒 Fixed datetime Handling for Midnight Values
Fixed datetime processing for values where the time part is 00:00:00.

Midnight values are now handled correctly.

📦 Dependency Updates

Updated npm dependencies to their latest versions to ensure improved compatibility, security, and overall performance.

🚀 What’s New

⚡ Optimized Global Caching with Forge KVS

• Native KVS TTL Support: The global cache system now leverages the native Forge KVS TTL feature ({ ttl: { unit: "SECONDS", value: number } }) to mark entries as expired automatically.
• Batch Deletion (kvs.batchDelete): The deletion of outdated or evicted cache records in KVS has been significantly optimized. The ORM now uses the kvs.batchDelete method, which greatly improves the performance of cache invalidation and scheduled cleanup operations.
• Proactive Expiration Management: Since Forge KVS TTL deletion is asynchronous (and can take up to 48 hours), a large cache might impact INSERT/UPDATE performance. I've updated the architecture and documentation to highlight the optional clearCacheSchedulerTrigger for proactive, immediate cleanup of expired entries in batches.

🎓 New Atlas Camp Example Project

• Added a new real-world example project based on the recent Atlas Camp presentation: forge-sql-orm-example-atlascamp.
• 📺 Watch the presentation: Check out the full talk and demonstration on YouTube — Watch the video.

📦 Dependency Updates

• Updated npm dependencies to their latest versions to ensure improved compatibility, security, and overall performance.

Changes

• Added a new UI Kit example project.
• Updated dependencies for compatibility and security.
• Minor internal stability improvements.

Notes

• No functional changes.
• Recommended for all users to stay up-to-date with the latest fixes from external libraries.

Changes

• Updated dependency versions to improve compatibility and security.
• Minor internal stability improvements.

Notes

• No functional changes.
• Recommended for all users to stay up-to-date with the latest fixes from external libraries.

Organization Move & Infrastructure Updates

This release consolidates the repository into a dedicated GitHub Organization and updates the CI/CD tooling.

🚀 What’s New

📦 Repository Moved to Organization
The project is now hosted under the forge-sql-orm organization. Old URLs will automatically redirect to the new location.

• New URL: https://github.com/forge-sql-orm/forge-sql-orm
• Recommended: Update your local remote to match the new origin:

git remote set-url origin https://github.com/forge-sql-orm/forge-sql-orm.git

🛠 CI/CD & Tooling Updates

• SonarCloud Integration: Replaced Coveralls with SonarCloud for static analysis and security scanning.
• Husky & Knip: Added validation via pre-commit hooks. Commits are now checked locally for unused dependencies (knip), type safety, and linting rules.
• Test Coverage: Vitest coverage thresholds (>80%) are now enforced in the pipeline.

📄 Repository Standards
Added standard documentation files to define project processes:

• Security: Added SECURITY.md with disclosure guidelines.
• Contributing: Added CONTRIBUTING.md with setup instructions.
• Code of Conduct: Added CODE_OF_CONDUCT.md.
• Templates: Added structured Issue templates (including manifest.yaml fields) and a Pull Request template.

🚀 What’s New

🛡️ Safer Development WebTriggers.
Development WebTriggers now strictly verify the environment and will not run in Production. Note: Please remember to remove these triggers from your production manifest.

Available Developer WebTriggers:

• fetchSchemaWebTrigger. Generates a DDL script of the current Forge-SQL database, allowing schema export to any MySQL-compatible DB for debugging.
• dropSchemaMigrations. Performs a complete cleanup by dropping all tables and sequences.
• dropTableSchemaMigrations. Drops all tables while preserving sequences.

✨ Updated Examples • All examples have been updated to align with RoA eligibility. • Development triggers in examples are now disabled by default.

🐛 CLI Bug Fixes • Fixed various bugs in forge-sql-orm-cli to improve stability.

🤖 Improved Rovo Integration

• Added support for single quotes (') in context variables.
• Ensures correct syntax handling when wrapping variables for AI context.

📦 Dependency Updates • Dependencies updated for better stability.