{"id":43518,"library":"orbit-sql","title":"orbit-sql","description":"SQL support for Orbit, a library for managing data synchronization and caching in JavaScript applications. orbit-sql provides SQL query building via Knex for server-side Orbit apps using PostgreSQL, MySQL, or SQLite. Current stable version is 0.4.2. The library integrates with the Orbit ecosystem, enabling SQL-backed records and queries. It is released on an as-needed basis, with a focus on Knex-based SQL support rather than raw queries. Key differentiators: built specifically for Orbit's data model, leverages Knex for cross-dialect compatibility, and provides typed query results in TypeScript.","status":"active","version":"0.4.2","language":"javascript","source_language":"en","source_url":"https://github.com/tchak/orbit-sql","tags":["javascript","orbit","sql","knex","typescript"],"install":[{"cmd":"npm install orbit-sql","lang":"bash","label":"npm"},{"cmd":"yarn add orbit-sql","lang":"bash","label":"yarn"},{"cmd":"pnpm add orbit-sql","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core Orbit types and interfaces for record storage and querying","package":"@orbit/core","optional":false},{"reason":"Record cache implementation for in-memory data storage","package":"@orbit/record-cache","optional":true},{"reason":"SQL query builder for database interactions","package":"knex","optional":false}],"imports":[{"note":"ESM is preferred; CommonJS require works with TypeScript esModuleInterop. Ensure Orbit is also imported.","wrong":"const SQLRecord = require('orbit-sql').SQLRecord","symbol":"SQLRecord","correct":"import { SQLRecord } from 'orbit-sql'"},{"note":"Default export is the orbitSQL object; named exports also available.","wrong":"const orbitSQL = require('orbit-sql')","symbol":"default as orbitSQL","correct":"import orbitSQL from 'orbit-sql'"},{"note":"Tree-shakable named imports reduce bundle size.","wrong":"import * as orbitSQL from 'orbit-sql'; const SQLRecord = orbitSQL.SQLRecord","symbol":"SQLRecord","correct":"import { SQLRecord } from 'orbit-sql'"}],"quickstart":{"code":"import orbitSQL from 'orbit-sql';\nimport { SQLRecord } from 'orbit-sql';\nimport Knex from 'knex';\n\nconst knexConfig = {\n  client: 'sqlite3',\n  useNullAsDefault: true,\n  connection: { filename: ':memory:' }\n};\n\nconst db = Knex(knexConfig);\nconst sql = orbitSQL({ db });\n\n// Create a record type\nconst userType = {\n  type: 'user',\n  attributes: { name: { type: 'string' } }\n};\n\n// Query\nsql.query((q) => q.type('user').filter({ name: 'Alice' })).then(results => {\n  console.log(results);\n});","lang":"typescript","description":"Sets up an in-memory SQLite database with Knex and runs a query using orbit-sql."},"warnings":[{"fix":"Always pass a Knex instance and call db.destroy() when the application shuts down.","message":"Knex instance must be provided directly. orbit-sql does not manage connections; you must handle connection pooling and cleanup.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Enable esModuleInterop in tsconfig.json or use default import.","message":"import { SQLRecord } from 'orbit-sql' requires TypeScript's esModuleInterop or hasModule option enabled for CommonJS bundling.","severity":"gotcha","affected_versions":">=0.3.0"},{"fix":"Use import { SQLRecord } from 'orbit-sql' instead of 'orbit-sql/record'.","message":"Version 0.4.0 changed the export structure; named exports like 'SQLRecord' were moved to a subpath. Check import statements.","severity":"breaking","affected_versions":">=0.4.0"}],"env_vars":null,"search_vec":"'0.4.2':43 'app':33 'applic':18 'as-need':63 'back':54 'base':73 'basi':66 'build':25 'built':82 'cach':15 'compat':95 'cross':93 'cross-dialect':92 'current':39 'data':12,87 'dialect':94 'differenti':81 'ecosystem':50 'enabl':51 'focus':69 'integr':46 'javascript':17,103 'key':80 'knex':27,72,90,106 'knex-bas':71 'leverag':89 'librari':9,45 'manag':11 'model':88 'mysql':36 'need':65 'orbit':2,7,20,32,49,85,104 'orbit-sql':1,19 'postgresql':35 'provid':22,97 'queri':24,57,79,99 'rather':76 'raw':78 'record':55 'releas':60 'result':100 'server':30 'server-sid':29 'side':31 'specif':83 'sql':3,4,21,23,53,74,105 'sql-back':52 'sqlite':38 'stabl':40 'support':5,75 'synchron':13 'type':98 'typescript':102,107 'use':34 'version':41 'via':26","created_at":"2026-06-05T17:00:10.890638+00:00","updated_at":"2026-06-05T17:00:10.890638+00:00","problems":[{"fix":"const sql = orbitSQL({ db: knexInstance });","cause":"The orbit-sql instance was not created correctly; missing db parameter.","error":"TypeError: Cannot read properties of undefined (reading 'query')"},{"fix":"Ensure db is a Knex instance: const db = Knex({ client: 'sqlite3', connection: { ... } });","cause":"Knex config missing 'client' property or incorrectly passed.","error":"Error: knex: Cannot read properties of undefined (reading 'client')"},{"fix":"Use arrow function with explicit return: q => q.filter({ ... }); or check parameters.","cause":"TypeScript expects a specific query callback signature.","error":"No overload matches this call. Overload 1 of 3..."}],"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/tchak/orbit-sql#readme","github":"https://github.com/tchak/orbit-sql","docs":null,"changelog":null,"pypi":null,"npm":"orbit-sql","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-05","next_check":"2026-09-03","install_tag":null}}