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/linked-ql@0.3.*.
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 |
LinkedQL is distributed as an npm package. Install it with:
npm install @linked-db/linked-qlThe package provides clients for all supported SQL dialects — including FlashQL, the in-memory SQL engine for local or offline use.
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:
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 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();| Dialect | Import Path | Guide |
|---|---|---|
| PostgreSQL | @linked-db/linked-ql/postgres | PostgreSQL ↗ |
| MySQL | @linked-db/linked-ql/mysql | MySQL ↗ |
| MariaDB | @linked-db/linked-ql/mariadb | MariaDB ↗ |
| FlashQL (In-Memory) | @linked-db/linked-ql/flashql | FlashQL ↗ |
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 ↗
| 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. |
| 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. |
Visit the LinkedQL documentation site ↗
| Jump to | |
|---|---|
| Getting Started ↗ | Get started with LinkedQL in under three minutes. No database required |
| Capabilities Overview ↗ | Jump to the Capabilities section. |
| Meet FlashQL ↗ | Meet FlashQL — LinkedQL's embeddable SQL engine. |
| Engineering Deep Dive ↗ | Dig into LinkedQL's engineering in the engineering section. |
| Component | Status | Note |
|---|---|---|
| Parser & Compiler | 🟩 100% | Stabilizing |
| Transform Engine | 🟩 100% | Stabilizing |
| Drivers (PG/MySQL) | 🟩 97% | Stabilizing; MySQL nearing parity |
| FlashQL Engine | 🟩 99% | Expanding |
| Realtime Engine | 🟩 99% | Stabilizing |
| Timeline Engine | 🟨 20% | Planned |
| Migration Wizard | ⬜ 10% | Planned |
| IDE Tooling | ⬜ 5% | Early hooks |
| Docs (vNext) | 🟩 99% | Expanding |
Status Legend:
🟩 Complete | 🟨 In Progress | ⬜ Not Started
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.
⤷ clone → install → test
git clone https://github.com/linked-db/linked-ql.git cd linked-ql git checkout next npm install npm test- Development happens on the
nextbranch — be sure to switch to it as above after cloning. - Consider creating your feature branch from
nextbefore making changes (e.g.git checkout -b feature/my-idea). - Remember to
npm testbefore submitting a PR. - Check the Progress section above to see where help is most needed.
MIT — see LICENSE
