knex_dart

A faithful port of Knex.js to Dart — a powerful, fluent SQL query builder for Dart backends.

Packages

Package	Description	Version
knex_dart	Core query builder (this package)
knex_dart_postgres	PostgreSQL driver
knex_dart_mysql	MySQL driver
knex_dart_sqlite	SQLite driver

knex_dart is the core package — it contains the query builder, schema builder, and compiler logic but no database connectivity. Pick the driver package for your database.

Installation

dependencies:
  knex_dart_postgres: ^0.1.0  # or mysql / sqlite

The driver package pulls in knex_dart automatically.

Quick Start

PostgreSQL

import 'package:knex_dart_postgres/knex_dart_postgres.dart';

final db = await KnexPostgres.connect(
  host: 'localhost',
  database: 'mydb',
  username: 'user',
  password: 'pass',
);

final users = await db.select(
  db('users').where('active', '=', true).limit(10),
);

await db.destroy();

SQLite

import 'package:knex_dart_sqlite/knex_dart_sqlite.dart';

final db = await KnexSQLite.connect(filename: ':memory:');

await db.executeSchema(
  db.schema.createTable('users', (t) {
    t.increments('id');
    t.string('name');
  }),
);

await db.insert(db('users').insert({'name': 'Alice'}));

MySQL

import 'package:knex_dart_mysql/knex_dart_mysql.dart';

final db = await KnexMySQL.connect(
  host: 'localhost',
  database: 'mydb',
  user: 'user',
  password: 'pass',
);

Query Builder

All driver packages expose the same Knex query builder API.

SELECT

// Basic
db('users').select(['id', 'name']).where('active', '=', true);

// Joins
db('users')
  .join('orders', 'users.id', '=', 'orders.user_id')
  .select(['users.name', 'orders.total'])
  .where('orders.status', '=', 'completed');

// Aggregates
db('sales')
  .count('* as total')
  .sum('amount as revenue')
  .where('status', '=', 'completed');

INSERT / UPDATE / DELETE

db('users').insert({'name': 'Alice', 'email': 'alice@example.com'});

db('users').where('id', '=', 1).update({'name': 'Bob'});

db('users').where('id', '=', 1).delete();

Advanced

// CTEs
db('active_users')
  .withRecursive('active_users', db('users').where('active', '=', true))
  .select(['*']);

// Upsert
db('users')
  .insert({'email': 'alice@example.com', 'name': 'Alice'})
  .onConflict('email')
  .merge();

// Raw
db.raw('select * from users where id = ?', [1]);

Schema Builder

await db.executeSchema(
  db.schema.createTable('posts', (t) {
    t.increments('id');
    t.string('title').notNullable();
    t.text('body');
    t.integer('user_id').references('id').inTable('users');
    t.timestamps();
  }),
);

Transactions

await db.trx((trx) async {
  await trx.insert(trx('accounts').insert({'balance': 100}));
  await trx.update(trx('accounts').where('id', '=', 1).update({'balance': 0}));
});

Side-by-Side: Knex.js vs knex_dart

Knex.js

knex('users')
  .select('name', 'email')
  .where('age', '>', 18)
  .orderBy('created_at', 'desc')
  .limit(10);

knex_dart

db('users')
  .select(['name', 'email'])
  .where('age', '>', 18)
  .orderBy('created_at', 'desc')
  .limit(10);

Features

• SELECT, INSERT, UPDATE, DELETE
• WHERE — basic, IN, NULL, BETWEEN, EXISTS, OR, raw
• JOINs — INNER, LEFT, RIGHT, FULL OUTER, CROSS, with callback builder
• Aggregates — COUNT, SUM, AVG, MIN, MAX with DISTINCT variants
• ORDER BY, GROUP BY, HAVING, LIMIT, OFFSET
• Raw queries with ?, :name, ?? binding formats
• RETURNING clause (PostgreSQL)
• CTEs (WITH / WITH RECURSIVE)
• UNIONs, INTERSECTs, EXCEPTs
• Subqueries
• JSON operators (whereJsonPath, whereJsonSupersetOf, etc.)
• Full-text search (whereFullText)
• Upserts (onConflict().merge())
• Schema builder — createTable, alterTable, dropTable, foreign keys, indexes
• Dialect-aware SQL (PostgreSQL $1, MySQL/SQLite ?)

Acknowledgments

This project is a port of Knex.js, created by Tim Griesser and contributors.

License

MIT — see LICENSE.