v1.9.4-beta.1 - Statements cache

CHANGELOG.md

@@ -1,3 +1,17 @@
+## 1.9.4-beta.1
+
+- `DBSQLAdapterCapability`: added `statementsCache`.
+
+- `ConditionSQLEncoder`:
+  - Added property `forCachedStatements`: forces generation of SQL statements suitable for caching.
+  - Fix resolution of parameter values present only in `EncodingContext.encodingParameters`
+    (i.e., generated by the encoder, not passed as normal parameters).
+
+- New mixin `StatementCache`
+  - New `CachedStatement`.
+
+- `PostgreSQLConnectionWrapper` now has support for statements cache (with `StatementCache`).
+
 ## 1.9.3
 
 - `DBPostgreSQLAdapter`:

lib/src/bones_api_base.dart

@@ -42,7 +42,7 @@ typedef APILogger = void Function(APIRoot apiRoot, String type, String? message,
 /// Bones API Library class.
 class BonesAPI {
   // ignore: constant_identifier_names
-  static const String VERSION = '1.9.3';
+  static const String VERSION = '1.9.4-beta.1';
 
   static bool _boot = false;
 

lib/src/bones_api_condition_encoder.dart

@@ -1158,6 +1158,10 @@
     if (valueAsList) {
       return _resolveParameterValueImpl(value, context, valueType, true)
           .resolveMapped((values) {
+        if (values is EncodingValue<String, Object?>) {
+          return values.asEncodingValueList();
+        }
+
         var list = values is List
             ? values
             : (values is Iterable ? values.toList(growable: false) : [values]);
@@ -1179,6 +1183,10 @@
       if (!context.parametersPlaceholders.containsKey(valueKey)) {
         return _resolveParameterValueImpl(value, context, valueType, false)
             .resolveMapped((val) {
+          if (val is EncodingValue<String, Object?>) {
+            return val;
+          }
+
           context.parametersPlaceholders[valueKey] ??= val;
           return EncodingPlaceholder(
               valueKey, valueType, placeholder, encodeEncodingPlaceholder);
@@ -1198,6 +1206,10 @@
         namedParameters: context.namedParameters,
         encodingParameters: context.encodingParameters);
 
+    if (paramValue is EncodingValue) {
+      return paramValue;
+    }
+
     if (valueType != null) {
       return resolveValueToType(paramValue, valueType,
           valueAsList: valueAsList);
@@ -1273,7 +1285,7 @@
           value == list.first;
         } else {
           throw ArgumentError(
-              "Can't resolve a `List` with mutiple values to a primitive type: $valueTypeInfo >> $value");
+              "Can't resolve a `List` with multiple values to a primitive type: $valueTypeInfo >> $value");
         }
       }
 
@@ -1354,6 +1366,18 @@
 
   @override
   String toString() => encode.toString();
+
+  EncodingValueList<E> asEncodingValueList() {
+    var values = this;
+    if (values is EncodingValueList<E>) {
+      return values as EncodingValueList<E>;
+    } else {
+      return EncodingValueList(values.key, values.type, [values], (p) {
+        var v = values.encode;
+        return '( $v )' as E;
+      });
+    }
+  }
 }
 
 abstract class EncodingValueResolved<E, T extends EncodingValueResolved<E, T>>

lib/src/bones_api_condition_sql.dart

@@ -9,10 +9,15 @@
 
 /// A [Condition] encoder for SQL.
 class ConditionSQLEncoder extends ConditionEncoder {
+  /// The character used to quote identifiers in the SQL dialect.
   final String sqlElementQuote;
 
+  /// If `true`, forces generation of SQL statements suitable for caching by
+  /// avoiding inline values and using substitution values whenever possible.
+  final bool forCachedStatements;
+
   ConditionSQLEncoder(SchemeProvider super.schemeProvider,
-      {required this.sqlElementQuote});
+      {required this.sqlElementQuote, this.forCachedStatements = false});
 
   @override
   String get groupOpener => '(';
@@ -37,12 +42,26 @@
 
     var schemeProvider = this.schemeProvider;
     if (schemeProvider == null) {
-      var idKey = context.addEncodingParameter('id', c.idValue);
+      var idValue = c.idValue;
+
+      var encodingValue = valueToParameterValue(context, idValue,
+          fieldKey: 'id', fieldType: int);
+
+      var idKey = context.addEncodingParameter('id', encodingValue);
+
+      if (forCachedStatements) {
+        var c2 = KeyConditionEQ(
+          [ConditionKeyField('id')],
+          ConditionParameter.key(idKey),
+        );
+        return encodeKeyConditionEQ(c2, context);
+      }
+
       var q = sqlElementQuote;
       var tableKey = '$q$tableAlias$q.$q$idKey$q';
 
       return encodeConditionValuesWithOperator(
-          context, int, idKey, tableKey, '=', c.idValue, false);
+          context, int, idKey, tableKey, '=', encodingValue, false);
     } else {
       var tableSchemeRet = schemeProvider.getTableScheme(tableName);
 
@@ -56,13 +75,26 @@
 
         var idFieldName = tableScheme.idFieldName ?? 'id';
         var idType = tableScheme.fieldsTypes[idFieldName] ?? int;
+        var idValue = c.idValue;
+
+        var encodingValue = valueToParameterValue(context, idValue,
+            fieldKey: idFieldName, fieldType: idType);
+
+        var idKey = context.addEncodingParameter(idFieldName, encodingValue);
+
+        if (forCachedStatements) {
+          var c2 = KeyConditionEQ(
+            [ConditionKeyField(idFieldName)],
+            ConditionParameter.key(idKey),
+          );
+          return encodeKeyConditionEQ(c2, context);
+        }
 
-        var idKey = context.addEncodingParameter(idFieldName, c.idValue);
         var q = sqlElementQuote;
         var tableKey = '$q$tableAlias$q.$q$idKey$q';
 
         return encodeConditionValuesWithOperator(
-            context, idType, idKey, tableKey, '=', c.idValue, false);
+            context, idType, idKey, tableKey, '=', encodingValue, false);
       });
     }
   }
