Repository files navigation

🔗Test coverage (EUnit)🔗API documentation (EDoc)🔗Hex package

MySQL/OTP is a driver for connecting Erlang/OTP applications to MySQL andMariaDB databases. It is a native implementation of the MySQL protocol inErlang.

Some of the features:

• Mnesia style transactions:
  • Nested transactions are implemented using SQL savepoints.
  • Transactions are automatically retried when deadlocks are detected.
• Each connection is a gen_server, which makes it compatible with Poolboy (forconnection pooling) and ordinary OTP supervisors.
• SSL.
• Authentication methodscaching_sha2_password (default from MySQL 8.0.4) andmysql_native_password (default from MySQL 4.1).
• Parametrized queries using cached unnamed prepared statements(What?)
• Slow queries are interrupted without killing the connection (MySQL version≥ 5.0.0)
• Implements both protocols: the binary protocol for prepared statements andthe text protocol for plain queries.

Requirements:

• Erlang/OTP version 21 or later
• MySQL database version 4.1 or later or MariaDB
• GNU Makeor Rebar or any other tool for building Erlang/OTP applications

%% Connect (ssl is optional){ok,Pid}=mysql:start_link([{host,"localhost"}, {user,"foo"},                              {password,"hello"}, {database,"test"},                              {ssl, [{server_name_indication,disable},                                     {cacertfile,"/path/to/ca.pem"}]}]),%% Select{ok,ColumnNames,Rows}=mysql:query(Pid, <<"SELECT * FROM mytable WHERE id = ?">>, [1]),%% Manipulate dataok=mysql:query(Pid,"INSERT INTO mytable (id, bar) VALUES (?, ?)", [1,42]),%% Separate calls to fetch more info about the last queryLastInsertId=mysql:insert_id(Pid),AffectedRows=mysql:affected_rows(Pid),WarningCount=mysql:warning_count(Pid),%% Mnesia style transaction (nestable)Result=mysql:transaction(Pid,fun () ->ok=mysql:query(Pid,"INSERT INTO mytable (foo) VALUES (1)"),throw(foo),ok=mysql:query(Pid,"INSERT INTO mytable (foo) VALUES (1)")end),caseResultof    {atomic,ResultOfFun} ->io:format("Inserted 2 rows.~n");    {aborted,Reason} ->io:format("Inserted 0 rows.~n")end,%% Multiple queries and multiple result sets{ok, [{[<<"foo">>], [[42]]}, {[<<"bar">>], [[<<"baz">>]]}]}=mysql:query(Pid,"SELECT 42 AS foo; SELECT 'baz' AS bar;"),%% Graceful timeout handling: SLEEP() returns 1 when interrupted{ok, [<<"SLEEP(5)">>], [[1]]}=mysql:query(Pid, <<"SELECT SLEEP(5)">>,1000),%% Close the connectionmysql:stop(Pid).

Usingerlang.mk:

DEPS = mysqldep_mysql = git https://github.com/mysql-otp/mysql-otp 1.9.0

Usingrebar (version 2 or 3):

{deps, [  {mysql,".*", {git,"https://github.com/mysql-otp/mysql-otp",                {tag,"1.9.0"}}}]}.

Usingmix:

{:mysql,git:"https://github.com/mysql-otp/mysql-otp",tag:"1.9.0"},

There's also a Hex package calledmysql.

EUnit tests are executed usingmake tests ormake eunit.

To run individual test suites, usemake eunit t=SUITE where SUITE is one ofmysql_encode_tests,mysql_protocol_tests,mysql_tests,ssl_tests ortransaction_tests.

The encode and protocol test suites does not require arunning MySQL server on localhost.

To quickly setup MySQL or MariaDB runing in docker for testing,executemake tests-prep, then executemake tests.

Set environemt variableMYSQL_IMAGE=mysql|mariadb andMYSQL_VERSION to pick a flavor.

To test aginast MySQL or MariaDB running in localhost, follow the below steps:

• Stop MySQL service
• Generate SSL certificates by runningmake -C test/ssl
• Copytest/ssl/server-{cert,key}.pem to/etc/mysql/
• Copytest/ssl/ca.pem to/etc/mysql/
• Change certificate file modes:sudo chmod -R 660 /etc/mysql/*.pem
• Change certificate file owner:sudo chown mysql:mysql /etc/mysql/*.pem
• Append SSL configs:cat test/ssl/my-ssl.cnf | sudo tee -a /etc/mysql/conf.d/my-ssl.cnf
• Start MySQL service
• Runsudo ./scripts/init.sh to prepare for test users.The script connects to the database on localhost as root and creates users.Alternatively, look into the script and perform the steps manually.
• Runmake tests.

If you runmake tests COVER=1 a coverage report will be generated. Opencover/index.html to see that any lines you have added or modified are coveredby a test.

Run the tests and also dialyzer usingmake dialyze.

Linebreak code to 80 characters per line and follow a coding style similar tothat of existing code.

Keep commit messages short and descriptive. Each commit message should describethe purpose of the commit, the feature added or bug fixed, so that the commitlog can be used as a comprehensive change log.CHANGELOG.md isgenerated from the commit messages.

This is for the project's maintainer(s) only.

Tagging a new version:

1. Before tagging, update src/mysql.app.src and README.md with the new version.
2. Tag and push tags usinggit push --tags.
3. After tagging a new version:

• Update the changelog usingmake CHANGELOG.md and commit it.
• Update the online documentation and coverage reports usingmake gh-pages.Then push the gh-pages branch usinggit push origin gh-pages.

Updating the Hex package (requires Mix):

make publish-hex

GNU Lesser General Public License (LGPL) version 3 or any later version.Since the LGPL is a set of additional permissions on top of the GPL, bothlicense texts are included in the filesCOPYING andCOPYING.LESSER respectively.