{"id":41119,"library":"forge-sql-orm","title":"Forge SQL ORM","description":"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.","status":"active","version":"2.1.29","language":"javascript","source_language":"en","source_url":"https://github.com/forge-sql-orm/forge-sql-orm","tags":["javascript","atlassian-forge","atlassian-forge-drizzle","forge-sql","forge","drizzle","drizzle-orm","drizzle-driver","drizzle-custom-driver","typescript"],"install":[{"cmd":"npm install forge-sql-orm","lang":"bash","label":"npm"},{"cmd":"yarn add forge-sql-orm","lang":"bash","label":"yarn"},{"cmd":"pnpm add forge-sql-orm","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency: required for database access in Forge","package":"@forge/sql","optional":false},{"reason":"Peer dependency: core ORM library","package":"drizzle-orm","optional":false}],"imports":[{"note":"Package is ESM-native; use import statements. CommonJS require may fail if bundler doesn't handle ESM.","wrong":"const forgeSqlDriver = require('forge-sql-orm').forgeSqlDriver","symbol":"forgeSqlDriver","correct":"import { forgeSqlDriver } from 'forge-sql-orm'"},{"note":"Named export; used for Level 1 caching.","wrong":"","symbol":"createLocalCache","correct":"import { createLocalCache } from 'forge-sql-orm'"},{"note":"Correct name is createGlobalCache, not createCache.","wrong":"import { createCache } from 'forge-sql-orm'","symbol":"createGlobalCache","correct":"import { createGlobalCache } from 'forge-sql-orm'"}],"quickstart":{"code":"import { forgeSqlDriver } from 'forge-sql-orm';\nimport { drizzle } from 'drizzle-orm';\nimport { sql } from '@forge/sql';\n\nconst driver = forgeSqlDriver({ sql });\nconst db = drizzle(driver);\n\n// Define schema with Drizzle\nconst users = pgTable('users', {\n  id: serial('id').primaryKey(),\n  name: text('name'),\n});\n\n// Query\nconst result = await db.select().from(users).where(eq(users.name, 'Alice'));\nconsole.log(result);","lang":"typescript","description":"Initializes the Drizzle driver with @forge/sql, defines a schema, and runs a select query."},"warnings":[{"fix":"Install both: npm install @forge/sql drizzle-orm","message":"The package requires both @forge/sql and drizzle-orm as peer dependencies; missing them will cause runtime errors.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Use import { ... } from 'forge-sql-orm' instead of require.","message":"CommonJS require() may not work due to ESM-only exports; use ES import syntax.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Ensure @forge/kvs is set up and imported before using createGlobalCache.","message":"Global cache requires @forge/kvs to be configured in the app; otherwise Level 2 caching will fail silently.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Migrate to explicit cache setup with createLocalCache/createGlobalCache.","message":"Method 'selectCacheableFrom' may be deprecated in favor of using caching decorators; check docs for current practice.","severity":"deprecated","affected_versions":">=2.1.0"}],"env_vars":null,"search_vec":"'activ':57 'altern':79 'analysi':38 'app':53 'atlassian':14,91,94 'atlassian-forg':90 'atlassian-forge-drizzl':93 'build':46 'built':66 'built-in':65 'cach':25,68 'cadenc':55 'custom':20,110 'differenti':63 'driver':21,107,111 'drizzl':10,76,96,101,103,106,109 'drizzle-custom-driv':108 'drizzle-driv':105 'drizzle-orm':102 'enabl':40 'featur':85 'forg':1,4,15,52,92,95,98,100 'forge-sql':97 'forge/kvs':31 'forge/sql':17,82 'frequent':59 'full':48 'global':29 'includ':64 'integr':12,74 'javascript':89 'key':62 'lack':83 'level':24 'like':80 'local':26 'lock':35 'memori':27 'migrat':33 'minor':60 'monitor':71 'optimist':34 'orm':3,6,11,77,104 'perform':70 'provid':18 'queri':37,45 'raw':81 'releas':54 'safe':43 'safeti':88 'schema':32 'seamless':73 'sql':2,5,44,99 'strategi':69 'support':50 'two':23 'two-level':22 'type':42,87 'type-saf':41 'typescript':49,112 'updat':61 'v2.1.29':7 'via':30 'wherea':78 'within':51","created_at":"2026-06-04T18:50:52.281364+00:00","updated_at":"2026-06-04T18:50:52.281364+00:00","problems":[{"fix":"Run: npm install forge-sql-orm @forge/sql drizzle-orm","cause":"Package not installed or not in node_modules","error":"Cannot find module 'forge-sql-orm'"},{"fix":"Use: import { forgeSqlDriver } from 'forge-sql-orm'","cause":"Incorrect import method (e.g., using require on ESM package)","error":"Error: forgeSqlDriver is not a function"},{"fix":"Ensure @forge/sql is initialized and passed as { sql } to forgeSqlDriver","cause":"Missing @forge/sql configuration or not passing sql instance to driver","error":"TypeError: Cannot read properties of undefined (reading 'query')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/forge-sql-orm/forge-sql-orm#readme","github":"https://github.com/forge-sql-orm/forge-sql-orm","docs":null,"changelog":null,"pypi":null,"npm":"forge-sql-orm","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-04","next_check":"2026-09-02","install_tag":null}}