mysql2 0.24.1
mysql2: ^0.24.1 copied to clipboard
A MySQL and MariaDB driver for Dart and Flutter, including Flutter web through a WebSocket bridge.
Changelog #
0.24.1 #
19 Nov 2026
Document the web bridge variable by variable. MYSQL_HOST and MYSQL_PORT
are the database the bridge dials. MYSQL_BRIDGE_BIND and
MYSQL_BRIDGE_PORT are the WebSocket the page opens. The README walks
through MySQL on 127.0.0.1:3307 with the bridge on 127.0.0.1:8080, and
example/example_web.dart connects to that layout. Diagrams are in doc/.
0.24.0 #
19 Nov 2026
Published as mysql2, the web-capable line of mysql1 0.23.0. Import
package:mysql2/mysql2.dart.
The driver can be used from Flutter web. A browser cannot open a TCP socket,
so the connection is carried over a WebSocket to bin/mysql_bridge.dart,
which opens the database connection. ConnectionSettings.bridgeUrl and
bridgeToken select it. useSSL is not available on that path. The bridge
dials only the host it was configured with.
On a server, on Flutter mobile and on the desktop, a connection with no
bridgeUrl is unchanged.
0.23.0 #
18 Nov 2026
A DECIMAL is now read as a String holding the exact value the server
sent, rather than a double. A double cannot hold every decimal value:
12345678901234567.89 read as 12345678901234568.0, and amounts of money
lost their cents. This is the change most likely to need code changing on
upgrade, and not only where a column is declared DECIMAL: MySQL also sends
a DECIMAL for SUM() and AVG() of an integer column, for / between
integers, and for a literal such as 1.5. Code which takes any of those as a
double, as row[0] as double does, now throws. Turn the text into an exact
type, such as Decimal from package:decimal. Where a double is close
enough, call double.parse on it, or ask the server for one with
CAST(x AS DOUBLE) (MySQL 8.0.17 and later) or x + 0e0. FLOAT and
DOUBLE are still read as double.
Breaking:
- A
DECIMALvalue is read as aString, as above. - A parameter of a type with no SQL literal form throws
MySqlClientError. It used to be written as itstoString(), so a list of strings passed forIN (?)became the one string'[a, b]'and matched nothing, and underNOT INmatched every row. The types still written areint,double,bool,String,DateTime,Duration,BigInt, and bytes. - Bytes are a
Uint8Listor aBlob. Any other list throws, aList<int>included, so wrap one inUint8List.fromListorBlob.fromBytes. AList<int>used to be written as a hex literal, which MySQL compares with a number as a number, so a list of ids passed forIN (?)matched the wrong row:[1, 2]becameX'0102'and matched id 258. A one-element list of a value up to 255, such as[3], matched 3 by coincidence, and that is code this breaks: write= ?, or one?per value. connectthrowsMySqlClientErrorwhenConnectionSettings.characterSetis not a utf8 or utf8mb4 collation. Parameters have been escaped on the client since 0.21.0, which is only safe in those character sets: in GBK or SJIS a crafted value can swallow the escape. The default,CharacterSet.UTF8MB4, is unchanged.
Fixed:
- A
DATETIME,TIMESTAMPorDATEin the hour the clocks skip for daylight saving read an hour late when the process was in a time zone which has it. Where the clocks went forward at midnight, as in America/Sao_Paulo until 2019, that was everyDATEon the day they did, which read as 01:00. - A transaction whose rollback fails throws the error which caused the rollback, not the rollback's own failure. That is most often a query which timed out: it closes the connection, and the rollback then threw "Cannot write to socket, it is closed". The rollback's failure is logged.
0.22.0 #
14 Oct 2026
The licence is now MIT, not GPL. #98 has the detail: every contributor whose code is still in the driver agreed to the change, and what was not agreed has been rewritten. The notice keeps 2012, the year SQLJocky, which this was forked from, first carried one.
Breaking:
ResultRow.fieldsis deprecated, fortoColumnMap(). It is a getter onto that now rather than a map each row holds, so the map it hands back is a copy and writing to it no longer changes the row.ResultRow.toString()printsResultRow({a: 1})rather thanFields: {a: 1}.
Changed:
- A row reads a value by name through its result's schema, which holds where each named column is, so a result builds one of those maps instead of one per row. Reading by name or by index is otherwise unchanged, including which of two columns of the same name is read, and a name no column has still reads as null.
0.21.1 #
05 Oct 2026
- An account with a password on MySQL 8 can log in over a connection which
is not TLS or a unix socket. A
caching_sha2_passwordaccount has to send the server its password the first time it logs in, and the driver now encrypts it with the server's RSA public key, which it asks the server for. It used to refuse. ConnectionSettings.serverPublicKeytakes that key in PEM, for anyone who would rather give it than have the server asked.
0.21.0 #
05 Oct 2026
The connection has been rewritten, and most of this release is what that fixed. Several changes are breaking.
Breaking:
- Requires Dart 3.0.
- The MySQL optimizer does not work well on prepared statements.
Therefore, query parameters are now written into the statement as literals
and sent as plain SQL, and prepared statements are no longer used. The
connection character set must be utf8 or utf8mb4, and the server must not
be in
NO_BACKSLASH_ESCAPESmode. - A query which times out closes the connection. Its response was otherwise liable to be taken for the answer to the next query.
useSSLimplemented.ConnectionSettings.useCompressionis removed. It never worked.- A
DateTimeparameter is sent with its fractional seconds, which the server rounds to the precision of the column. It used to be cut to whole seconds. - Almost all
FINElogging is gone. affectedRowsis never null. For a statement which returns rows it is the number of rows, where it used to be null.ResultRow's constructor takes the result's schema, which breaks a subclass of it outside this package.
Added:
- The result API is closer to
package:postgres, so code which reads rows looks the same against either driver.Resultsis nowResult, a list of rows, andFieldis nowResultSchemaColumn; the old names still work and are deprecated.ResultandResultRowhave aschema, andResultRowhastoColumnMap()andisSqlNull().
Fixed:
- Logging in to MySQL 8 with a password.
caching_sha2_passwordaccounts left the connection one packet out of step, which showed up as the first query returning nothing, each query returning the previous query's rows,RangeError ... Not in inclusive range 0..5, "Got packets out of order" or "Socket has been closed". An account whose plugin is not the server's default now logs in too. - A
caching_sha2_passwordaccount the server has not cached can log in over TLS or a unix socket. Over plain TCP it is refused with a message saying so. CALL: every query after a stored procedure call returned the results of the one before it.DATETIME(n)andTIMESTAMP(n)parameters lost their fraction. Reading aTIME(n)column hung, and a negativeTIMEwas read wrongly.- A value of 16MB or more returned no rows, and a row which exactly filled a packet sent the driver into a loop ("Illegal length 0").
- A value which cannot be decoded, such as a
POINT, fails the query at once. It used to hang until the timeout and close the connection. - An error from the server part way through a result is reported instead of being dropped.
Performance:
- Reading a large result is about ten times faster.
0.20.0 #
30 June 2022
- Add return to transaction
- null safety fixes
0.19.2 #
06 May 2021
- Add mysql8 to test matrix & support caching_sha2_password auth
0.19.1 #
05 May 2021
- Correct parsing of DateTime in non-utc client timezone
0.19.0 #
02 Apr 2021
- Breaking: migrate to Dart 2.12.0 with null safety enabled
0.18.1 #
31 Mar 2021
- Supporting Unix socket connections.
0.18.0 #
- Breaking: Rename
RowtoResultRowso name doesn't conflict withRowfrom Flutter. (#10)
0.17.1 #
19 Dec 2019
- Fix analysis errors
0.17.0+1 #
23 Apr 2019
- Make result field values accessible by name on BinaryDataPackets
- Require
Listtype in public query API
0.17.0 #
23 Apr 2019
- Make result field values accessible by name on BinaryDataPackets
- Require
Listtype in public query API
0.16.3 #
28 Nov 2018
- Improve docs
- Breaking: Test for correct query parameter count on the client side
- Breaking: Tidy up old field by name access code
- Tidy up
Fieldclass
0.16.2 #
23 Oct 2018
- Make
Fielda concrete class - Breaking: Don't export
mysql.constants. These are internal.
0.16.1 #
23 Oct 2018
- Simplify example
0.16.0 #
- Breaking: Validate that all
DateTimevalues passed to and returned fromqueryandqueryMultiare UTC.
0.15.2 #
- Add types to
queryandqueryMultiinterface. This makes the package easier to use withimplicit-dynamic: false
0.15.1 #
- Documentation updates
0.15.0 #
- Publish first version post-fork
Earlier releases, as SQLJocky, are listed in the changelog of https://github.com/jamesots/sqljocky.