@@ -75,12 +107,26 @@
 
     var schemeProvider = this.schemeProvider;
     if (schemeProvider == null) {
-      var idKey = context.addEncodingParameter('id', c.idsValues);
+      var idsValues = c.idsValues;
+
+      var encodingValue = valueToParameterValue(context, idsValues,
+          fieldKey: 'id', fieldType: int, valueAsList: true);
+
+      var idKey = context.addEncodingParameter('id', encodingValue);
+
+      if (forCachedStatements) {
+        var c2 = KeyConditionIN(
+          [ConditionKeyField('id')],
+          ConditionParameter.key(idKey),
+        );
+        return encodeKeyConditionIN(c2, context);
+      }
+
       var q = sqlElementQuote;
       var tableKey = '$q$tableAlias$q.$q$idKey$q';
 
       return encodeConditionValuesWithOperator(
-          context, int, idKey, tableKey, 'IN', c.idsValues, true);
+          context, int, idKey, tableKey, 'IN', encodingValue, true);
     } else {
       var tableSchemeRet = schemeProvider.getTableScheme(tableName);
 
@@ -94,13 +140,26 @@
 
         var idFieldName = tableScheme.idFieldName ?? 'id';
         var idType = tableScheme.fieldsTypes[idFieldName] ?? int;
+        var idsValues = c.idsValues;
+
+        var encodingValue = valueToParameterValue(context, idsValues,
+            fieldKey: idFieldName, fieldType: idType, valueAsList: true);
+
+        var idKey = context.addEncodingParameter(idFieldName, encodingValue);
+
+        if (forCachedStatements) {
+          var c2 = KeyConditionIN(
+            [ConditionKeyField(idFieldName)],
+            ConditionParameter.key(idKey),
+          );
+          return encodeKeyConditionIN(c2, context);
+        }
 
-        var idKey = context.addEncodingParameter(idFieldName, c.idsValues);
         var q = sqlElementQuote;
         var tableKey = '$q$tableAlias$q.$q$idKey$q';
 
         return encodeConditionValuesWithOperator(
-            context, idType, idFieldName, tableKey, 'IN', c.idsValues, true);
+            context, idType, idFieldName, tableKey, 'IN', encodingValue, true);
       });
     }
   }
@@ -509,14 +568,18 @@
       }
     }
 
