No description or website provided.
Clone or download

README.md

Kitura

APIDoc Build Status - Master macOS Linux Apache 2 Slack Status

SwiftKueryMySQL

MySQL plugin for the Swift-Kuery framework. It enables you to use Swift-Kuery to manipulate data in a MySQL database.

Swift version

The latest version of SwiftKueryMySQL requires Swift 4.0 or newer. You can download this version of the Swift binaries by following this link. Compatibility with other Swift versions is not guaranteed.

Install MySQL

macOS

brew install mysql
mysql.server start

Linux

sudo apt-get update
sudo apt-get install mysql-server libmysqlclient-dev pkg-config
sudo service mysql start

Usage

On macOS, regular swift commands can be used for build and test. Use the example command below for generating an Xcode project.

For example,

swift build
swift test
swift package generate-xcodeproj --xcconfig-overrides Config.xcconfig

On linux standard swift commands will also work provided your mysql installation is version 5.7 or greater. If using an earlier version of mysql add -Xcc -I/usr/include/mysql to swift commands to point the compiler at the mysql header files:

For example,

swift build -Xcc -I/usr/include/mysql/
swift test -Xcc -I/usr/include/mysql/

Add dependencies

Add the SwiftKueryMySQL package to the dependencies within your application’s Package.swift file. Substitute "x.x.x" with the latest SwiftKueryMySQL release.

.package(url: "https://github.com/IBM-Swift/SwiftKueryMySQL.git", from: "x.x.x")

Add SwiftKueryMySQL to your target's dependencies:

.target(name: "example", dependencies: ["SwiftKueryMySQL"]),

Import package

import SwiftKueryMySQL

Using SwiftKueryMySQL

Create an instance of MySQLConnection by calling:

let connection = MySQLConnection(host: host, user: user, password: password, database: database,
                                 port: port, characterSet: characterSet)

Where:

  • host - hostname or IP of the MySQL server, defaults to localhost
  • user - the user name, defaults to current user
  • password - the user password, defaults to no password
  • database - default database to use, if specified
  • port - port number for the TCP/IP connection if connecting to server on a non-standard port (i.e. not 3306)
  • characterSet - MySQL character set to use for the connection

All the connection parameters are optional, so if you were using a standard local MySQL server as the current user, you could simply use:

let connection = MySQLConnection(password: password)

password is also optional, but recommended.

Alternatively, call:

let connection = MySQLConnection(url: URL(string: "mysql://\(user):\(password)@\(host):\(port)/\(database)")!))

You now have a connection that can be used to execute SQL queries created using Swift-Kuery.

If you want to share a connection instance between multiple threads use MySQLThreadSafeConnection instead of MySQLConnection:

let connection = MySQLThreadSafeConnection(host: host, user: user, password: password, database: database,
                                 port: port, characterSet: characterSet)

A MySQLThreadSafeConnection instance can be used to safely execute queries on multiple threads sharing the same connection.

To connect to the server and execute a query:

connection.connect() { error in
   // if error is nil, connect() was successful
   let query = Select(from: table)
   connection.execute(query: query) { queryResult in
      if let resultSet = queryResult.asResultSet {
         for row in resultSet.rows {
            // process each row
         }
      }
   }
}

View the Swift-Kuery documentation for detailed information on using the Swift-Kuery framework.

For testing purposes - MySQL test setup

To run swift test to validate your MySQL installation, you must first run the following commands to set up your MySQL:

mysql_upgrade -uroot || echo "No need to upgrade"
mysql -uroot -e "CREATE USER 'swift'@'localhost' IDENTIFIED BY 'kuery';"
mysql -uroot -e "CREATE DATABASE IF NOT EXISTS test;"
mysql -uroot -e "GRANT ALL ON test.* TO 'swift'@'localhost';"

API Documentation

For more information visit our API reference.

Community

We love to talk server-side Swift, and Kitura. Join our Slack to meet the team!

Deployment via Cloud Foundry

If you include SwiftKueryMySQL as a dependancy in an application you are deploying using the Cloud Foundry Swift buildpack then you will need to specify some additional flags when compiling your application. This is best achieved by adding a file to the root of your application named .swift-build-linux-options with the content:

$ cat .swift-build-options-linux 
-Xcc -I/usr/include/mysql/

These flags tell the compiler where to find the MySQL header files required to build the CMySQL library.

License

This library is licensed under Apache 2.0. Full license text is available in LICENSE.