mysql_dart 4.0.1
mysql_dart: ^4.0.1 copied to clipboard
Native MySQL client written in Dart. Supports TLS, MySQL 9/9.7 caching_sha2_password, JSON columns, MariaDB 10/11, and Percona/MySQL 5.7/8.
4.0.1 #
- fix:
connect()waited forever when the server answered the handshake with anAuthSwitchRequestfor an authentication plugin the driver does not support; it now fails withMySQLClientException(#15, by Kevin Moore) - fix: an ERR followed by an OK in the same TCP read during the handshake marked the connection as established although the server had refused the login; the ERR now fails
connect()and closes the connection. An auth challenge shorter than 20 bytes is rejected, and the TLS certificate is verified before any auth challenge is read (#15) - fix: an ERR among the parameter and column definitions of a
COM_STMT_PREPAREreply was ignored andprepare()succeeded; it now fails withMySQLServerException(#15) - fix: a malformed RSA public key from the server (
caching_sha2_passwordwithout TLS) is rejected with aFormatException: DER lengths must be minimal and inside the key, the structure must be an RSA SubjectPublicKeyInfo with no trailing bytes, and the modulus and exponent must be plausible.writeVariableEncIntrejects negative values and always writes little-endian, whatever the writer's default (#15) - fix: a truncated or malformed packet from the server (header, greeting, OK, EOF, column count, column definition, prepare OK, auth switch, extra auth data) threw
RangeErrororFormatException; it now throwsMySQLProtocolException. A packet is decoded from its declared length only, so the bytes of the next packet in the same read are no longer taken as part of it (#13, by Kevin Moore) - fix: column names that are not UTF-8 (latin1 metadata sent before
SET NAMES) threw aFormatException; they are decoded like the OK and ERR messages. A greeting whose authentication plugin name is not NUL-terminated (MySQL 5.5/5.6, Bug#59453) is accepted (#13) - fix: malformed rows, text and binary, threw
RangeErrororIndexError: a length-encoded header past the end of the row, an 8-byte length that overflowed a signed 64-bit shift, a binary DATE/DATETIME/TIMESTAMP that is not 0, 4, 7 or 11 bytes or a TIME that is not 0, 8 or 12. They now throwMySQLProtocolException; so doestypedColAt<T>()for aTthe value cannot convert to, which threwTypeError(#14, by Kevin Moore) - fix:
typedColAt<int>()on aBIGINT UNSIGNEDabove 2^63 - 1 threw theFormatExceptionofint.parse(through both protocols, with any server), and so did a numeric or date value not in the format of its column; they now throwMySQLProtocolException, astypedColAtdocuments. Read such a value asStringornum, or withtypedAssoc(), which returns aBigInt - fix: the message of an ERR packet was decoded as strict UTF-8. Errors sent before the handshake use the server's own charset (latin1 with a localized
lc_messages), so a message with an accent threwFormatExceptioninstead ofMySQLServerException - test:
fuzz_decoders_test.dartmutates packets captured from MySQL 9.7, MySQL 5.7 and MariaDB 13 (tool/capture_server_packets.dart) and feeds them to every decoder, to the typed reads and to the RSA key parser; only aMySQLExceptionmay escape. It found the two fixes above - test:
protocol_faults_test.dartreplays captured exchanges through a local TCP server and breaks them at every packet (dropped connection, injected ERR/OK/EOF/empty packets, byte-by-byte or coalesced delivery): every call must end, with a result or aMySQLException, and an ERR must fail it. Against 4.0.0 it reports 85 problems, among them 3 hangs and 25 calls that succeeded despite an ERR; it reports none now - test: the auth, decoder and row bounds tests of #13, #14 and #15 (by Kevin Moore)
- ci: MySQL 5.5 (without TLS), 5.6 and 5.7, and MySQL 8.4 and 9.7 on Windows. The JSON and fractional-second tests skip on servers without them
- docs: why TLS fails with old servers (
UNSUPPORTED_PROTOCOL):dart:iorequires TLS 1.2, MySQL 5.5 and 5.6 before 5.6.46 speak TLS 1.0 only
4.0.0 #
TLS server certificates are now verified (breaking). Reported by Brett Sutton.
- security, breaking: with TLS (
secure: true, the default) any server certificate was accepted: whenonBadCertificatewas not given, the driver accepted every certificate. Anyone between the application and the server could impersonate it, read and change the traffic, and, withcaching_sha2_password(the MySQL 8.4/9 default), get the password, which is sent in clear text inside TLS. The certificate must now chain to a root trusted bysecurityContext(the system roots by default) and namehost; otherwiseconnect()fails with aHandshakeExceptionbefore the credentials are sent, and its message says how to fix it - feat:
verifyServerCertificateincreateConnectionandMySQLConnectionPool(defaulttrue).falseaccepts any certificate, such as the one MySQL and MariaDB generate on first start, for a server in Docker or on the same host; the traffic is still encrypted.onBadCertificate, when given, decides instead. A Unix socket is local and its certificate is not verified - security: a server that sent the greeting and then never answered the TLS handshake kept the TCP connection open after
connect(timeoutMs: ...)timed out, andclose()could not release it:SecureSocket.securetakes over the socket and its handshake cannot be aborted. TLS connections now go through aRawSocketthe driver keeps and closes when the deadline expires, with the same throughput and latency - fix:
connect(timeoutMs: ...)bounds the greeting, TLS handshake, authentication and charset setup together, and a connection that fails or times out is closed - feat:
socketTimeoutincreateConnectionbounds the TCP connection attempt;MySQLConnectionPoolpasses itstimeoutMs - fix: the
KILL QUERYconnection of a query timeout connects to the configured host, not the resolved address, so its certificate is checked against the same name - fix:
MySQLConnectionPoolwent overmaxConnections: a connection under theSELECT 1of the idle test (idleTestThreshold) or of the check after a failed callback, and one being closed, was not counted, so another task opened a new connection beside it (4 connections withmaxConnections: 2). They are now counted until they are returned or closed - fix: a task waiting for a free slot in
MySQLConnectionPoolcould wait forever: a slot freed by a connection attempt that failed, or by a connection the server closed, did not wake the waiting tasks. After a server restart, requests queued while the pool was full hung with the pool empty - fix: an account with an empty password was rejected (
Access denied, error 1045) on MariaDB, and on MySQL without TLS: the handshake sent a hash of the empty password instead of an empty auth response (#7, by Kevin Moore) - docs:
LICENSEkeeps the BSD-3-Clause notice of the originalzim32/mysql.dart(#9, by Kevin Moore) - breaking: the decoders of
package:mysql_dart/mysql_protocol_extension.dartandpackage:mysql_dart/mysql_protocol.dartreturn Dart 3 records instead of the internalTuple2: use.$1/.$2instead of.item1/.item2(#10, by Kevin Moore).MySQLConnectionandMySQLConnectionPoolare not affected - fix: an error sent by the server before the handshake (1040 "Too many connections", a blocked host) lost the first 6 characters of its message, skipped as a SQLSTATE it does not have (from #8, by Kevin Moore)
- fix: a length-encoded field running past the end of a packet throws
MySQLProtocolExceptionnaming the field, instead of aRangeError(from #8) - test: multi-statement batches with OK results, a failing statement,
lastInsertIDper result, a prepared statement after a batch andCALL(from #6, by Paschalis P)
Migrating from 3.x #
- Server using the certificate MySQL/MariaDB generate (Docker, same host): pass
verifyServerCertificate: false. - Server with a certificate from your own CA: keep verification and trust the CA,
securityContext: SecurityContext(withTrustedRoots: true)..setTrustedCertificates('ca.pem'). - Server with a certificate from a public CA that names the host you connect to: nothing to change.
- To verify certificates while still on 3.x: pass the CA in
securityContextandonBadCertificate: (_) => false.
3.0.3 #
- fix:
typedAssoc(),typedColAt<DateTime>()andtypedColByName<DateTime>()turned a dateDateTimecannot represent into another day, becauseDateTime.parserolls an out-of-range month or day over: the zero date0000-00-00(WordPress drafts,sql_modewithout NO_ZERO_DATE) came back as-0001-11-30, a zero month or day (2024-05-00) as the previous month's last day, and an invalid date stored under ALLOW_INVALID_DATES (2024-02-30) as March 1. Dates are now parsed strictly (the server'sYYYY-MM-DD[ hh:mm:ss[.ffffff]]), and such a date is handled by the newzeroDateBehavioroption - feat:
zeroDateBehaviorinMySQLConnection.createConnectionandMySQLConnectionPool:ZeroDateBehavior.convertToNull(default) returnsnull,ZeroDateBehavior.exceptionthrows aMySQLClientExceptionnaming the value (Connector/J'szeroDateTimeBehavior).colAt()andassoc()still return the server's text
3.0.2 #
- fix: a write to a connection the server already closed (
wait_timeout,KILL) failed with "Connection reset by peer" (Linux) on the socket'sdonefuture, which was not observed: it became an uncaught error in the caller's zone (an application's error handler, a failing test), although the command itself already failed with the read-side error. The future is observed now; the command still fails with the error, and the pool replaces the connection
3.0.1 #
-
fix: on MySQL 8.0.22+ the auto-prepared statement of an SQL text was reused for parameters of any type, but MySQL derives a parameter's type when the statement is prepared (or reprepared after a DDL) and converts later values to it:
select ? as vprepared for an int returned0for'a', and an insert prepared while a column was temporal failed with error 3988 ("Conversion from collation utf8mb4_0900_ai_ci into latin1_swedish_ci impossible") once the column becamevarchar. The cache key now includes the parameter types, andcreate/alter/drop/rename/truncateon the connection close the cached statements (MariaDB was not affected) -
fix: an ERR packet that ends a result set after some rows (an error raised while a row is computed) was decoded as a row, which threw and closed the connection; it is now reported as
MySQLServerExceptionand the connection stays usable (text and prepared paths, iterable result sets included) -
fix: a parameter rejected on the client (unsupported type) left the connection "busy with another command" forever; parameters are validated and the packet encoded before the connection is marked busy
-
fix: prepared-statement (binary) results ignored the UNSIGNED flag:
TINYINT UNSIGNED200 came back as -56, andSMALLINT/INT/BIGINT UNSIGNEDabove the signed range were negative;BIGINT UNSIGNEDabove 2^63 - 1 now becomes aBigInt(it threw aFormatExceptionintypedAssoc()) -
fix: TEXT columns with a
_bincollation (and MariaDBJSON) were returned asUint8List: the server sets BINARY_FLAG for every_bincollation, so only thebinarycharacter set (63) now means bytes -
fix: a query timeout left the statement running and the connection busy until it finished; the statement is now interrupted with
KILL QUERY(through a short-lived second connection) and the connection is ready when the timeout is reported -
fix:
:nameplaceholders inside strings with'escapes, backtick identifiers and comments (--,#,/* */) were treated as parameters -
fix:
transactional()marked the transaction beforeSTART TRANSACTIONsucceeded and a failingROLLBACKreplaced the original error and left "Already in transaction" set; the state is now always cleared, the original error kept, and a connection whose rollback failed is closed -
fix:
close()(andMySQLConnectionPool.close()) waited forever after the server closed the session (KILL, restart, network): it flushed the destroyed socket; it now just releases the connection -
feat:
Map,ListandSetparameters are sent as JSON text andBigIntas its decimal text (they were rejected) -
feat: concurrent callers of one
MySQLConnectionwait for their turn (FIFO) instead of failing with "connection is busy with another command" (execute,prepare,PreparedStmt.execute/deallocate; an iterable result set holds the turn until its last row arrives).transactional()holds the connection: commands and transactions from other callers wait until it commits or rolls back, while commands from its callback (concurrent ones included, recognized through aZonevalue) run inside it; a secondtransactional()from the callback still fails with "Already in transaction".createConnection(queueConcurrentCalls: false)keeps the 3.0.0 fail-fast behavior. The pool is unchanged (one caller per connection) -
fix: cancelling an iterable result set's stream after it ended closed the connection when another command was already running on it
-
fix: a multi-statement query whose first statement returns no rows (
INSERT ...; SELECT ...) returned only that first result and left the others unread, so the next command got them as its reply (the OK packet's SERVER_MORE_RESULTS_EXISTS flag was ignored); every result is now chained throughnext -
fix:
CALLthrough the text protocol returned only its final OK (its result sets were dropped), and through a prepared statement (executewith parameters,prepare) left that OK unread, so the next command got it as its reply; the result sets are now returned, chained throughnext, followed by the OK -
fix: an iterable result set of a multi-statement query or
CALLleft the following results unread for the next command; they are now read and discarded, and the stream ends after the last one -
fix: a command waiting for its reply (and the commands queued behind it) waited forever when the server closed the connection (
KILL, restart, network) or the socket failed; it now fails withMySQLClientException("Connection closed"), an iterable stream gets the error, andclose()completes (it threw when the connection had been closed mid-command, or by the driver itself) -
fix: pausing an iterable result set's stream after its last rows were buffered (e.g. an
await forwhose body awaits) left the socket paused, so the next command on the connection waited forever; the socket is resumed when the command ends, and a pause after the end no longer pauses the next command -
fix:
prepare()of a statement with no parameters and no result columns (DDL,INSERTwithout placeholders, ...) waited forever for packets the server does not send -
fix:
execute(sql, [...])(auto-prepared) silently ignored extra positional parameters and sent a malformed packet for missing ones; a wrong count now throwsMySQLClientException, asPreparedStmt.executedoes -
fix: prepared-statement (binary) DATETIME/TIMESTAMP/TIME fractional seconds were not zero-padded:
03:04:05.005came back as03:04:05.5000(half a second) and.000001as.1; years below 1000 were not padded either, sotypedAssoc()threw aFormatException -
fix: payloads of 0xffffff bytes (16 MB) or more were not split when sent (the 3-byte length was truncated) nor joined when received (a row of exactly 0xffffff bytes threw a
RangeError); they are now framed as several packets -
fix: nested
transactional()calls on two connections deadlocked (the inner one hid the outer one's zone value), and work left running by a finishedtransactional()callback joined another caller's later transaction (and its rollback); the zone value is now per connection and per transaction -
perf: a packet arriving in many socket chunks (multi-megabyte rows, especially over TLS) is assembled once instead of re-merging every byte received so far on each chunk, which was quadratic (a 16 MB row over TLS took tens of seconds)
-
test:
regression_protocol_test.dartcovers each fix against a real server -
test:
concurrency_test.dartcovers concurrent commands, prepared statements, iterable result sets and transactions on one connection -
test:
coverage_matrix_test.dartruns every entry point (text, named/positional parameters,prepare, iterable, pool,transactional) against every statement kind and checks that the next command gets its own reply;coverage_types_test.dartround-trips every column type through both protocols (NULLs, limits, fractional seconds, utf8mb4, 16 MB packets);coverage_recovery_test.dartcovers server errors, timeouts, paused and cancelled streams, killed connections with queued commands, the auto-prepared statement cache and the pool under load
3.0.0 #
- breaking: raised the minimum Dart SDK to
^3.6.0, aligning the package with the AOT benchmark baseline and allowing future hot-path refactors to use modern Dart features - perf:
COM_STMT_EXECUTEcan now encode directly into a complete MySQL packet with a precomputed buffer, avoiding the genericMySQLPacket+ByteDataWriterpath for prepared-statement execution - perf:
typedAssoc()now avoids reparsing values that already arrived as typed Dart values, reducing overhead for PDO-style integrations such as Eloquent that materialize every row as a typed map - fix: cleaned up Dart 3 analyzer diagnostics in connection/auth and exception code paths without changing public exception formatting
- fix: the connection pool now validates connections after operation errors and retires broken sockets instead of returning them to the idle queue, improving recovery after database restarts
- test: added protocol unit coverage for direct
COM_STMT_EXECUTEpacket encoding, null bitmaps, variable-length values, temporal values, and exception formatting - test: added real database integration coverage for prepared-statement binary result decoding with JSON payloads and BLOB bytes
- test: added an opt-in destructive pool restart test controlled by
MYSQL_RESTART_COMMAND, allowing local validation against a real MySQL/MariaDB service restart under load - docs: expanded the performance roadmap with Dart SDK baseline planning and architectural ideas from
dpgsql/Npgsql for pool, data source, telemetry, retries, and auto-prepare evolution
2.0.0 #
- feat: added compatibility with MySQL Community Server 9 and 9.7, including
caching_sha2_passwordfull authentication with TLS, pinned RSA public keys, or optional server public key retrieval - feat: binary protocol now supports MySQL JSON columns (
column type 245), decoding them as UTF-8 JSON strings instead of failing at the protocol layer - feat: integration tests now read
MYSQL_*environment variables so they can run against any local or CI port/configuration - ci: GitHub Actions now runs the test suite against MySQL 9.7 in addition to the existing database coverage
- refactor: removed external runtime dependencies on
asn1lib,pointycastle,buffer,crypto, andtupleby inlining the required PEM/RSA/OAEP, hashing, tuple, and byte-writer logic - perf: removed artificial latency from
connect()andclose()by replacing handshake polling withCompletersignaling and removing the fixed close delay - perf: compiled AOT benchmark now reaches
0.532 msaverage connect latency,11,255text queries/s,11,362prepared queries/s, and839,539rows/s on 10,000-row result sets in the local MariaDB benchmark - perf: local AOT benchmark beats PHP PDO on connect latency,
SELECT 1, and 10,000-row result-set throughput, and beats PHP mysqli on connect latency and 10,000-row throughput while mysqli still leads tiny prepared statements through its native C extension - perf: documented remaining performance headroom after 2.0.0, especially direct
COM_STMT_EXECUTEencoding, per-result-set decode plans, lower row wrapper allocation, streaming memory behavior, and the final incremental packet reader/ring buffer - perf:
connect()now supportssetCharsetOnConnect: false, allowing the initial charset/collationSETround-trip to be measured or skipped explicitly - perf: packet header parsing, length-encoded integers, null-terminated strings, and packet splitting were rewritten to avoid hot-path temporary objects and repeated list concatenation
- perf:
COM_STMT_EXECUTEnow skips resending parameter type metadata when the parameter signature has not changed for the prepared statement - perf: textual result-set row decoding now parses length-encoded cells inline, removing per-cell helper tuple allocation in the large result-set path
- perf: binary result-set row decoding now fast-paths common length-encoded column types, reducing per-cell helper dispatch and tuple allocation for
VARCHAR,TEXT,JSON,DECIMAL,BLOB,BIT, andGEOMETRY - perf: result-set metadata now caches case-insensitive column name lookups and precomputed Dart type hints, reducing repeated work in
colByName(),typedColByName(), andtypedAssoc() - feat: iterable result sets now propagate stream
pause/resumeto the socket subscription, enabling real backpressure for row-by-row consumers - feat: benchmark tooling now separates TLS vs non-TLS runs, measures connect latency with and without the initial charset
SET, recordsmedian,p95, andp99, and compares materialized vs streaming result sets - feat: added profiling and stress tools for result-set heap inspection (
vm_service) and auto-prepared statement cache behavior under hot-set and thrash-set workloads - feat:
MySQLConnectionnow exposes auto-prepared statement cache statistics for hits, misses, evictions, deferred closes, and current cache occupancy - feat: auto-prepared statement cache capacity is now configurable per connection and per pool with
autoPreparedStatementCacheCapacity - breaking:
MySQLConnectionPool.execute(..., iterable: true)was removed because streamed results keep the physical connection busy until EOF and the old pooled flow could release the connection early - breaking:
MySQLConnectionPool.prepare()was removed and replaced bywithPrepared(...), because prepared statements are bound to one physical connection and the old API could return a statement whose owning connection had already been reused by unrelated work - docs: README and roadmap now document the new pooling constraints,
withPrepared(...), iterable result-set backpressure, benchmark methodology, and the distinction between locally tested and CI-covered server versions
1.2.1 #
- fix: textual and binary result sets now decode strings with UTF-8 so accented characters appear correctly
- fix: connection pool returns connections to the idle queue even when
withConnectioncallbacks throw, preventing resource leaks - fix: connection pool enforces
maxConnectionseven when multiple connections are being established concurrently - feat:
MySQLConnectionPoolgained idle connection validation, recycling by age/usage,timeZone,onConnectionOpencallback, basic retry policy, andstatus()method for inspection.
1.2.0 #
- feat:
MySQLConnection.executenow accepts positional lists and named maps directly; when parameters are present the driver auto-prepares, caches, and executes statements over the binary protocol so blobs/bytes are handled transparently - fix: textual BLOB/TEXT columns are decoded as UTF‑8 strings consistently (even for auto-prepared/binary protocol queries), matching the associative API expectations
- docs: README now documents the new
execute()usage patterns and clarifies that DECIMAL/NEWDECIMAL columns are surfaced as strings to avoid precision loss
1.0.0 #
- implemented "provide SSL certificates in createConnection"
final SecurityContext context = SecurityContext(withTrustedRoots: true);
final sslConn = await MySQLConnection.createConnection(
host: 'localhost',
port: 3306,
userName: 'dart',
password: 'dart',
databaseName: 'banco_teste',
secure: true,
securityContext: context,
onBadCertificate: (certificate) => true,
);
await sslConn.connect();
- implemented blob support
await connection.execute(
"CREATE TABLE binary_test (id INT AUTO_INCREMENT PRIMARY KEY, data BLOB)");
final binaryData = Uint8List.fromList([0, 255, 127, 128]);
final stmt =
await connection.prepare("INSERT INTO binary_test (data) VALUES (?)");
final res = await stmt.execute([binaryData]);
expect(res.affectedRows.toInt(), equals(1));
await stmt.deallocate();
final result = await connection.execute("SELECT data FROM binary_test");
final row = result.rows.first;
expect(row.typedColByName<Uint8List>("data"), equals(binaryData));
- implemented more tests and fix bugs
0.0.30 #
- feat: Binary prepared statements with enhanced integration and unit tests
0.0.30 #
- Rename mysql_client to mysql_dart
0.0.29 #
- Add Support empty password
0.0.27 #
- Add timeoutMs param to pool constructor
0.0.26 #
- Change default charset to ut8mb4 (fix emojies)
- Add timeoutMs option to connect() method
- Increase default timeout from 5 seconds to 10 seconds
0.0.25 #
- Add support for unix socket connection. See example/main_unix_socket.dart
0.0.24 #
- Fix colByName and typedColByName: ignore column name case
0.0.23 #
- Fix caching_sha2_password auth plugin
0.0.22 #
- Check server supports SSL
- Add support for multiple statements
0.0.21 #
- Fix _lastError reset in _forceClose() and used after
0.0.20 #
- Refactor error handling
- Add section about error handling to README.md
- Fix connection pool bugs
- Fix mysql protocol string parsing (ascii instead of utf8)
0.0.19 #
- Expose mysql server error code in MySQLServerException
0.0.18 #
- Remove general Exception class. Add custom exception classes
0.0.17 #
- Fix string encoding in prepared statements
0.0.16 #
- Fix in transaction flag
0.0.15 #
- Fix capability flags parsing
0.0.14 #
- Fix prepared statement select with params (handle two EOF packets if numOfCols and numOfParams are both > 0)
0.0.13 #
- Fix decoding long strings
0.0.12 #
- Add info about typed access to readme and examples
0.0.11 #
- Implement typed access to column data
- Add tests
0.0.10 #
- Add more docs and examples
0.0.9 #
- Use utf8 charset by default
- Encode all data using utf8.encode() and utf8.decode()
0.0.8 #
- Improve error handling
- Add handling of incomplete packets in _spliPackets() method
- Fix parameters substitution
- Add mysql_client tests
0.0.7 #
- Add doc comments and example
0.0.6 #
- Implement iterable result sets
0.0.5 #
- Implement caching_sha2_password auth plugin
- Refactor data packets handling
- Split data packets
- Fix some bugs
0.0.4 #
- Implement SSL connection
- Fix bug with hardcoded host and port
0.0.3 #
- Implement prepared statements
- Add more tests
0.0.2 #
- Fix readme and docs
0.0.1 #
- Initial version.