postgres 3.5.14

PostgreSQL database driver. Supports binary protocol, connection pooling and statement reuse.

Changelog

3.5.14

• Fix an opaque Bad state: StreamSink is closed crash when the socket closes in the narrow window between connecting and sending the first message (e.g. StartupMessage, a bound statement, or a simple query); this now surfaces as a catchable PgException.
• Fix connect() leaking the socket and its listener when startup (or onOpen) fails instead of closing the partially-opened connection.
• Fix connect() failures (e.g. wrong password, SSL/auth errors) reporting a stack trace made up of internal frames only; the caller's stack is now attached so the trace points back to the code that called connect()/Connection.open().
• Fix the same internal-frames-only stack trace issue for a failed LISTEN (Channels[channel]): the trace now points back to the code that subscribed to the channel.
• Fix a background UNLISTEN (sent when the last listener on a channel cancels) throwing when it raced a concurrent close(); this is now treated as a no-op instead of failing whatever cancelled the subscription.
• Fix a one-shot query being split across two transactions: parsing had its own Sync-terminated exchange, so a transaction-mode pooler could hand the connection to another client between the parse and the bind (26000/42P05). Parse, bind and execute now travel in one exchange under the unnamed statement.
• A failed one-shot query no longer sends a redundant Close for the unnamed statement it never named; failure and success now cost the same single exchange.
• Fix port connection-string query parameter being ignored whenever a host was already present in the URI (e.g. postgresql://host/db?port=9876).
• Fix pooled connections being reused across requests with different typeRegistry or securityContext settings.
• Fix Channels.notify() permanently failing after one transient error; a failed attempt to prepare the notify statement is no longer cached.
• Fix a malformed numeric field in a server error message, or a malformed SCRAM iteration count, crashing the connection instead of surfacing as a PgException.
• Remove an unconditional print() warning for the deprecated read type-substitution alias.
• Reduce date/timestamp binary encode and decode overhead by reusing the cached Y2K epoch instead of constructing a new DateTime on every call.
• Fix logical replication tuple values arriving undecoded (raw bytes) with typeOid always null; the live decode path now resolves types and decodes binary columns.
• Fix binary range decoding inferring a bound's byte length from the rest of the buffer instead of validating the explicit length prefix Postgres sends.
• TypeRegistry.decode() now returns FutureOr<Object?> instead of Future<Object?>, avoiding a Future allocation per column for the common synchronous codec case; this removes real overhead from the row-decoding hot path.
• Fix connectTimeout/queryTimeout: Duration.zero (or negative) meaning "wait forever" instead of failing fast; such values are now rejected at settings construction, matching the connection-string parser's existing validation.
• Connecting without a password now fails immediately with a clear PgException instead of silently authenticating with an empty one; also fixes a pending-operation error (e.g. this one) escaping as an unhandled exception instead of a catchable connection failure.

3.5.13

• Fix socket/listener leaks in cancelAll() and cancelPendingStatement(), and add a hard timeout fallback so a stuck query can't hang forever even if cancellation fails.
• Fix Pool.prepare() hanging when a connection can't be acquired, Pool.close() returning before in-use connections finish closing, and pooled connects ignoring time already spent waiting for a slot.
• Fix pooled connections not inheriting securityContext from pool-level settings.
• Fix connection-string parsing of bracketed IPv6 hosts, and accept the standard libpq sslmode=prefer/allow and replication=on/off/yes/no/1/0 values.
• Fix TypedValue(Type.unspecified, ...) silently discarding a parameter type known from a :type annotation or prepared statement.
• Fix Sql.indexed mis-tokenizing the @>, <@, @?, @@ operators as auto-incrementing variables.
• Fix Severity parsing to prefer PostgreSQL's non-localized error-severity field.
• Fix logical replication tuple decoding: unknown column type bytes no longer crash the stream, and binary-format columns are no longer mis-decoded as text.
• Fix off-by-one in DatabaseInfo column lookup causing a RangeError instead of returning null.
• Fix LSN.operator- performing addition instead of subtraction.
• Fix Range.flag misclassifying a valid single-point inclusive range (e.g. [x,x]) as empty.
• Fix numeric Infinity/-Infinity values silently decoding as 0.

3.5.12

• Fix runTx silently rolling back after ROLLBACK TO SAVEPOINT recovery: clear stale _transactionException when PostgreSQL confirms a healthy transaction state.
• Fix connection permanently blocked when BEGIN fails inside runTx (stale _activeTransaction state).
• Fix connection left in undefined PostgreSQL state when ROLLBACK fails after a transaction error.
• Fix untyped Uint8List parameters being encoded as an integer array literal: they are now encoded as a bytea hex literal.

3.5.11

• Adding JsonbListView with isSqlNull(int index) method to check if a JSONB array has SQL or JSON null value.
• Fix double-timezone encoding bug.
• Fix statement scope bug.

3.5.10

• Supporting BYTEA[] built-in type.
• Fix TypedValue parameter propagation.

3.5.9

• Supporting multiple hosts in connection strings via comma-separated hosts or multiple host query parameters.
• Unix socket connections via host query parameter (automatically detected when path contains /).
• Supporting user/username, password, database, and port as query parameters in connection strings (override URL components).

3.5.8

• Upgraded SDK constraints and lints.
• New SASL authenticator (reduce dependencies that haven't been updated for a while).
• Supporting more URL-based connection-string parameters (mostly for pool).
• Optimized StackTrace capture #432 by gmpassos.

3.5.7.

• Supporting URL-based connection-string specification in Connection.openFromUrl and Pool.withUrl. (Note: feature and supported settings is considered experimental.)

3.5.6

• Accept null values as part of the binary List encodings.

3.5.5

• Better exception message when SSL is not supported.
• Fix: typo in type specification (read -> real, also keeping read for compatibility).

3.5.4

Warning: This version fixes the inconsistency of 3.5.3 by:

• UniqueViolationException and ForeignKeyViolationException extends ServerException instead of PgException, and
• they no longer have public constructor (please open an issue if this is something you'd rely on).
• The exception from cancelling the statement is also extends ServerException instead of PgException.

3.5.3

• New typed exceptions: UniqueViolationException, ForeignKeyViolationException. #416 by hurrba
• Fix: don't reuse pool connections that are closed/closing. #417 by davidmartos96

3.5.2

• Fix: Pool connection timeout does not rely on package:pool's timeout, instead uses a separate Timer.

3.5.1

• Fix: ARRAY_AGG (and other arrays) may return [null].

3.5.0

• Better exception stacktraces (in some cases) using package:stack_trace.
• With that dependency, upgraded minimum SDK to 3.4.

3.4.8

• Fix: Don't ignore de pool resource close call when using foce. #406 by davidmartos96.

3.4.7

• Implemented Pool.close(force: true) (using davidmartos96's #397 as baseline).

3.4.6

• Fix: do not close connection after an empty statement.
• Fix: close(force: true) does not cause uncaught exception.

3.4.5

• close(force: true) to indicate intent to force-close pending queries and resources. #396 by davidmartos96
• Fix: multiple message processing overlap bug when SSL mode was disabled.

3.4.4

• Fix: explicit closing of prepared statement portals in transactions to release table locks. #393

3.4.3

• Fix: prevent hanging state by forwarding protocol-level parsing errors into the message stream.

3.4.2

• Fix: When a transaction is rolled back, do not expose the exception on rollback, rather the original exception from the transaction.

3.4.1

• Do not allow exceptions escape when closing broken connection. #384 by pulyaevskiy.

3.4.0

• Connection.info (through ConnectionInfo class) exposes read-only connection-level information, e.g. acessing access server-provided parameter status values.
• Support for binary pgoutput replication by wolframm.
• Allowing custom type codecs:
  • Codec interface is used for encoding/decoding value by type OIDs or Dart values.
  • Codec.encode and Codec.decode gets a reference to CodecContext which provides access to encoding, observed runtime parameters and the TypeRegistry.
  • EncoderFn value converter for generic Dart object -> Postgres-encoded bytes (for values where type is not specified).
  • DatabaseInfo tracks information about relations and oids (currently limited to RelationMessage caching).
• Timeout-related behaviour changes, may be breaking in some cases:
  • Preparing/executing a stamement on the main connection while in a runTx callback will throw an exception.
  • Setting timeout will try to actively cancel the current statement using a new connection.
  • ServerException may be transformed into _PgQueryCancelledException which is both PgException and TimeoutException (but no longer ServerException).
• API deprecations:
  • Deprecated TupleDataColumn.data, use .value instead (for binary protocol messages).
  • Deprecated some logical replication message parsing method.
  • Removed @internal-annotated methods from the public API of ServerException and Severity.

3.3.0

Removed legacy v2 APIs. These APIs were meant to be removed in 3.1.0, but were kept for a bit longer, as they didn't have any drawback to be around. However, a planned redesign of the type customization would require to touch the v2 codebase and it is not worth the effort to keep it much longer.

3.2.1

• Added or fixed decoders support for QueryMode.simple: double, real, timestampWithTimezone, timestampWithoutTimezone, date, numeric, json, jsonb #338 by pst9354.

3.2.0

• Support for tsvector and tsquery types.
• ResultRow.isSqlNull(int) returns true if the column's value was SQL NULL.
• TypedValue.isSqlNull indicates SQL NULL (vs. JSON null).

3.1.2

• ConnectionSettings.onOpen callback to initialize a new connection and set connection-level variables.

3.1.1

• Use ':' (colon) for substitution and cast operator together #309 by xvrh.

3.1.0

Added the following PostgreSQL builtin types:

• Geometric types line, lseg, path, polygon, box, circle
• Range types int4range, int8range, daterange, tsrange, tstzrange
• Time type time
• Array types _int2, _date, _time, _timestamp, _timestamptz, _uuid

Huge thanks for #294 by wolframm.

3.0.8

• Properly react to connection losses by reporting the database connection as closed.

3.0.7

• Allow cleartext passwords when secure connection is used. (#283 by simolus3)

3.0.6

• Allow passing a SecurityContext when opening postgres connections.

3.0.5

• Support for type char/character/bpchar.

3.0.4

• Fix: SSL connection problem handler.

3.0.3

• Using const for ConnectionSettings, SessionSettings and PoolSettings classes. (#267 by Gerrel)
• Parsing of Sql.indexed and Sql.named happens when the Connection starts to interpret it. Errors with unknown type names are thrown in this later step.

3.0.2

• Fix: Dispose disconnected pool Connections. (#260 by nehzata).
• Deprecated ParseMessage constructor's types argument, use typeOids instead. (As most users don't access this directly, it will be removed in 3.1.0).

3.0.1

• Fix: do not allow execute after closing the Connection.
• Session.runTx() supports rolling back the transaction through TxSession.rollback() (otherwise any exception has the same effect, but callers need to catch it).
• Supporting more type aliases, including serial4, serial8, integer...
• Deprecated all of v2 API, legacy fallback will be removed in next minor version (3.1.0).

3.0.0

New features:

• New API (better names and consistency).
• New SQL parsing and configurable query substitutions.
• Integrated connection pooling.
• A somewhat-compatible legacy API support to help migrations (will be removed in 3.1.0).

BREAKING CHANGES

The package had a partial rewrite affecting public client API and internal behaviour, keeping most of the wire protocol handling from the old version.

Users of this package must rewrite and test their application when upgrading.

Notable breaking behaviour changes:

• Simple query protocol allows sending queries to the server without awaiting on the result. The new implementation queues these request on the client instead.
• Table name OIDs are not fetched or cached, this information from the result schema is absent, also causing mappedResultsQuery to be removed from the new API.
• Queries are not cached implicitly, explicit prepared statements can be used instead.
• interval values are returned as Interval type instead of Duration.
• A newly added UndecodedBytes instances are returned when the package does not know or has not implemented the appropriate type decoding yet. Previously these values were auto-encoded to String and if that failed the Uint8List were used.
• Types, fields and parameter names may have been renamed to be more consistent or more aligned with the Dart naming guides.

Legacy compatibility layer

package:postgres/legacy.dart provides a somewhat backwards-compatible API via the PostgreSQLConnection.withV3() constructor. Many features, including the ones mentioned above are missing and/or throw UnimplementedError when called.

Migration

• You may use the legacy compatibility layer to check if your code relies on any of the above mentioned feature, rewrite if needed.
• Start using the new API, incrementally, when possible.
• For most queries, you may use Sql.named('SELECT ...') to keep the default name- and Map-based query @variable`` substitution, or you may use the raw $1` version (with 1-based indexes).
• Always write tests.

If you have any issues with migration or with the new behavior, please open an issue on the package's GitHub issue tracker or discussions.

Thanks

The rewrite happened because of many contributions (including code, comments or criticism) on the new direction and design. I'd like to call out especially to simolus3 and osaxma, who helped to push forward.

3.0.0-beta.2

see the latest 3.0.0 (pre)release

3.0.0-beta.1

see the latest 3.0.0 (pre)release

3.0.0-alpha.1

see the latest 3.0.0 (pre)release

2.6.3

• Allow encoding to be specified for connections. The setting will be used for all connection-related string conversions.
• Allow generic List type as substitution values in binary encoding (as long as the inner type matches).
• Refactor: replaced UTF8BackedString with generic encoding (not complete).
• Breaking change in package:postgres/messages.dart: default constructors made internal, parsing is done with more efficient reader.

2.6.2

• Improved (experimental) v3 implementation. #98 and #102 by simolus3.

2.6.1

• Added support for bigInt (int8) arrays. #41 by schultek.

2.6.0

• Updated to package:lints.
• Adding lowerCase values to AuthenticationScheme.
• Add new package:postgres/postgres_v3_experimental.dart library as a preview. It exposes the postgres client under a new API that will replace the current one in version 3.0.0 of this package. At the moment, the new library is experimental and not fully implemented. Until the actual 3.0.0 release, the new APIs might change without a breaking version.

2.5.2

• Connecting without a password for non-trusted users throws an exception instead of timing out #68 by osaxma.

2.5.1

• Use substitutionValues with useSimpleQueryProtocol #62 by osaxma

2.5.0

• Added Support for Streaming Replication Protocol which included the following changes:
  • Replication Mode Messages Handling. #58 by osaxma
  • Add new message types for replication. #57 by osaxma
  • Add connection configuration for Streaming Replication Protocol. #56 by osaxma
  • Raise the min sdk version to support enhanced enums. #55 by osaxma
  • Add LSN type and time conversion to and from ms-since-Y2K. #53 by osaxma
  • Fix affected rows parsing in CommandCompleteMessage. #52 by osaxma
  • Introduced new APIs to PostgreSQLConnection: addMessage to send client messages, messages stream to listen to server messages & useSimpleQueryProtocol option in query method. #51 by osaxma

2.4.6

• Fix crash when manually issuing a transaction statement like BEGIN without using the high-level transaction APIs. #47 by simolus3.

2.4.5

• Added support for boolean arrays. #41 by slightfoot.

2.4.4

• Added support for varchar arrays. #39 by paschalisp.

2.4.3

• Support for clear text passwords using a boolean parameter in connection as 'allowClearTextPassword' to activate / deactivate the feature. #20.

2.4.2

• Include original stacktrace when query fails. (#15 by davidmartos96)

2.4.1+2

• Fix error when sending json data with execute() #11

2.4.1+1

• Fix error when passing allowReuse: null into query() #8

2.4.1

• Support for type interval, #10.

2.4.0

• Support for type numeric / decimal (#7, #9).
• Support SASL / SCRAM-SHA-256 Authentication, #6.

2.3.2

• Expose ColumnDescription.typeId.

2.3.1

• Added support for types varchar, point, integerArray, doubleArray, textArray and jsonArray. (Thanks to schultek, #3)

2.3.0

• Finalized null-safe release.

2.3.0-null-safety.2

• Fixing query API optional parameters.

2.3.0-null-safety.1

• Updated public API to always return non-nullable results.
• BREAKING CHANGE: unknown mapped table name is no longer null, it is empty string ('').

2.3.0-null-safety.0

• Migrate to null safety. (Thanks to j4qfrost, #153).
• Documentation fix (by saward).

2.2.0

• Supporting Unix socket connections. (Thanks to grillbiff, #124)
• Preparation for custom type converters.
• Added rowsAffected to PostgreSQLResult. (Thanks to arturaz, #143)

2.1.1

• Fix RuneIterator.current use, which no longer returns null in 2.8 SDK.

2.1.0

• Missing substitution value no longer throws FormatException. More details in the GitHub issue.

2.0.0

• Fixed startup packet length when username is null (#111).
• Finalized dev release.

2.0.0-dev1.0

• Restricted field access on [PostgreSQLConnection].
• Connection-level default query timeout.
• Option to specify timeout for the transaction's "COMMIT" query.
• Optimized byte buffer parsing and construction with package:buffer.
• Hardened codebase with package:pedantic and additional lints.
• Updated codebase to Dart 2.2.
• PostgreSQLResult and PostgreSQLResultRow as the return value of a query.
  • Returned lists are protected with UnmodifiableListView.
  • Exposing column metadata through ColumnDescription.
  • row-level toTableColumnMap and toColumnMap
• PostgreSQLConnection and _TransactionProxy share the OID cache.
• default value for query(allowReuse = true) is set only in the implementation method.

Breaking behaviour

• Table OIDs are always resolved to table names (and not only with mapped queries).

1.0.2

• Add connection queue size

1.0.1

• Prevent the table name resolution of OIDs <= 0.

1.0.0

• Adds support for Dart 2

0.9.9

• Add full support for UUID columns.

0.9.8

• Preserve error stacktrace on various query or transaction errors.
• Read support for BYTEA columns.

0.9.7

• Adds Connection.mappedResultsQuery to return query results as a Map with keys for table and column names.

0.9.6

• Adds Connection.notifications to listen for NOTIFY events (thanks @andrewst)
• Adds better error reporting.
• Adds support for JSONB columns.
• Fixes issue when encoding UTF16 characters (thanks @andrewst)

0.9.5

• Allow connect via SSL.

0.9.4

• Fixed issue with buffer length

0.9.3

• Fixed issue with UTF8 encoding

0.9.2

• Bump for documentation

0.9.1

• Added transactions: PostgreSQLConnection.transaction and PostgreSQLConnection.cancelTransaction.

0.9.0

• Initial version