slingshot_postgres 0.1.13
slingshot_postgres: ^0.1.13 copied to clipboard
PostgreSQL driver for Dart backends over libpq and dart:ffi: a native thread-per-connection pool, async I/O that never blocks an isolate, zero-copy result reads.
Changelog #
Format: Keep a Changelog. The package follows semver; the native library
(libnative_db) carries its own ABI version, MAJOR.MINOR, checked at load time: a different MAJOR is fatal, an
older MINOR than the Dart side expects is a warning.
0.1.13 #
Added #
PoolConfig.statementCacheSize: a per-connection cache of server-side prepared statements, off by default (0). When on, a statement that takes the Extended protocol (withparams, orbinaryResult) is prepared under a name on the first use of its SQL on a connection, and later uses on that connection run the prepared statement, so the server skips parsing and planning. Keyed by the SQL text plus the parameter types; the least recently used statements beyond the capacity are evicted and closed on the server. RequirespreservePreparedStatements(orsessionResetQuery: null);startthrows otherwise.- A cached statement that went stale (SQLSTATE 26000 after
DEALLOCATE ALL, or 0A000cached plan must not change result typeafter a schema change) is prepared again and the query re-run once, when the connection is outside a transaction. Inside a transaction the server has already aborted it: theQueryFailedExceptionis thrown and the next use prepares afresh. On the cached path, error messages end with[SQLSTATE xxxxx]. - Native ABI MINOR 7:
pool_submit_query_cached,pool_set_statement_cache_capacityandget_error_sqlstate. The new Dart side loads an older library with the usual warning; the cache then refuses to start.
Fixed #
- A query that hit its timeout on the simple, parameterised, multi-read or pipeline path left the connection
unusable: libpq kept the cancelled statement in progress, every later statement on that connection failed with
QueryTimeoutException, and the pool kept handing it out. The worker now cancels and drains the statement to its end before reporting the timeout, so the connection and its session stay usable. - When a statement cannot be ended cleanly (the deadline hit before it was fully sent, the server did not end it
within 5 s of the cancel, or a read failed with the link still up), the session is now given up: the connection
is reconnected and the statement is reported as
ConnectionLostException, on every path. Before, some of these cases reported a plain failure, and a following statement of the same transaction could run on the fresh session outside the transaction. A statement not fully sent is never completed afterwards, so it does not run after the caller was told it failed. The cancel itself is a blockingPQcancel; with the server unreachable it can take longer than the 5 s window.
0.1.12 #
Added #
-
One-dimensional array parameters, sent in binary with nulls allowed:
Param.boolArray,Param.int2Array,Param.int4Array,Param.int8Array,Param.float8Array,Param.textArrayandParam.uuidArray, forWHERE id = ANY($1)without building a string. Elements are validated by the scalar encoders (a malformed uuid or an out-of-rangeint2/int4throwsArgumentError).Param.untypedArrayOfNulls(n)sends an array ofnNULLs with no element type, typed by the server from context.PostgresOidgains the seven array OIDs. -
PoolConfig.preservePreparedStatements: a session reset that keeps statements prepared on the connection across borrows. It leaves outDEALLOCATE ALLandDISCARD PLANSand clears the rest of the session state, on release and withdeferSessionReset. Statements prepared with SQLPREPAREsurvive too. Requires the defaultsessionResetQuery;startthrows otherwise.
Fixed #
- With
sessionResetQuery: null, a connection returned inside a transaction (open or failed) went back to the pool with the transaction still open, and the next borrower inherited it and its locks. It is now rolled back on release, decided from the client-side transaction status, so a release outside a transaction still sends nothing.
0.1.11 #
Fixed #
- When the server ends the session during a simple-protocol statement (for example
pg_terminate_backend), the statement raisesConnectionLostExceptionand the slot is reconnected at once. Before, it raisedQueryFailedExceptionwith the server's FATAL message, the slot stayed marked healthy over a dead link, and the loss only surfaced on the next statement. When an earlier statement of the same string completed before the link died, nothing changes: the FATAL still raisesQueryFailedException, and the loss is reported on the next statement, so work the server did is not reported as lost. - After a
ConnectionLostException, the executor refuses every laterexecute,executeMultiReadandexecutePipelineby rethrowing that same exception, which names the statement that was lost. The native worker reconnects the slot while the connection is still leased, so before this a statement issued after the loss ran on the fresh session in autocommit: a write made inside a unit of work was committed at once, while the followingcommit()reported that nothing had been committed. A new lease gets a new executor and is not affected.
No API or ABI version change (still MAJOR 2 / MINOR 6). The native library in lib/_native/ is rebuilt for all
four platforms, since the first fix lives in the native worker.
0.1.10 #
Fixed #
PostgresRepositoryreleases the result set of every operation (findAll,findById,insert,update,delete) before returning, also when the row mapper throws. Before, eachPGresultstayed allocated until the finalizer ran, which the GC schedules without seeing native memory. The row mapper must decode the values it needs: aPostgresResultRowkept for later now throwsStateErrorwhen read.- A
QueryPhaseSinkorPoolDiagnosticsSinkthat throws no longer replaces the outcome it observes. Before, a throwing query sink discarded the ready result set and handed its own exception to the caller, and a throwing transaction sink hid theBEGINor body error, or made a committedwithTransactionInstrumentedlook failed. The sink's exception now goes to the current zone (Zone.handleUncaughtError); the caller gets the result or the original error. No API or ABI version change.
0.1.9 #
Fixed #
- The native library exports only its public ABI (the functions of
native_db.handnative_pool.h), 27 symbols instead of 78. Its own copy of the Dart API DL and the pool internals stay local, so on Linux a same-named symbol from another library in the process can no longer take over an internal call.
Added #
- README: shipping with
dart build clithrough the opt-inslingshot_postgres_assetscompanion, which needsslingshot1.0.5 or later.
No API or ABI version change (still MAJOR 2 / MINOR 6). The native library in lib/_native/ is rebuilt for all
four platforms.
0.1.8 #
Fixed #
- A multi-statement string sent without parameters no longer stalls the isolate. The native worker used to report
the query done as soon as the first result was complete; when a later statement's output was large (64 KB was
enough), the first result arrived early and the Dart side waited for the rest on the isolate's thread, stopping
its event loop for as long as the slowest statement ran. The worker now drains every result first, and the
query
timeoutcovers that wait, which it used to miss. COPY ... TO STDOUT/FROM STDIN, which this package does not support, fails withConnectionLostException, timeout or not: the connection is reset at once, so the backend does not linger in COPY holding its locks, and the session (an open transaction included) is gone. The reconnect has its own budget (5 s), outside the querytimeout, as when a link drops. It used to spin forever while the results were drained.
No API or ABI change. The native library in lib/_native/ is rebuilt for all four platforms: this is the first
release since 0.1.0 that changes it.
0.1.7 #
Fixed #
- Reading a cell from a
PostgresResultRowafterPostgresResultSet.release()throws aStateError, as dorow()androws. It used to read the freedPGresult: in practice a silentnull, indistinguishable from SQL NULL, though nothing guaranteed even that. Metadata (columnNames,rowCount,typeOf) stays readable, andtoString()on a released row no longer touches the result. - A type without a decoder (
int4[],inet, ...), and text-modebyteaoutside the hex format (bytea_output = 'escape'), return their raw bytes as an ownedUint8Listcopy. They used to return a view into thePGresult: a view kept pastrelease()could show bytes of a later query on the same isolate.
No API or ABI change; the native library is the one shipped since 0.1.0.
0.1.6 #
Documentation only: README rewritten, shorter pubspec description. No API or ABI change.
0.1.5 #
First release on pub.dev. Depends on slingshot (the contract package, formerly slingshot_core) from pub.dev,
^1.0.3, instead of by git. No API or ABI change; the native library is the one shipped since 0.1.0. An app
that installs this version from pub.dev must not also take orbiter_postgres 0.1.4 or older by git, which
brings the connector by git: use orbiter_postgres 0.1.5 or newer.
0.1.4 #
Renamed from dart_db_connector_postgres to slingshot_postgres; the repository moved with it. No API change: only the package
name, the library import (package:slingshot_postgres/slingshot_postgres.dart) and the dependency key change. Depends on slingshot_core, the
renamed contract package.
The environment variable DART_DB_CONNECTOR_NATIVE_LIB_PATH, which overrides where the native library is
loaded from, keeps its name: renaming it would change behavior.
0.1.3 #
Consumed by git reference to the tag v0.1.3. Native ABI 2.6, same native library as 0.1.0.
Added #
- Full-text search types decode as
String:tsvector(OID 3614),tsquery(3615) andregconfig(3734), andtypeOfreportsPostgresType.text. Text results return the server's text form; binary results rebuild the same text from the binary structure, so both formats agree ('a':1A 'b','jo':* & 'sil':*). The exception isregconfigin binary results, which carries only the configuration OID and decodes to it as a decimalString('3748'forsimple); text results return the name.PostgresOidgainstsvector,tsqueryandregconfig. These columns used to come back as raw bytes (Uint8List); a::textcast in the query keeps working.
Tests #
full_text_search_test.dart: a generatedtsvectorcolumn with a GIN index, queried withto_tsquery('simple', $1)andParam.text, ranked withts_rank, throughwithTransaction, in both result formats; the GIN index serves the parameterised predicate.
0.1.2 #
Consumed by git reference to the tag v0.1.2. Native ABI 2.6, same native library as 0.1.0.
Added #
PostgresConnectionPool.takeAcquireStats()returns aPoolAcquireStatswith whatacquire()saw since the previous call (connections handed out, total and maximum wait in microseconds, largest waiter queue on arrival, andacquire()calls that hitacquireTimeout) and resets it. It covers every path that borrows a connection,withTransactionandPostgresUnitOfWorkincluded. Counted only withPoolConfig.instrumentationEnabled; otherwise all zero. Per pool, so per isolate. A timed-out call counts only intimeouts.
Tests #
tls_integration_test.dartreads the certificates only fromTLS_PG_CERTS; it no longer defaults to a directory outside the package, and its skip message says what the directory must contain.
0.1.1 #
Consumed by git reference to the tag v0.1.1. Native ABI 2.6, same native library as 0.1.0.
Fixed #
name(OID 19) and"char"(OID 18) columns now decode asStringin both text and binary results, andtypeOfreportsPostgresType.textfor them. They used to come back as raw bytes, which hit every catalog query (pg_class.relname,pg_roles.rolname,pg_class.relkind). A"char"byte with the high bit set reads as\oooin both formats, as the server renders it in text mode since PostgreSQL 15. Code that worked around it with::textkeeps working.executewith several statements in one string (no parameters, text results, so the simple query protocol) now throwsQueryFailedExceptionwith the server message when any statement fails, not only the first. An error from the second statement on used to be dropped: inside a transaction it surfaced on the next query as "current transaction is aborted"; outside one, the whole string was rolled back andexecutereturned normally. On success the result of the first statement is still the one returned.
Documentation #
- README: "Local PostgreSQL with TLS", the points where a local
verify-fullsetup usually goes wrong (SAN, server key ownership,pg_hba.conf, client certificates per role, client key mode, CI). example/05_tls.dartandexample/README.mdno longer point to a directory that is not part of this repository; the certificates directory is now a required argument.
0.1.0 #
First public release, consumed by git reference to the tag v0.1.0. Native ABI 2.6.
Included #
- Native connection pool (
PostgresConnectionPool,PoolConfig): one libpq connection per native thread, completions through Dart native ports, acquire timeout, optional instrumentation, gracefulclose()that waits for borrowed connections. - Reconnection of a pooled connection whose link to the server was lost.
- Session reset when a connection returns to the pool (
sessionResetQuery, defaultDISCARD ALL), with a rollback first for a connection returned inside a transaction; or deferred to the first statement of the next borrow (deferSessionReset, opt-in). - Transactions:
withTransaction,withTransactionOn,withPipelinedTransaction,withTransactionInstrumented;withPostgresConnectionfor autocommit work. TheBEGINof a transaction is deferred and sent together with its first statement. PostgresUnitOfWorkandPostgresRepository<T, K>over the contracts ofdart_db_connector_core1.0.1.- Extended Query protocol with typed parameters (
Param), text and binary result decoding,numericasPostgresNumeric, in-place reads throughPostgresResultSet/PostgresResultRow. - TLS through any libpq parameter, or
PostgresConnInfowith an explicitSslMode; libpq's startup error message inNativePoolStartupException; credentials masked in every exception. - Pre-built native library for
linux-x64,linux-arm64,macos-x64andmacos-arm64inlib/_native/.
ABI history (MAJOR 2) #
| MINOR | Adds |
|---|---|
| 0 | Native thread-per-connection pool: pool_create, pool_acquire, pool_release, pool_submit_query, pool_submit_pipeline, pool_cancel, pool_destroy |
| 1 | pool_submit_query_params: Extended Query protocol with bound parameters |
| 2 | Several reads in one round trip |
| 3 | Reconnection policy for a lost link |
| 4 | libpq's message for a failed pool_create |
| 5 | A statement prefix (the deferred BEGIN) in the same Extended pipeline |
| 6 | N statement prefixes under one Sync, and the transaction status without a round trip |