@linked-db/linked-ql

v0.4.5009

Published

6 days ago

A query client that extends standard SQL with new syntax sugars and enables auto-versioning capabilities on any database

0High
0Medium
0Low

ox-harris

Linked DB Arrow Joins IndexedDB MySQL PostgreSQL

LinkedQL

A modern take on SQL and SQL databases

Simplify and unify your entire database layer in a single interface 🛸 LinkedQL is a database client (client.query()) for PostgreSQL and MySQL/MariaDB, but more broadly, an idea: SQL reimagined for modern apps ↗. LinkedQL solves reactivity, relationships, JSON, schemas, embedding, federation & sync, and more in under 80 KiB min | zip.

[!NOTE] You’re viewing @linked-db/linked-ql — the newest iteration.
For the prev 0.3.x branch, see linked-db/[email protected].*.

[!IMPORTANT] 🚀 LinkedQL is in active development and evolving daily. Current status = alpha. You’re welcome to experiment, but it’s not yet suited for production apps.

| Guide | Explore | Project | |:------------------------------------------|:----------------------------------------------|:----------------------------------| | Installation | Capabilities | Status | | Clients & Dialects | Features | Contributing | | Query Interface | Documentation | License |

Installation

LinkedQL is distributed as an npm package. Install it with:

npm install @linked-db/linked-ql

The package provides clients for all supported SQL dialects — including FlashQL, the in-memory SQL engine for local or offline use.

Initialization

Import and initialize the client for your use case. You can run either fully in-memory or with a database. Here are two quick examples:

Run Locally with FlashQL

FlashQL lets you run SQL queries entirely in memory — with zero setup.

import { FlashQL } from '@linked-db/linked-ql/flashql';

const client = new FlashQL();

await client.query(`CREATE TABLE users (id INT PRIMARY KEY, name TEXT)`);
const result = await client.query(`
  INSERT INTO users (id, name) VALUES (1, 'Ada'), (2, 'Linus');
  SELECT * FROM users;
`);

console.log(result.rows);
// [{ id: 1, name: 'Ada' }, { id: 2, name: 'Linus' }]

FlashQL is ideal for:

Local-first and offline-first apps
Running SQL over runtime data
Testing and prototyping

Connect to a Database

Connect to your database from the list of supported dialects below. Here’s an example using PostgreSQL:

import { PGClient } from '@linked-db/linked-ql/postgres';

const client = new PGClient({
  host: 'localhost',
  port: 5432,
  user: 'postgres',
  password: 'password',
  database: 'myapp',
});

await client.connect();

const result = await client.query(`SELECT 10 AS value`);
console.log(result.rows); // [{ value: 10 }]

await client.disconnect();

Clients & Dialects

Query Interface

LinkedQL maintains a unified and familiar interface across all dialects — whether remote or local. Method signatures and return values are consistent and documented in the Client API Reference ↗

Capabilities

| Capability | Description | | :---------------------------- | :----------------------------------------------------------------------------------------------------------------------------- | | ⚡ Live Queries | Turn on reactivity over any SQL query with { live: true }. No extra infrastructure required. | | 🔗 DeepRef Operators | Traverse relationships using simple path notation (~> / <~). Insert or update nested structures using same notation. | | 🧩 JSON Literals | Bring JSON-like clearity to your queries with LinkedQL's first-class support for JSON notation. | | 🪄 Upserts | Do upserts with a literal UPSERT statement. | | 🧠 Schema Versioning | (Coming soon) Get automatic schema versioning on your database: automatic snapshots and historical introspection. | | 💾 Edge & Offline Runtime | (FlashQL) Run or embed SQL locally — in browsers, workers, or edge devices — for local-first and offline-first applications. | | 🌐 Federation & Sync | (Alpha) Unify remote databases, REST endpoints, and local stores into a single relational graph with seamless synchronization. |

Features

| Feature | Description | | :---------------------------------------- | :------------------------------------------------------------------------------------------------------ | | 💻 Classic client.query() Interface | Same classic client interface; advanced capabalities for modern applications. | | 🔗 Multi-Dialect Support | A universal parser that understands PostgreSQL, MySQL, MariaDB, and FlashQL — one client, many dialects. | | 💡 Lightweight Footprint | A full reactive data layer in one compact library — under 80 KiB (min/zip). | | 🎯 Automatic Schema Inference | No upfront schema work. LinkedQL auto-discovers your schema and stays schema-driven across complex tasks. | | 🪄 Diff-Based Migrations | (Coming soon) Evolve schemas declaratively through change detection instead of hand-written migration scripts. |

Documentation

Visit the LinkedQL documentation site ↗

⏳ Status

🟩 Complete | 🟨 In Progress | ⬜ Not Started

🤝 Contributing

LinkedQL is in active development — and contributions are welcome!

Here’s how you can jump in:

Issues → Spot a bug or have a feature idea? Open an issue.
Pull requests → PRs are welcome for fixes, docs, or new ideas.
Discussions → Not sure where your idea fits? Start a discussion.

🛠️ Local Setup

⤷ clone → install → test

git clone https://github.com/linked-db/linked-ql.git
cd linked-ql
git checkout next
npm install
npm test

📝 Tips

Development happens on the next branch — be sure to switch to it as above after cloning.
Consider creating your feature branch from next before making changes (e.g. git checkout -b feature/my-idea).
Remember to npm test before submitting a PR.
Check the Progress section above to see where help is most needed.

🔑 License

MIT — see LICENSE