Flutter SQL构建插件dart_sql_builder的使用

dart_sql_builder 是一个强大的、灵活的查询构建器，用于 Dart 语言。它简化了创建复杂 SQL 查询的过程。它不是 ORM，也不是类型安全的，但提供了更易读和可维护的方式来构建 SQL 查询，而无需编写原始的 SQL 字符串。

该包包括对各种查询类型的支持，包括 SELECT、INSERT、UPDATE 和 DELETE 查询。它还提供了一个方便的 API 来链式连接查询组件，使您可以轻松地创建复杂的查询，而无需太多努力。

除了核心的查询构建功能外，dart_sql_builder 还计划在未来进行一些增强，例如：

• 管理数据库表的迁移工具
• 支持除 PostgreSQL 之外的其他 SQL 驱动程序
• 帮助创建类型安全查询的构建器

dart_sql_builder 包附带了一个内置的 PostgreSQL 驱动程序，可以轻松集成到您的 Dart 项目中。以下是如何使用该包与 PostgreSQL 驱动程序一起工作的示例：

final postgreSQL = PostgreSQL();
final selectQuery = postgreSQL.select;
final insertQuery = postgreSQL.insert;
final updateQuery = postgreSQL.update;
final deleteQuery = postgreSQL.delete;

您可以使用 PostgreSQL 运行查询：

final postgreSQL = PostgreSQL();

await postgreSQL.open();

final query = postgreSQL.select
  ..select(['name', 'age'])
  ..from('users')
  ..where('age > ?', [30]);

await query.query();
await query.queryMapped();
await query.execute();

或者运行原始查询：

final postgreSQL = PostgreSQL();
final query = 'SELECT COUNT(*) FROM users';

await postgreSQL.rawQuery(query);
await query.rawQueryMapped(query);
await query.rawExecute(query);

基础 Query 类作为所有查询的基础，并且可以扩展以支持额外的数据库驱动程序和自定义查询类型。

在以下部分中，您将找到每个受支持查询类型的详细文档：SelectQuery、InsertQuery、UpdateQuery 和 DeleteQuery。这些指南将帮助您了解如何有效地使用 dart_sql_builder 包来构建 SQL 查询，以满足您的 Dart 应用程序需求。

现在，深入学习每个查询类型的文档，以了解如何充分利用 dart_sql_builder 包：

1. SelectQuery 📖
2. InsertQuery 📝
3. UpdateQuery 🔄
4. DeleteQuery ❌

InsertQuery

向数据库表中添加新行。InsertQuery 允许您一次插入单个或多个行，甚至提供冲突处理选项来处理唯一约束。

使用方法

要使用 InsertQuery，您首先需要创建一个实例。然后可以链式调用方法来构建所需的查询。

示例

以下是如何构建一个简单的 INSERT 查询的示例：

final query = InsertQuery()
  ..into('users')
  ..insert({'name': 'John Doe', 'age': 30});

这将生成以下 SQL 查询：

INSERT INTO users (name, age) VALUES ('John Doe', 30);

方法

into

into 方法用于指定要插入的表。

query.into('users');

insert

insert 方法用于指定要插入的列值。您可以传递一个包含列名及其相应值的映射。

query.insert({'name': 'John Doe', 'age': 30});

insertAll

insertAll 方法用于一次性插入多行。您可以传递一个包含列名及其相应值的映射列表。

query.insertAll([
  {'name': 'John Doe', 'age': 30},
  {'name': 'Jane Doe', 'age': 25}
]);

onConflictDoNothing

onConflictDoNothing 方法用于指定如果发生指定列的冲突，则插入操作应该什么也不做。

query.insert({'name': 'John Doe', 'age': 30, 'unq': 'test'}).onConflictDoNothing(['unq']);

onConflictDoUpdate

onConflictDoUpdate 方法用于指定如果发生冲突，则插入操作应该更新指定列。

query.insert({'name': 'John Doe', 'age': 30, 'unq': 'test'}).onConflictDoUpdate(['unq'], {'age': 31});

returning

returning 方法用于指定插入操作后要返回的列。您可以传递一个包含列名的字符串数组。

query.returning(['id']);

returnAll

returnAll 方法用于在插入操作后返回所有列。

query.returnAll();

示例

以下是使用 InsertQuery 构建复杂 INSERT 查询的示例：

final query = InsertQuery()
  ..into('users')
  ..insert({'name': 'John Doe', 'age': 30, 'unq': 'test'})
  ..onConflictDoUpdate(['unq'], {'age': 31})
  ..returnAll();

这将生成以下 SQL 查询：

INSERT INTO users (name, age, unq) VALUES ('John Doe', 30, 'test')
ON CONFLICT (unq) DO UPDATE SET age = 31 RETURNING *;

SelectQuery

