query method

@override Future<PostgreSQLResult> query(String fmtString, { Map<String, dynamic>? substitutionValues, bool? allowReuse, int? timeoutInSeconds, bool? useSimpleQueryProtocol, })

Executes a query on this context.

This method sends the query described by fmtString to the database and returns a Future whose value is the returned rows from the query after the query completes. The format string may contain parameters that are provided in substitutionValues. Parameters are prefixed with the '@' character. Keys to replace the parameters do not include the '@' character. For example:

    connection.query("SELECT * FROM table WHERE id = @idParam", {"idParam" : 2});

The type of the value is inferred by default, but should be made more specific by adding ':type" to the parameter pattern in the format string. For example:

    connection.query("SELECT * FROM table WHERE id = @idParam:int4", {"idParam" : 2});

Available types are listed in PostgreSQLFormatIdentifier.typeStringToCodeMap. Some types have multiple options. It is preferable to use the PostgreSQLFormat.id function to add parameters to a query string. This method inserts a parameter name and the appropriate ':type' string for a PostgreSQLDataType.

If successful, the returned Future completes with a List of rows. Each is row is represented by a List of column values for that row that were returned by the query.

By default, instances of this class will reuse queries. This allows significantly more efficient transport to and from the database. You do not have to do anything to opt in to this behavior, this connection will track the necessary information required to reuse queries without intervention. (The fmtString is the unique identifier to look up reuse information.) You can disable reuse by passing false for allowReuse.

useSimpleQueryProtocol indicates that the query will be executed using the Simple Query Protocol. This is similar to runing execute but instead of receiving the affectedRowCount only, this method will return PostgreSQLResult which contains affectedRowCount in addition to any data returned by the executed statement.

It's important to understand that when useSimpleQueryProtocol is true, all values will be of type String even if they have different type in the database. For instance, the value of an int4 column will be returned as a String instead of an int.

Setting useSimpleQueryProtocol to true is mainly useful for when the connection is established using the Streaming Replication Protocol. When the connection is in replication mode, the default Extended Query Protocol cannot be used as the database will throw an error and drop the connection. In other words, only the Simple Query Protocol can be used with Streaming Replication Protocol.

Implementation

@override
Future<PostgreSQLResult> query(
  String fmtString, {
  Map<String, dynamic>? substitutionValues,
  bool? allowReuse,
  int? timeoutInSeconds,
  bool? useSimpleQueryProtocol,
}) =>
    _query(
      fmtString,
      substitutionValues: substitutionValues,
      allowReuse: allowReuse ?? true,
      useSimpleQueryProtocol: useSimpleQueryProtocol ?? false,
      timeoutInSeconds: timeoutInSeconds,
    );