@linked-db/linked-ql
Advanced tools
The application-flavoured SQL that runs anywhere, with pluggable, composable backends, with an offline- and sync-ready model
Portable query engine for modern applications and agents.
const db = new PGClient(); // or: MySQLClient | FlashQL | EdgeClient | etc
const result = await db.query(
`SELECT {
id,
profile: { name, email },
parent: parent_user ~> { name, email }
} FROM users;`,
{ live: true }
);
Show result: output shape + live behaviour
// Structured output (via "{ ... }"): result.rows[0].profile.name; // Foreign key traversal (via "~>"): result.rows[0].parent.name; // Live queries: // result.rows updates automatically as underlying data changes // (any reactive system can observe these updates) Observer.observe(result.rows[0].parent, 'email', (c) => { console.log(c.value, c.oldValue); });
LinkedQL brings:
Runs across:
→ All in just ~100 KiB (min+zip)
→ A single interface that drops into any application
See the overview ↗ for the full picture.
[!IMPORTANT] LinkedQL is shaping up fast, and currently backed by over 1,200 tests.
Feedback, issues, and PRs help drive us towards the next thousand tests and beyond.
See Contributing
LinkedQL is distributed as an npm package:
npm install @linked-db/linked-ql
It provides clients for all supported SQL dialects — including FlashQL, the embeddable SQL engine for local and offline use.
Import and use the client for your database.
| Client/Model | Import Path | Guide |
|---|---|---|
PGClient | @linked-db/linked-ql/postgres | PostgreSQL ↗ |
MySQLClient | @linked-db/linked-ql/mysql | MySQL ↗ |
MariaDBClient | @linked-db/linked-ql/mariadb | MariaDB ↗ |
FlashQL | @linked-db/linked-ql/flashql | FlashQL ↗ |
EdgeClient | @linked-db/linked-ql/edge | Edge / Browser ↗ |
EdgeWorker | @linked-db/linked-ql/edge-worker | Edge Worker ↗ |
See:
LinkedQL exposes a minimal and consistent database interface:
await db.query(sql, options);
await db.query(sql, { live: true, ...options });
await db.stream(sql, options);
await db.transaction(fn);
await db.wal.subscribe(selector, handler);
await db.sync.sync(); // (FlashQL)
The same surface applies whether db is a direct PostgreSQL client, a local FlashQL engine, or an EdgeClient.
See:
LinkedQL collapses the traditional data stack — database, API layer, and sync engine — into a single model.
The overview page is your map to what LinkedQL enables.
Below are a few examples that build up that model step by step.
JSON Literals let you define the exact shape your application expects directly in SQL.
const result = await db.query(`
SELECT {
id: u.id,
name: u.name,
profile: {
email: u.email,
age: u.age
}
} AS user
FROM users u;
`);
No remapping step or post-processing code. The query itself defines the shape.
This is fully covered in JSON Literals ↗
DeepRefs let you follow relationships directly in SQL using simple arrow notations.
| Notation | Meaning |
|---|---|
~> | forward traversal (follow a reference) |
<~ | reverse traversal (find dependents) |
const result = await db.query(`
SELECT
id,
parent_user ~> email AS parent_email
FROM users;
`);
This says:
→ "Given a foreign key (parent_user)"
→ "Tie in the referenced row; select email"
const result = await db.query(`
SELECT
id,
(parent_user <~ users) ~> email AS child_email
FROM users;
`);
This walks “backwards” through a relationship:
email column from eachconst result = await db.query(`
SELECT {
id,
profile: { name, email },
parent: parent_user ~> { id, name, email }
} FROM users;
`);
await db.query(`
INSERT INTO users
(email, parent_user ~> (id, email))
VALUES
('ada@example.com', ROW (50, 'parent@example.com'));
`);
This lets you construct relationships directly in an insert:
→ "Given a base row"
→ "Insert a related row that automatically references the base"
No need for an ORM or manual JOIN logic.
If you've defined foreign key relationships in your tables, you can traverse them directly in the query.
Deeper syntax and traversal patterns are fully covered in DeepRefs ↗.
LinkedQL brings live queries to your database: PostgreSQL, FlashQL, MySQL/MariaDB*.
With just a mode switch { live: true }, you get back a live, self-updating result set.
const result = await db.query(`
SELECT p.title, p.category
FROM posts AS p
WHERE p.published = true
ORDER BY p.created_at DESC
`, { live: true });
result.rows updates automatically as the database changes:
No need for dedicated GraphQL servers in front of your database.
The query itself is the subscription.
const result = await db.query(`
SELECT
p.title,
p.category,
author ~> { name, email } AS author
FROM posts AS p
WHERE p.published = true
ORDER BY p.created_at DESC
`, { live: true });
→ Supports the full SELECT range – joins, filters, aggregates, etc.
→ Supports the full set of LinkedQL syntax shorthands like DeepRefs and JSON Literals
See the full story in Live Queries ↗.
See the Realtime Engine ↗ paper for a deeper dive.
[!NOTE] Fully supported across:
- databases: PostgreSQL, FlashQL, etc. (MySQL/MariaDB support coming soon)
- runtimes and deployment models: client / server / worker / edge
Meet FlashQL – a full SQL engine that runs anywhere + inside your application.
It's LinkedQL's embeddable SQL engine.
import { FlashQL } from '@linked-db/linked-ql/flashql';
const db = new FlashQL();
await db.connect();
const result = await db.query(`
CREATE TABLE users (
id INT PRIMARY KEY,
name TEXT
);
INSERT INTO users VALUES (1, 'Ada'), (2, 'Linus');
SELECT * FROM users ORDER BY id;
`);
console.log(result.rows);
await db.disconnect();
FlashQL brings the full LinkedQL feature set into an embedded, local-first runtime.
Built for:
See FlashQL ↗ for a detailed overview.
LinkedQL uses a small set of primitives (EdgeClient, FlashQL) to unlock data federation, sync, and offline-first architectures.
For example:
You can spin up a FlashQL instance locally, backed by an upstream database.
const db = new FlashQL({
getUpstreamClient: (url) =>
new EdgeClient({ url, type: 'http' }),
});
await db.connect();
It lets you declare remote data as local tables (views):
await db.query(`
CREATE VIEW users AS
SELECT * FROM users
WITH (replication_origin = 'postgres:/api/db');
`);
This simple setup gives you data federation across boundaries:
query both local and remote data as one relational graph:
const result = await db.query(`
SELECT *
FROM users u
JOIN orders o ON o.user_id = u.id;
`);
With just an extra keyword, you get automatic sync between local and remote states:
await db.query(`
CREATE REALTIME VIEW users AS
SELECT * FROM users
WITH (replication_origin = 'postgres:/api/db');
`);
With a single abstraction:
What typically takes a database, API layer, cache, and sync engine is reduced to one relational model — expressed entirely in SQL.
This is fully covered in:
A visual, interactive playground that lets you experiment with these integration patterns is coming soon.
But here are real samples you can play with now, right in the @webqit/node-live-response repo:
If you want to explore the full LinkedQL model, see:
LinkedQL is in active development — and contributions are welcome!
Here’s how you can jump in:
⤷ clone → install → test
git clone https://github.com/linked-db/linked-ql.git
cd linked-ql
git checkout next
npm install
npm test
next branch — be sure to switch to it as above after cloning.next before making changes (e.g. git checkout -b feature/my-idea).npm test before submitting a PR.MIT — see LICENSE
FAQs
The application-flavoured SQL that runs anywhere, with pluggable, composable backends, with an offline- and sync-ready model
We found that @linked-db/linked-ql demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Five malicious NuGet packages impersonate Chinese .NET libraries to deploy a stealer targeting browser credentials, crypto wallets, SSH keys, and local files.
Security News
pnpm 11 turns on a 1-day Minimum Release Age and blocks exotic subdeps by default, adding safeguards against fast-moving supply chain attacks.
Security News
The remediated findings include organization permission bugs, stale project access after transfers, OIDC replay edge cases, audit logging gaps, and an IDOR in API token deletion.