forge-sql-orm

library2.1.29jsnpmunverified

Forge SQL ORM (v2.1.29) is a Drizzle ORM integration for Atlassian Forge's @forge/sql, providing a custom driver, two-level caching (local memory and global via @forge/kvs), schema migration, optimistic locking, and query analysis. It enables type-safe SQL query building with full TypeScript support within Forge apps. Release cadence is active, with frequent minor updates. Key differentiators include built-in caching strategies, performance monitoring, and seamless integration with Drizzle ORM, whereas alternatives like raw @forge/sql lack these features and type safety.

database

npm install forge-sql-orm

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FORGE-SQL-ORM

forge-sql-orm

databasejavascriptv2.1.29

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

forgeSqlDriver

✓ import { forgeSqlDriver } from 'forge-sql-orm'

✗ const forgeSqlDriver = require('forge-sql-orm').forgeSqlDriver

Package is ESM-native; use import statements. CommonJS require may fail if bundler doesn't handle ESM.

createLocalCache

✓ import { createLocalCache } from 'forge-sql-orm'

Named export; used for Level 1 caching.

createGlobalCache

✓ import { createGlobalCache } from 'forge-sql-orm'

✗ import { createCache } from 'forge-sql-orm'

Correct name is createGlobalCache, not createCache.

Initializes the Drizzle driver with @forge/sql, defines a schema, and runs a select query.

import { forgeSqlDriver } from 'forge-sql-orm'; import { drizzle } from 'drizzle-orm'; import { sql } from '@forge/sql'; const driver = forgeSqlDriver({ sql }); const db = drizzle(driver); // Define schema with Drizzle const users = pgTable('users', { id: serial('id').primaryKey(), name: text('name'), }); // Query const result = await db.select().from(users).where(eq(users.name, 'Alice')); console.log(result);

Debug

Known issues

gotchaThe package requires both @forge/sql and drizzle-orm as peer dependencies; missing them will cause runtime errors.

fix

Install both: npm install @forge/sql drizzle-orm

affects: >=2.0.0

gotchaCommonJS require() may not work due to ESM-only exports; use ES import syntax.

fix

Use import { ... } from 'forge-sql-orm' instead of require.

affects: >=2.0.0

gotchaGlobal cache requires @forge/kvs to be configured in the app; otherwise Level 2 caching will fail silently.

fix

Ensure @forge/kvs is set up and imported before using createGlobalCache.

affects: >=2.0.0

deprecatedMethod 'selectCacheableFrom' may be deprecated in favor of using caching decorators; check docs for current practice.

fix

Migrate to explicit cache setup with createLocalCache/createGlobalCache.

affects: >=2.1.0

Errors

Common errors & fixes

Cannot find module 'forge-sql-orm'

Package not installed or not in node_modules

fix

Run: npm install forge-sql-orm @forge/sql drizzle-orm

Error: forgeSqlDriver is not a function

Incorrect import method (e.g., using require on ESM package)

fix

Use: import { forgeSqlDriver } from 'forge-sql-orm'

TypeError: Cannot read properties of undefined (reading 'query')

Missing @forge/sql configuration or not passing sql instance to driver

fix

Ensure @forge/sql is initialized and passed as { sql } to forgeSqlDriver

Upgrade

Version history

2.1.29latest on npm

Audit

Dependencies

@forge/sqlrequiredPeer dependency: required for database access in Forge

drizzle-ormrequiredPeer dependency: core ORM library

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/forge-sql-orm/forge-sql-orm ↗

packageforge-sql-orm ↗

homepagehttps://github.com/forge-sql-orm/forge-sql-orm#readme ↗