createConnection static method

Future<MySQLConnection> createConnection({
  1. required dynamic host,
  2. required int port,
  3. required String userName,
  4. required String password,
  5. bool secure = true,
  6. String? databaseName,
  7. String collation = 'utf8mb4_general_ci',
  8. SecurityContext? securityContext,
  9. bool onBadCertificate(
    1. X509Certificate certificate
    )?,
  10. bool verifyServerCertificate = true,
  11. bool allowPublicKeyRetrieval = false,
  12. String? serverPublicKey,
  13. int autoPreparedStatementCacheCapacity = 32,
  14. bool queueConcurrentCalls = true,
  15. ZeroDateBehavior zeroDateBehavior = ZeroDateBehavior.convertToNull,
  16. Duration? socketTimeout,
})

Creates connection with provided options.

Keep in mind, this is async function. So you need to await result. Don't forget to call MySQLConnection.connect to actually connect to database, or you will get errors. See examples directory for code samples.

host host to connect to. Can be String or InternetAddress. userName database user name. password user password. secure If true - TLS will be used, if false - ordinary TCL connection.

verifyServerCertificate (default true): with TLS, the server certificate must chain to a root trusted by securityContext (the system roots by default) and name host; otherwise the connection fails before the user name and password are sent. Pass false to accept any certificate, such as the one MySQL and MariaDB generate on first start (Docker, a server on the same host): the traffic is still encrypted, but nothing proves it reaches the right server. To keep verification with a private CA, add the CA to securityContext instead. onBadCertificate, when given, decides instead of this flag. A Unix socket is local, so its certificate is not verified.

socketTimeout bounds the TCP connection attempt (no limit by default); connect's timeoutMs bounds the rest. databaseName Optional database name to connect to. collation Optional collaction to use.

By default after connection is established, this library executes query to switch connection charset and collation:

SET @@collation_connection=$_collation, @@character_set_client=utf8mb4, @@character_set_connection=utf8mb4, @@character_set_results=utf8mb4

queueConcurrentCalls (default true): concurrent callers wait for their turn, and commands from outside a transactional callback wait for it to end. With false, a command issued while another one runs fails with "connection is busy with another command" and a second transactional with "Already in transaction" (the 3.0.0 behavior, useful to detect a connection shared by mistake).

zeroDateBehavior (default ZeroDateBehavior.convertToNull): what the typed reads return for a date DateTime cannot represent, such as the zero date 0000-00-00; ZeroDateBehavior.exception throws instead.

Implementation

static Future<MySQLConnection> createConnection({
  required dynamic host,
  required int port,
  required String userName,
  required String password,
  bool secure = true,
  String? databaseName,
  String collation = 'utf8mb4_general_ci',
  SecurityContext? securityContext,
  bool Function(X509Certificate certificate)? onBadCertificate,
  bool verifyServerCertificate = true,
  bool allowPublicKeyRetrieval = false,
  String? serverPublicKey,
  int autoPreparedStatementCacheCapacity = 32,
  bool queueConcurrentCalls = true,
  ZeroDateBehavior zeroDateBehavior = ZeroDateBehavior.convertToNull,
  Duration? socketTimeout,
}) async {
  if (autoPreparedStatementCacheCapacity < 1) {
    throw ArgumentError.value(
      autoPreparedStatementCacheCapacity,
      'autoPreparedStatementCacheCapacity',
      'must be at least 1',
    );
  }

  // Logger.level = loggingLevel;
  // logger.d("Establishing socket connection");
  // TLS goes through RawSocket, which the driver can close during a
  // handshake the server never answers (see RawSocketAdapter).
  final Socket socket = secure
      ? RawSocketAdapter(
          await RawSocket.connect(host, port, timeout: socketTimeout))
      : await Socket.connect(host, port, timeout: socketTimeout);
  // logger.d("Socket connection established");
  if (socket.address.type != InternetAddressType.unix) {
    // no support for extensions on sockets
    socket.setOption(SocketOption.tcpNoDelay, true);
  }

  final client = MySQLConnection._(
    socket: socket,
    username: userName,
    password: password,
    databaseName: databaseName,
    secure: secure,
    collation: collation,
    allowPublicKeyRetrieval: allowPublicKeyRetrieval,
    serverPublicKey: serverPublicKey,
    autoPreparedStatementCacheCapacity: autoPreparedStatementCacheCapacity,
    queueConcurrentCalls: queueConcurrentCalls,
    zeroDateBehavior: zeroDateBehavior,
  );

  // Armazena os parĂ¢metros de SSL no cliente (adicione esses campos na classe)
  client._securityContext = securityContext;
  client._onBadCertificate = onBadCertificate;
  client._verifyServerCertificate = verifyServerCertificate;
  client._socketTimeout = socketTimeout;
  client._host = host;
  client._port = port;

  return client;
}