diff --git a/packages/storage_sdk/lib/src/presentation/facade/storage_sdk_api.dart b/packages/storage_sdk/lib/src/presentation/facade/storage_sdk_api.dart
index 70b2015..d6e6861 100644
--- a/packages/storage_sdk/lib/src/presentation/facade/storage_sdk_api.dart
+++ b/packages/storage_sdk/lib/src/presentation/facade/storage_sdk_api.dart
@@ -56,11 +56,26 @@ abstract class StorageSdkApi {
   factory StorageSdkApi({
     required GeneratedDatabase Function(QueryExecutor) databaseFactory,
     required Map<Type, TableInfo> Function(GeneratedDatabase) tableRegistry,
-  }) =>
-      StorageSdkWiring.build(
-        databaseFactory: databaseFactory,
-        tableRegistry: tableRegistry,
-      );
+  }) => StorageSdkWiring.build(
+    databaseFactory: databaseFactory,
+    tableRegistry: tableRegistry,
+  );
+
+  // ── 事务 ─────────────────────────────────────────────────────────────────
+
+  /// 在单个事务内执行 [action]。
+  ///
+  /// - 成功则自动 COMMIT
+  /// - 抛出异常则自动 ROLLBACK，异常会继续向上传递
+  ///
+  /// 示例：
+  /// ```dart
+  /// await _storage.transaction(() async {
+  ///   await _storage.insertOrReplace(companionA);
+  ///   await _storage.updateWhere(companionB, (t) => t.uid.equals(1));
+  /// });
+  /// ```
+  Future<T> transaction<T>(Future<T> Function() action);
 
   // ── 插入 ─────────────────────────────────────────────────────────────────
 
@@ -92,16 +107,16 @@ abstract class StorageSdkApi {
   /// );
   /// ```
   Future<void> updateWhere<D, T extends Table>(
-      Insertable<D> companion,
-      Expression<bool> Function(T) filter,
-      );
+    Insertable<D> companion,
+    Expression<bool> Function(T) filter,
+  );
 
   // ── 删除 ─────────────────────────────────────────────────────────────────
 
   /// 按条件删除。
   Future<void> deleteWhere<D, T extends Table>(
-      Expression<bool> Function(T) filter,
-      );
+    Expression<bool> Function(T) filter,
+  );
 
   /// 清空整张表。
   Future<void> deleteAll<D>();
@@ -118,13 +133,13 @@ abstract class StorageSdkApi {
 
   /// 按条件查询。
   Future<List<D>> selectWhere<D, T extends Table>(
-      Expression<bool> Function(T) filter,
-      );
+    Expression<bool> Function(T) filter,
+  );
 
   /// 查询第一条匹配记录。
   Future<D?> selectFirst<D, T extends Table>(
-      Expression<bool> Function(T) filter,
-      );
+    Expression<bool> Function(T) filter,
+  );
 
   // ── 监听 ─────────────────────────────────────────────────────────────────
 
@@ -133,13 +148,13 @@ abstract class StorageSdkApi {
 
   /// 按条件监听（实时流）。
   Stream<List<D>> watchWhere<D, T extends Table>(
-      Expression<bool> Function(T) filter,
-      );
+    Expression<bool> Function(T) filter,
+  );
 
   /// 监听第一条匹配记录（实时流）。
   Stream<D?> watchFirst<D, T extends Table>(
-      Expression<bool> Function(T) filter,
-      );
+    Expression<bool> Function(T) filter,
+  );
 
   // ── 原始 SQL ─────────────────────────────────────────────────────────────
 
@@ -152,7 +167,5 @@ abstract class StorageSdkApi {
   // ── 统计 ─────────────────────────────────────────────────────────────────
 
   /// 统计记录数。
-  Future<int> count<D, T extends Table>({
-    Expression<bool> Function(T)? filter,
-  });
-}
\ No newline at end of file
+  Future<int> count<D, T extends Table>({Expression<bool> Function(T)? filter});
+}
diff --git a/packages/storage_sdk/lib/src/presentation/wiring/storage_sdk_api_impl.dart b/packages/storage_sdk/lib/src/presentation/wiring/storage_sdk_api_impl.dart
index cdbf4cb..a5e8cba 100644
--- a/packages/storage_sdk/lib/src/presentation/wiring/storage_sdk_api_impl.dart
+++ b/packages/storage_sdk/lib/src/presentation/wiring/storage_sdk_api_impl.dart
@@ -11,8 +11,8 @@ class StorageSdkApiImpl implements StorageSdkApi, StorageSdkLifecycle {
   StorageSdkApiImpl({
     required StorageSdkCore core,
     required Map<Type, TableInfo> Function(GeneratedDatabase) tableRegistry,
-  })  : _core = core,
-        _tableRegistry = tableRegistry;
+  }) : _core = core,
+       _tableRegistry = tableRegistry;
 
   // ── 表查找 ───────────────────────────────────────────────────────────────
 
@@ -25,6 +25,13 @@ class StorageSdkApiImpl implements StorageSdkApi, StorageSdkLifecycle {
     return table as TableInfo<T, D>;
   }
 
