orbit-sql

library0.4.2jsnpmunverified

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.

database

npm install orbit-sql

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ORBIT-SQL

orbit-sql

databasejavascriptv0.4.2

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.

SQLRecord

✓ import { SQLRecord } from 'orbit-sql'

✗ const SQLRecord = require('orbit-sql').SQLRecord

ESM is preferred; CommonJS require works with TypeScript esModuleInterop. Ensure Orbit is also imported.

default as orbitSQL

✓ import orbitSQL from 'orbit-sql'

✗ const orbitSQL = require('orbit-sql')

Default export is the orbitSQL object; named exports also available.

SQLRecord

✓ import { SQLRecord } from 'orbit-sql'

✗ import * as orbitSQL from 'orbit-sql'; const SQLRecord = orbitSQL.SQLRecord

Tree-shakable named imports reduce bundle size.

Sets up an in-memory SQLite database with Knex and runs a query using orbit-sql.

import orbitSQL from 'orbit-sql'; import { SQLRecord } from 'orbit-sql'; import Knex from 'knex'; const knexConfig = { client: 'sqlite3', useNullAsDefault: true, connection: { filename: ':memory:' } }; const db = Knex(knexConfig); const sql = orbitSQL({ db }); // Create a record type const userType = { type: 'user', attributes: { name: { type: 'string' } } }; // Query sql.query((q) => q.type('user').filter({ name: 'Alice' })).then(results => { console.log(results); });

Debug

Known issues

gotchaKnex instance must be provided directly. orbit-sql does not manage connections; you must handle connection pooling and cleanup.

fix

Always pass a Knex instance and call db.destroy() when the application shuts down.

affects: >=0.1.0

gotchaimport { SQLRecord } from 'orbit-sql' requires TypeScript's esModuleInterop or hasModule option enabled for CommonJS bundling.

fix

Enable esModuleInterop in tsconfig.json or use default import.

affects: >=0.3.0

breakingVersion 0.4.0 changed the export structure; named exports like 'SQLRecord' were moved to a subpath. Check import statements.

fix

Use import { SQLRecord } from 'orbit-sql' instead of 'orbit-sql/record'.

affects: >=0.4.0

Errors

Common errors & fixes

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

The orbit-sql instance was not created correctly; missing db parameter.

fix

const sql = orbitSQL({ db: knexInstance });

Error: knex: Cannot read properties of undefined (reading 'client')

Knex config missing 'client' property or incorrectly passed.

fix

Ensure db is a Knex instance: const db = Knex({ client: 'sqlite3', connection: { ... } });

No overload matches this call. Overload 1 of 3...

TypeScript expects a specific query callback signature.

fix

Use arrow function with explicit return: q => q.filter({ ... }); or check parameters.

Upgrade

Version history

0.4.2latest on npm

Audit

Dependencies

@orbit/corerequiredCore Orbit types and interfaces for record storage and querying

@orbit/record-cacheoptionalRecord cache implementation for in-memory data storage

knexrequiredSQL query builder for database interactions

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/tchak/orbit-sql ↗

packageorbit-sql ↗

homepagehttps://github.com/tchak/orbit-sql#readme ↗