从数据库表中检索数据。通过 SelectQuery，您可以过滤、排序、分组和连接数据，从而轻松获取所需的数据。

使用方法

要使用 SelectQuery，您首先需要创建一个实例。然后可以链式调用方法来构建所需的查询。

示例

以下是如何构建一个简单的 SELECT 查询的示例：

final query = SelectQuery()
  ..select(['name', 'age'])
  ..from('users')
  ..where('age > ?', [30]);

这将生成以下 SQL 查询：

SELECT name, age FROM users WHERE age > 30;

方法

select

select 方法用于指定要在查询中选择的列。您可以传递一个包含列名的字符串数组。

query.select(['name', 'age']);

selectAll

selectAll 方法用于选择查询中的所有列。

query.selectAll();

selectDistinct

selectDistinct 方法用于为指定列选择唯一值。

query.selectDistinct(['age']);

from

from 方法用于指定要从中选择数据的表。

query.from('users');

where

where 方法用于添加一个 WHERE 条件到查询中。您可以传递一个表示条件的字符串和一个替换条件中占位符的值数组。

query.where('age > ?', [30]);

and

and 方法用于添加一个 AND 操作符到查询中，允许您链接多个 WHERE 条件。

query.where('age > ?', [30]).and().where('country = ?', ['USA']);

or

or 方法用于添加一个 OR 操作符到查询中，允许您链接多个 WHERE 条件。

query.where('age > ?', [30]).or().where('country = ?', ['USA']);

join

join 方法用于将另一个表连接到查询中。您可以传递表名、ON 条件和连接类型（默认是 INNER JOIN）。

query.join('orders', 'users.id = orders.user_id');

groupBy

groupBy 方法用于按一个或多个列分组结果。

query.groupBy(['country']);

having

having 方法用于添加一个 HAVING 条件到查询中，与 GROUP BY 结合使用以过滤结果。

query.having('COUNT(*) > ?', [1]);

orderBy

orderBy 方法用于按一个或多个列排序结果。您可以传递一个包含列名的数组和一个包含 Order 枚举值（Order.asc 或 Order.desc）的数组来为每个列指定顺序。

query.orderBy(['age'], [Order.desc]);

limit

limit 方法用于限制查询返回的结果数量。

query.limit(10);

offset

offset 方法用于指定查询返回结果的起始点。

query.offset(20);

示例

以下是使用 SelectQuery 构建复杂 SELECT 查询的示例：

final query = SelectQuery()
  ..select(['users.name', 'orders.product'])
  ..from('users')
  ..join('orders', 'users.id = orders.user_id', JoinType.left)
  ..where('users.age > ?', [21])
  ..and()
  ..where('users.country = ?', ['USA'])
  ..groupBy(['users.name', 'orders.product'])
  ..orderBy(['users.name'], [Order.desc])
  ..limit(10);

这将生成以下 SQL 查询：

SELECT users.name, orders.product
FROM users
LEFT JOIN orders ON users.id = orders.user_id
WHERE users.age > 21 AND users.country = 'USA'
GROUP BY users.name, orders.product
ORDER BY users.name DESC
LIMIT 10;

UpdateQuery

修改数据库中的现有数据。UpdateQuery 允许您基于一组条件更新表中的特定列，从而使您可以轻松地应用更改到目标行。

使用方法

要使用 UpdateQuery，您首先需要创建一个实例。然后可以链式调用方法来构建所需的查询。

示例

以下是如何构建一个简单的 UPDATE 查询的示例：

final query = UpdateQuery()
  ..update('users')
  ..set({'name': 'John Doe', 'age': 31})
  ..where('id = ?', [1]);

这将生成以下 SQL 查询：

UPDATE users SET name = 'John Doe', age = 31 WHERE id = 1;

方法

update

update 方法用于指定要更新的表。

query.update('users');

set

set 方法用于指定要设置的列值。您可以传递一个包含列名及其相应值的映射。

query.set({'name': 'John Doe', 'age': 31});

where

where 方法用于添加一个 WHERE 条件到查询中。您可以传递一个表示条件的字符串和一个替换条件中占位符的值数组。

query.where('id = ?', [1]);

and

and 方法用于添加一个 AND 操作符到查询中，允许您链接多个 WHERE 条件。

query
    ..where('age > ?', [30])
    ..and()
    ..where('country = ?', ['USA']);

or

or 方法用于添加一个 OR 操作符到查询中，允许您链接多个 WHERE 条件。

query
    ..where('age > ?', [30])
    ..or()
    ..where('country = ?', ['USA']);

returning

returning 方法用于指定更新操作后要返回的列。您可以传递一个包含列名的字符串数组。

query.returning(['id']);

returnAll

returnAll 方法用于在更新操作后返回所有列。

query.returnAll();

示例

