This document defines what Forge SQL ORM must deliver and which platform limits it must respect. It complements:

Official Atlassian references:

• Forge SQL — SQL storage, limits, schema management
• KVS and Custom Entity Store limits — limits relevant to global (Level 2) caching

Forge SQL ORM follows a documentation-first development model:

1. Every shipped feature is documented in README.md, forge-sql-orm-extra/README.md, or forge-sql-orm-cli/README.md before or together with the release that exposes it.
2. Removed or deprecated features are removed or marked in the same documentation in the release that removes them.
3. Breaking changes are called out in CHANGELOG.md and, when applicable, in the README migration sections.
4. Nothing intentionally undocumented — if it is part of the public API or behavior consumers rely on, it must appear in docs or linked examples.
5. Examples under examples/ demonstrate end-to-end usage for major capabilities (migrations, caching, vectors, Rovo, and others listed in the README).

This requirements document does not duplicate the full API; it states obligations and constraints. The README remains the detailed specification of behavior.

Provide a type-safe ORM layer for Atlassian Forge apps that use @forge/sql, built on Drizzle ORM, including migrations, caching, observability, and Forge-specific SQL types.

• npm package forge-sql-orm (core library)
• npm package forge-sql-orm-extra (extended library — global cache, Rovo, SQL-parser cache invalidation)
• npm package forge-sql-orm-cli (schema/migration tooling)
• Custom Drizzle driver for @forge/sql
• Schema migration queueing and execution patterns aligned with Forge SQL
• Optional two-level caching (in-memory + @forge/kvs)
• Query analysis, slow-query monitoring, and timeout/OOM diagnostics
• Forge/TiDB-oriented custom column types and SQL function helpers
• Documented example applications under examples/

• Hosting or provisioning Forge SQL (Atlassian platform responsibility)
• Replacing Drizzle ORM; consumers may still use Drizzle directly via the custom driver
• General-purpose ORM for non-Forge MySQL/TiDB deployments
• Atlassian Government Cloud (AGC) — Forge SQL is not supported on AGC at the time of writing; this library targets standard Forge environments where @forge/sql is available
• Guaranteed TiDB-specific features beyond what Forge SQL documents as supported; prefer ANSI SQL where possible

The repository is a monorepo with three independently published npm packages. Consumers choose packages at install time; runtime code lives in forge-sql-orm or forge-sql-orm-extra, not both as primary imports.

Feature placement rules:

• Capabilities that need only @forge/sql and Drizzle belong in core.
• Capabilities that need @forge/kvs, Rovo, or heavy optional parsers belong in extra (see NFR-9 bundle discipline).
• Tooling that runs outside Forge resolvers belongs in CLI.

Versioning: Packages share aligned major versions when breaking changes affect consumers across packages. Minor and patch versions may diverge between packages within the same major line.

Release channels:

Weekly publishes must run the quality gate defined in §8 before GPR upload; ephemeral ci.* GPR versions are not a consumer channel.

Each requirement maps to documentation in README.md unless noted.

The library must not encourage patterns that violate Atlassian platform limits. Implementations should fail gracefully or document constraints when limits apply.

Source: Forge SQL — Limitations (verify on Atlassian docs for updates).

Behavioral constraints

Per-install quotas

Per-query / per-response limits

Schema and data design recommendations (Atlassian)

• DDL changes must remain backward compatible with schema versions still migrating on customer sites.
• SQL used by older app versions must keep working on newer schemas.
• Avoid destructive schema changes that break cross-version compatibility.
• Avoid plain AUTO_INCREMENT hotspots; prefer AUTO_RANDOM or BINARY(16) UUIDs as documented by Atlassian/TiDB.

Source: KVS and Custom Entity Store limits.

Global caching must account for:

Design implications for FR-9–FR-11

• Cache entries must stay within 240 KiB per key; large result sets may require chunking or SQL-only strategies.
• High churn caches must respect RPS and read/write buckets; bulk workloads should use async events (Atlassian recommendation).
• Prefer batch KVS operations where the library batches writes/reads to reduce 10 KB rounding overhead.
• Do not store secrets in plain KVS values; use kvs.setSecret and encrypted environment variables for credentials.

Example of community-reported defect tracking: Issue #2128 (Forge lint / TypeScript duplicate property reporting).

Requirements in §3–§4 are verified by:

• Automated tests in the repository root (__tests__/, Vitest) and in workspace packages (forge-sql-orm-extra/__tests__/, forge-sql-orm-cli/__tests__/) with coverage thresholds per package
• CI workflow .github/workflows/node.js.yml (lint, build, test:coverage for core, extra, and CLI; dependency license compliance (license:check); SonarCloud, example builds, Forge deploy smoke paths)
• Manual review of README/CHANGELOG on each release
• Example applications built and deployed in CI (smoke validation of packaging and Forge app lifecycle; not a substitute for automated SQL integration tests)

Live integration tests against Forge SQL are not part of this repository’s automated test suite.

Forge SQL is a hosted, per-installation cloud database on Atlassian infrastructure. Running deterministic integration tests in CI would require a live Forge app installation, platform credentials, tenant-isolated data, and network access to @forge/sql on every pull request. That is impractical for an open-source library consumed across many sites and environments, and it would couple test reliability to external quota limits (see §5.1).

Strategy: mock the official low-level API (@forge/sql).

Instead of hitting a remote database, tests mock @forge/sql at the boundary the library actually uses — sql.prepare(query) returning objects with bindParams() and execute() — and assert the SQL strings, parameters, and ORM behavior (including Drizzle integration) end-to-end through the public API.

Primary suites (large, query-aware mocks):

Additional tests use the same @forge/sql mock pattern where needed (e.g. ForgeSQLLocalCache.test.ts, forgeDriver.test.ts, migration web triggers under __tests__/src/webtriggers/).

This approach satisfies integration-style coverage of the ORM stack (Drizzle → custom driver → @forge/sql call shape) without a cloud database. Manual validation against real Forge SQL remains the responsibility of app authors and is supported via documented examples/* apps and CI Forge deploy steps.

Forge SQL ORM is solo-maintained. To keep review discipline at the level a quality rubric expects without a second human reviewer, every pull request to master is reviewed by an automated pipeline whose comments are treated as binding review items.

Pipeline (runs on every PR):

Comment resolution policy:

• Every comment posted by any of the tools above is a mandatory review item, regardless of severity (info/minor included).
• A human maintainer must resolve every comment before merge — by fixing the code, by replying with explicit reasoning that the comment is wrong or inapplicable and marking it resolved, or by filing a follow-up issue if the concern is out of scope.
• Auto-merge is enabled only after the pipeline passes and every outstanding bot comment has been resolved by a human.
• PRs with unresolved bot comments will not be merged.

This pipeline, combined with mandatory human-driven comment resolution, satisfies the "code review" quality dimension on a solo-maintained project. See CONTRIBUTING.md — Pull Request Review Policy for the contributor-facing version of this policy.

Last updated: 2026-06-05 (release channels §2.4; NFR-5 weekly GPR)