+  /// 获取当前已开启的数据库实例，未开启则抛出 [StateError]。
+  GeneratedDatabase get _db {
+    final db = _core.dataSource.current;
+    if (db == null) throw StateError('数据库未开启，请先调用 openDatabase()');
+    return db;
+  }
+
   // ── 生命周期 ─────────────────────────────────────────────────────────────
 
   @override
@@ -36,6 +43,16 @@ class StorageSdkApiImpl implements StorageSdkApi, StorageSdkLifecycle {
   @override
   bool get isDatabaseOpen => _core.dataSource.current != null;
 
+  // ── 事务 ─────────────────────────────────────────────────────────────────
+
+  /// 在单个事务内执行 [action]。
+  ///
+  /// - 成功则自动 COMMIT
+  /// - 抛出异常则自动 ROLLBACK，异常会继续向上传递
+  @override
+  Future<T> transaction<T>(Future<T> Function() action) =>
+      _db.transaction(action);
+
   // ── 插入 ─────────────────────────────────────────────────────────────────
 
   @override
@@ -54,64 +71,57 @@ class StorageSdkApiImpl implements StorageSdkApi, StorageSdkLifecycle {
 
   @override
   Future<void> updateWhere<D, T extends Table>(
-      Insertable<D> companion,
-      Expression<bool> Function(T) filter,
-      ) =>
-      _core.repo.updateWhere(_tableFor<T, D>(), companion, filter);
+    Insertable<D> companion,
+    Expression<bool> Function(T) filter,
+  ) => _core.repo.updateWhere(_tableFor<T, D>(), companion, filter);
 
   // ── 删除 ─────────────────────────────────────────────────────────────────
 
   @override
   Future<void> deleteWhere<D, T extends Table>(
-      Expression<bool> Function(T) filter,
-      ) =>
-      _core.repo.deleteWhere(_tableFor<T, D>(), filter);
+    Expression<bool> Function(T) filter,
+  ) => _core.repo.deleteWhere(_tableFor<T, D>(), filter);
 
   @override
-  Future<void> deleteAll<D>() =>
-      _core.repo.deleteAll(_tableFor<Table, D>());
+  Future<void> deleteAll<D>() => _core.repo.deleteAll(_tableFor<Table, D>());
 
   // ── 查询 ─────────────────────────────────────────────────────────────────
 
   @override
-  Future<List<D>> selectAll<D>() =>
-      _core.repo.selectAll(_tableFor<Table, D>());
+  Future<List<D>> selectAll<D>() => _core.repo.selectAll(_tableFor<Table, D>());
 
   @override
   Future<List<D>> selectWhere<D, T extends Table>(
-      Expression<bool> Function(T) filter,
-      ) =>
-      _core.repo.selectWhere(_tableFor<T, D>(), filter);
+    Expression<bool> Function(T) filter,
+  ) => _core.repo.selectWhere(_tableFor<T, D>(), filter);
 
   @override
   Future<D?> selectFirst<D, T extends Table>(
-      Expression<bool> Function(T) filter,
-      ) =>
-      _core.repo.selectFirst(_tableFor<T, D>(), filter);
+    Expression<bool> Function(T) filter,
+  ) => _core.repo.selectFirst(_tableFor<T, D>(), filter);
 
   // ── 监听 ─────────────────────────────────────────────────────────────────
 
   @override
-  Stream<List<D>> watchAll<D>() =>
-      _core.repo.watchAll(_tableFor<Table, D>());
+  Stream<List<D>> watchAll<D>() => _core.repo.watchAll(_tableFor<Table, D>());
 
   @override
   Stream<List<D>> watchWhere<D, T extends Table>(
-      Expression<bool> Function(T) filter,
-      ) =>
-      _core.repo.watchWhere(_tableFor<T, D>(), filter);
+    Expression<bool> Function(T) filter,
+  ) => _core.repo.watchWhere(_tableFor<T, D>(), filter);
 
   @override
   Stream<D?> watchFirst<D, T extends Table>(
-      Expression<bool> Function(T) filter,
-      ) =>
-      _core.repo.watchFirst(_tableFor<T, D>(), filter);
+    Expression<bool> Function(T) filter,
+  ) => _core.repo.watchFirst(_tableFor<T, D>(), filter);
 
   // ── 原始 SQL ─────────────────────────────────────────────────────────────
 
   @override
-  Future<List<QueryRow>> rawQuery(String sql, [List<Object?> args = const []]) =>
-      _core.repo.rawQuery(sql, args);
+  Future<List<QueryRow>> rawQuery(
+    String sql, [
+    List<Object?> args = const [],
+  ]) => _core.repo.rawQuery(sql, args);
 
   @override
   Future<void> rawExecute(String sql, [List<Object?> args = const []]) =>
@@ -122,6 +132,5 @@ class StorageSdkApiImpl implements StorageSdkApi, StorageSdkLifecycle {
   @override
   Future<int> count<D, T extends Table>({
     Expression<bool> Function(T)? filter,
-  }) =>
-      _core.repo.count(_tableFor<T, D>(), filter: filter);
-}
\ No newline at end of file
+  }) => _core.repo.count(_tableFor<T, D>(), filter: filter);
+}