以下是使用 UpdateQuery 构建复杂 UPDATE 查询的示例：

final query = UpdateQuery()
  ..update('users')
  ..set({'name': 'John Doe', 'age': 31})
  ..where('age > ?', [21])
  ..and()
  ..where('country = ?', ['USA'])
  ..returnAll();

这将生成以下 SQL 查询：

UPDATE users SET name = 'John Doe', age = 31 WHERE age > 21 AND country = 'USA' RETURNING *;

DeleteQuery

从数据库中删除数据。DeleteQuery 允许您基于特定条件从表中删除行，确保您只删除预期的数据。

使用方法

要使用 DeleteQuery，您首先需要创建一个实例。然后可以链式调用方法来构建所需的查询。

示例

以下是如何构建一个简单的 DELETE 查询的示例：

final query = DeleteQuery()
  ..deleteFrom('users')
  ..where('id = ?', [1]);

这将生成以下 SQL 查询：

DELETE FROM users WHERE id = 1;

方法

deleteFrom

deleteFrom 方法用于指定要从中删除的表。

query.deleteFrom('users');

where

where 方法用于添加一个 WHERE 条件到查询中。您可以传递一个表示条件的字符串和一个替换条件中占位符的值数组。

query.where('id = ?', [1]);

and

and 方法用于添加一个 AND 操作符到查询中，允许您链接多个 WHERE 条件。

query.where('age > ?', [30]).and().where('country = ?', ['USA']);

or

or 方法用于添加一个 OR 操作符到查询中，允许您链接多个 WHERE 条件。

query.where('age > ?', [30]).or().where('country = ?', ['USA']);

returning

returning 方法用于指定删除操作后要返回的列。您可以传递一个包含列名的字符串数组。

query.returning(['id']);

returnAll

returnAll 方法用于在删除操作后返回所有列。

query.returnAll();

示例

以下是使用 DeleteQuery 构建复杂 DELETE 查询的示例：

final query = DeleteQuery()
  ..deleteFrom('users')
  ..where('age > ?', [21])
  ..and()
  ..where('country = ?', ['USA'])
  ..returnAll();

这将生成以下 SQL 查询：

DELETE FROM users WHERE age > 21 AND country = 'USA' RETURNING *;

总结 🎁

社区的贡献有助于改进和扩展该包的功能和能力，始终受到欢迎。

dart_sql_builder 在 MIT 许可证下发布，这意味着您可以自由使用、修改和分发代码。

记住，dart_sql_builder 是用心制作的，并期待着在您的支持下成长和发展。

祝您编码愉快！🚀

以下是一个完整的示例代码，展示了如何使用 dart_sql_builder 进行基本的 CRUD 操作和事务处理：

final psqlConnectionString = 'postgresql://postgres:123456[@localhost](/user/localhost):5432/postgres';

Future<void> selectExample() async {
  final db = PostgresSQL.connectionString(psqlConnectionString);

  await db.open();

  final query = db.select..from('your_table');
  query.where('column_name = ?', ['value']);

  final result = await query.queryMapped();
  print(result);

  await db.close();
}

Future<void> insertExample() async {
  final db = PostgresSQL.connectionString(psqlConnectionString);

  await db.open();

  final query = db.insert;
  query.into('your_table');
  query.insert({
    'column1': 'value1',
    'column2': 'value2',
    'column3': 'value3',
  });

  final resultInfo = await query.queryMapped();
  print(resultInfo);

  await db.close();
}

Future<void> updateExample() async {
  final db = PostgresSQL.connectionString(psqlConnectionString);

  await db.open();

  final query = db.update;
  query.update('your_table');
  query.set({
    'column1': 'value1',
    'column2': 'value2',
    'column3': 'value3',
  });

  query.where('id = 1');
  await query.execute();

  await db.close();
}

Future<void> deleteExample() async {
  final db = PostgresSQL.connectionString(psqlConnectionString);

  await db.open();

  final query = db.delete;
  query.deleteFrom('your_table');
  query.where('id = 1');
  await query.execute();

  await db.close();
}

Future<void> transactionExample() async {
  final db = PostgresSQL.connectionString(psqlConnectionString);

  await db.open();

  await db.tx((connection) async {
    final selectQuery = db.select..from('your_table');
    final updateQuery = db.update..update('your_table');

    // 使用块参数提供的 `connection` 运行您的查询。
    await selectQuery.query(tx: connection);
    await updateQuery.execute(tx: connection);
  });

  await db.close();
}

void main() async {
  print("\n---Select Example---");
  await selectExample();

  print("\n---Insert Example---");
  await insertExample();

  print("\n---Update Example---");
  await updateExample();

  print("\n---Delete Example---");
  await deleteExample();

  print("\n---Transaction Example---");
  await transactionExample();
}