-    if (value is ConditionParameter) {
+    if (value is EncodingValue<String, Object?>) {
+      return value;
+    } else if (value is ConditionParameter) {
       return conditionParameterToParameterValue(
           value, context, fieldKey, fieldType,
           valueAsList: valueAsList);
     } else if (value is List &&
         value.whereType<ConditionParameter>().isNotEmpty) {
       var parametersValues = value.map((v) {
-        if (v is ConditionParameter) {
+        if (value is EncodingValue<String, Object?>) {
+          return value;
+        } else if (v is ConditionParameter) {
           return conditionParameterToParameterValue(
               value, context, fieldKey, fieldType,
               valueAsList: valueAsList);

lib/src/bones_api_entity_db_memory.dart

@@ -108,6 +108,7 @@ class DBSQLMemoryAdapter extends DBSQLAdapter<DBSQLMemoryAdapterContext>
               transactions: true,
               transactionAbort: true,
               tableSQL: false,
+              statementsCache: false,
               constraintSupport: false,
               multiIsolateSupport: false,
               connectivity: DBAdapterCapabilityConnectivity.none),

lib/src/bones_api_entity_db_mysql.dart

@@ -104,6 +104,7 @@ class DBMySQLAdapter extends DBSQLAdapter<DBMySqlConnectionWrapper>
               transactions: true,
               transactionAbort: true,
               tableSQL: true,
+              statementsCache: false,
               constraintSupport: false,
               multiIsolateSupport: true,
               connectivity: DBAdapterCapabilityConnectivity.secureAndUnsecure),

lib/src/bones_api_entity_db_postgres.dart

@@ -111,6 +111,7 @@
               transactions: true,
               transactionAbort: true,
               tableSQL: true,
+              statementsCache: true,
               constraintSupport: true,
               multiIsolateSupport: true,
               connectivity: DBAdapterCapabilityConnectivity.secureAndUnsecure),
@@ -1093,13 +1094,13 @@
 
         return doInsertSQL(
                 entityName, table, insertSQL, transaction, connection)
-            .resolveMapped((res) => _fixeTableSequence(transaction, entityName,
+            .resolveMapped((res) => _fixTableSequence(transaction, entityName,
                 table, idFieldName, idFieldType, connection, res));
       });
     });
   }
 
-  FutureOr<dynamic> _fixeTableSequence(
+  FutureOr<dynamic> _fixTableSequence(
       Transaction transaction,
       String entityName,
       String table,
@@ -1215,7 +1216,8 @@
 }
 
 /// A [DBPostgreSQLAdapter] connection wrapper.
-class PostgreSQLConnectionWrapper extends DBConnectionWrapper<Session> {
+class PostgreSQLConnectionWrapper extends DBConnectionWrapper<Session>
+    with StatementCache<Statement> {
   final String? username;
   final String host;
   final int port;
@@ -1230,14 +1232,17 @@
     return "postgresql://$username@$host:$port/$database${secure ? '?sslmode=require' : ''}";
   }
 
+  Future<Result> _executeWithCachedStatement(
+      String sql, Map<String, dynamic>? substitutionValues) async {
+    var statement = await prepareSQLCached(sql);
+    return statement.run(substitutionValues);
+  }
+
   Future<List<Map<String, dynamic>>> mappedResultsQuery(String sql,
       {Map<String, dynamic>? substitutionValues}) async {
     updateLastAccessTime();
 
-    var rs = await nativeConnection.execute(
-      Sql.named(sql),
-      parameters: substitutionValues,
-    );
+    var rs = await _executeWithCachedStatement(sql, substitutionValues);
 
     var mappedResult = rs.map((e) => e.toResultsMap()).toList();
 
@@ -1247,20 +1252,21 @@
   Future<Result> query(String sql,
       {Map<String, dynamic>? substitutionValues}) async {
     updateLastAccessTime();
-    return nativeConnection.execute(
-      Sql.named(sql),
-      parameters: substitutionValues,
-    );
+
+    return _executeWithCachedStatement(sql, substitutionValues);
   }
 
   Future<int> execute(String sql,
       {Map<String, dynamic>? substitutionValues}) async {
     updateLastAccessTime();
+
+    // Can't use `prepareSQLCached` for `ignoreRows: true`.
     var rs = await nativeConnection.execute(
       Sql.named(sql),
       parameters: substitutionValues,
       ignoreRows: true,
     );
+
     return rs.affectedRows;
   }
 
@@ -1280,6 +1286,18 @@
     );
   }
 
+  @override
+  Future<CachedStatement<Statement>> prepareSQLCachedImpl(String sql) async {
+    var sqlNamed = Sql.named(sql);
+    var statement = await nativeConnection.prepare(sqlNamed);
+    return CachedStatement(statement);
+  }
+
+  @override
+  void disposeCachedStatement(Statement statement) {
+    statement.dispose();
+  }
+
   @override
   bool isClosedImpl() {
     final nativeConnection = this.nativeConnection;