sqljocky 0.11.0


This is a MySQL connector for the Dart programming language. It isn't finished, but should work for most normal use. The API is getting reasonably close to where I want it to be now, so hopefully there shouldn't be too many breaking changes in the future.

It will only work in the command-line VM, not in a browser.


The changelog has now been moved to CHANGELOG.md


Create a connection pool:

var pool = new ConnectionPool(host: 'localhost', port: 3306, user: 'bob', password: 'wibble', db: 'stuff', max: 5);

Execute a query:

pool.query('select name, email from users').then((result) {...});

Use the results: (Note: forEach is asynchronous.)

results.forEach((row) {
    print('Name: ${row[0]}, email: ${row[1]}');

Or access the fields by name:

results.forEach((row) {
    print('Name: ${row.name}, email: ${row.email}');

Prepare a query:

pool.prepare('insert into users (name, email, age) values (?, ?, ?)').then((query) {...});

Execute the query:

query.execute(['Bob', 'bob@bob.com', 25]).then((result) {...});

An insert query's results will be empty, but will have an id if there was an auto-increment column in the table:

print("New user's id: ${result.insertId}");

Execute a query with multiple sets of parameters:

query.executeMulti([['Bob', 'bob@bob.com', 25],
        ['Bill', 'bill@bill.com', 26],
        ['Joe', 'joe@joe.com', 37]]).then((results) {...});

Use the list of results:

for (result in results) {
    print("New user's id: ${result.insertId}");

Use a transaction:

pool.startTransaction().then((trans) {
    trans.query('...').then((result) {
        trans.commit().then(() {...});


To run the examples and tests, you'll need to create a 'connection.options' file by copying 'connection.options.example' and modifying the settings.


It is released under the GPL, because it uses a modified part of mysql's include/mysql_com.h in constants.dart, which is licensed under the GPL. I would prefer to release it under the BSD Licence, but there you go.

The Name

It is named after Jocky Wilson, the late, great darts player. (Hence the lack of an 'e' in Jocky.)

Things to do

  • Compression
  • Handle character sets properly (currently defaults to UTF8)
  • Better handling of various data types, especially BLOBs, which behave differently when using straight queries and prepared queries.
  • Implement the rest of mysql's commands
  • Improve performance where possible
  • More unit testing
  • More integration tests
  • DartDoc
  • More Example code
  • Use idiomatic dart where possible
  • Geometry type
  • Decimal type should probably use a bigdecimal type of some sort
  • MySQL 4 types (old decimal, anything else?)
  • Test against multiple mysql versions



  • Added support for packets larger than 16 MB. ConnectionPool's constructor has a new parameter, 'maxPacketSize', which specifies the maximum packet size in bytes. Using packets larger than 16 MB is not currently particularly optimised.
  • Fixed some issues with authentication. In particular, errors should now be thrown when you try to connect to a server which is using an old or unsupported authentication protocol.


  • Added SSL connections. Pass 'useSSL: true' to ConnectionPool constructor. If server doesn't support SSL, connection will continue unsecured. You can check if the connections are secure by calling pool.getConnection().then((cnx) {print(cnx.usingSSL); cnx.release();});


  • Added ConnectionPool.getConnection() which returns a RetainedConnection. Useful if you need to keep a specific connection around (for example, if you need to lock tables).


  • Fixed connection retention error in Query.executeMulti


  • Can now access fields by name.


  • Breaking change: Results no longer has a 'stream' property - it now implements Stream itself. As a result, it also no longer has a 'rows' property, or a 'toResultsList()' method - you can use 'toList()' to convert it into a list instead.


  • Rewritten some connection handling code to make it more robust, and so that it handles stream operations such as 'first' correctly (i.e. without hanging forever).
  • Updated spec for Dart 1.0


  • Support for latest SDK (removal of dart:utf8 library)


  • Support for latest SDK


  • Change prepared statement syntax. Values must now be passed into the execute() method in an array. This change was made because otherwise prepared statements couldn't be used asynchronously correctly - if you used the same prepared query object for multiple queries 'at the same time', the wrong values could get used.


  • Handle errors in the utils package properly
  • Pre-emptively fixed some errors, wrote more tests.


  • Fixed error with large fields.


  • Hopefully full unicode support
  • Fixed problem with null values in prepared queries.


  • Some initial changes for better unicode handling.


  • Blobs and Texts which are bigger than 250 characters now work.


  • Make ConnectionPool and Transaction implement QueriableConnection
  • Improved tests.


  • Fix for new SDK


  • Made an internal class private


  • Breaking change: Now uses streams to return results.


  • Major refactoring so that only the parts of sqljocky which are supposed to be exposed are.


  • Support for M4.


  • Support for M3.
  • Bit fields are now numbers, not lists.
  • Dates now use the DateTime class instead of the Date class.
  • Use new IO classes.


  • Support for the new SDK.


  • SQLJocky now uses a connection pooling model, so the API has changed somewhat.

1. Depend on it

Add this to your package's pubspec.yaml file:

  sqljocky: ">=0.11.0 <0.12.0"

If your package is an application package you should use any as the version constraint.

2. Install it

You can install packages from the command line:

$ pub get

Alternatively, your editor might support pub. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

import 'package:sqljocky/sqljocky.dart';


A MySQL connector


Email code@jamesots.com James Ots