queryflow 0.6.0
queryflow: ^0.6.0 copied to clipboard
Queryflow is a lightweight and flexible Query Builder designed to simplify the process of building and executing SQL queries to MySQL and PostgreSQL.
Queryflow #
A lightweight, type-safe SQL query builder and schema manager for MySQL and PostgreSQL, written in Dart.
Queryflow lets you compose parameterized SQL with a fluent API, map rows to typed models, and keep table definitions next to your code — without code generation.
final users = await db
.select('users', ['id', 'name', 'email'])
.where('active', Equals(true))
.orderBy(['name'], OrderByType.asc)
.limit(20)
.fetch();
Documentation #
📚 Full documentation: https://docs.page/RafaelBarbosatec/queryflow
| Guide | Description |
|---|---|
| Introduction | What Queryflow is and what it includes. |
| Quick start | A complete CRUD walkthrough. |
| Query builder | SELECT, WHERE, JOINs, sorting, and aggregates. |
| Models | Type adapters and typed CRUD. |
| Schema management | TableModel, synchronization, views, and events. |
| Transactions | Atomic operations and rollback. |
| MySQL vs PostgreSQL | Dialect differences and gotchas. |
| API reference | Generated Dart API docs. |
Features #
- Fluent, parameterized queries —
SELECT,INSERT,UPDATE,DELETE, joins, aggregates, grouping, ordering, and paging. - Rich WHERE matchers — comparisons, ranges, dates,
LIKE,IN, null checks, negation, and raw conditions. - Typed models —
TypeAdapterandQueryTypeAdapterforfetchAs,selectModel,insertModel,updateModel, anddeleteModel. - Schema as code —
TableModeldefinitions, column types, primary keys, unique constraints, foreign keys, defaults, and initial data. - Schema synchronization — create missing tables and columns, with destructive changes opt-in.
- Views and MySQL events — manage views on both databases and scheduled events on MySQL.
- Transactions —
executeTransactionwith automatic rollback. - Connection pooling — single connection by default, pool via
maxConnections. - Both databases — dialect-aware quoting, placeholders, auto increment,
enums, and
RETURNING.
Supported databases #
| MySQL | PostgreSQL | |
|---|---|---|
| CRUD, joins, aggregates | ✅ | ✅ |
| Transactions | ✅ | ✅ |
| Schema synchronization | ✅ | ✅ |
| Views | ✅ | ✅ |
| Scheduled events | ✅ | — |
FULL OUTER JOIN |
— | ✅ |
? placeholders |
✅ | ✅ (converted) |
$1, $2, ... placeholders |
— | ✅ |
See Database support for the full compatibility matrix.
Installation #
dependencies:
queryflow: ^0.6.0
dart pub get
Requires Dart >= 3.0.0 < 4.0.0. Queryflow runs on the Dart VM and on Flutter
mobile/desktop; it is not compatible with Flutter web.
Quick start #
1. Define a model and table #
import 'package:queryflow/queryflow.dart';
class User {
final int? id;
final String name;
final DateTime createdAt;
User({required this.name, required this.createdAt, this.id});
Map<String, dynamic> toMap() => {
if (id != null) 'id': id,
'name': name,
'created_at': createdAt.toIso8601String(),
};
factory User.fromMap(Map<String, dynamic> map) => User(
id: map['id'] as int?,
name: map['name'] as String,
createdAt: map['created_at'] as DateTime,
);
static final table = TableModel(
name: 'users',
columns: {
'id': TypeInt(isPrimaryKey: true, isAutoIncrement: true),
'name': TypeVarchar(length: 120),
'created_at': TypeDateTime(),
},
);
static final adapter = QueryTypeAdapter<User>(
table: table.name,
primaryKeyColumn: table.primaryKeyColumn,
toMap: (user) => user.toMap(),
fromMap: User.fromMap,
);
}
2. Connect #
// MySQL
final db = Queryflow.mysql(
host: '127.0.0.1',
port: 3306,
userName: 'root',
password: 'secret',
databaseName: 'app',
typeAdapters: [User.adapter],
tables: [User.table],
);
// PostgreSQL
final db = Queryflow.postgresql(
host: '127.0.0.1',
port: 5432,
userName: 'postgres',
password: 'secret',
databaseName: 'app',
typeAdapters: [User.adapter],
tables: [User.table],
);
3. Synchronize and query #
await db.synchronize();
final id = await db.insertModel(
User(name: 'Ada', createdAt: DateTime.now()),
);
final users = await db
.selectModel<User>()
.where('name', Like('A%'))
.orderBy(['name'], OrderByType.asc)
.fetch();
await db.updateModel(
User(id: id, name: 'Ada Lovelace', createdAt: DateTime.now()),
);
await db.deleteModel(
User(id: id, name: 'Ada', createdAt: DateTime.now()),
);
await db.close();
4. Transactions #
await db.executeTransaction((tx) async {
final userId = await tx.insertModel(
User(name: 'Grace', createdAt: DateTime.now()),
);
// Assuming Profile is another model with a registered adapter:
await tx.insertModel(
Profile(userId: userId, bio: 'Computer scientist'),
);
});
Examples #
Runnable examples live in the
example/
directory:
Development #
dart pub get
dart format .
dart analyze
dart test
The integration tests require MySQL and PostgreSQL. See Contributing for the database setup.
Contributing #
Issues and pull requests are welcome: github.com/RafaelBarbosatec/queryflow.
License #
MIT — see LICENSE.