{"id":13483042,"url":"https://github.com/crystal-lang/crystal-mysql","last_synced_at":"2025-04-04T23:09:28.649Z","repository":{"id":891475,"uuid":"21025208","full_name":"crystal-lang/crystal-mysql","owner":"crystal-lang","description":"MySQL connector for Crystal","archived":false,"fork":false,"pushed_at":"2025-02-12T13:34:48.000Z","size":170,"stargazers_count":107,"open_issues_count":22,"forks_count":37,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-03-28T22:14:32.658Z","etag":null,"topics":["crystal","database","driver","mysql"],"latest_commit_sha":null,"homepage":null,"language":"Crystal","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/crystal-lang.png","metadata":{"funding":{"open_collective":"crystal-lang"},"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-06-20T04:20:56.000Z","updated_at":"2025-02-17T00:01:55.000Z","dependencies_parsed_at":"2024-01-23T21:20:29.092Z","dependency_job_id":"f8ea49fb-afb9-475f-8455-51a880b689d9","html_url":"https://github.com/crystal-lang/crystal-mysql","commit_stats":{"total_commits":137,"total_committers":19,"mean_commits":"7.2105263157894735","dds":0.5985401459854014,"last_synced_commit":"7689c585a33b45873eec35884eed8420bb8434b0"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crystal-lang%2Fcrystal-mysql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crystal-lang%2Fcrystal-mysql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crystal-lang%2Fcrystal-mysql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crystal-lang%2Fcrystal-mysql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/crystal-lang","download_url":"https://codeload.github.com/crystal-lang/crystal-mysql/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247261612,"owners_count":20910108,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["crystal","database","driver","mysql"],"created_at":"2024-07-31T17:01:07.695Z","updated_at":"2025-04-04T23:09:28.619Z","avatar_url":"https://github.com/crystal-lang.png","language":"Crystal","funding_links":["https://opencollective.com/crystal-lang"],"categories":["Database Drivers/Clients"],"sub_categories":[],"readme":"# crystal-mysql [![Build Status](https://travis-ci.org/crystal-lang/crystal-mysql.svg?branch=master)](https://travis-ci.org/crystal-lang/crystal-mysql)\n\n\nMySQL driver implement natively in Crystal, without relying on external libraries.\n\nCheck [crystal-db](https://github.com/crystal-lang/crystal-db) for general db driver documentation. crystal-mysql driver is registered under `mysql://` uri.\n\n## Why\n\nUsing a natively implemented library has a significant performance improvement over working with an external library, since there is no need to copy data to and from the Crystal space and the native code. Initial tests with the library have shown a 2x-3x performance boost, though additional testing is required.\n\nAlso, going through the MySQL external library *blocks* the Crystal thread using it, thus imposing a significant penalty to concurrent database accesses, such as those in web servers. We aim to overcome this issue through a full Crystal implementation of the MySQL driver that plays nice with non-blocking IO.\n\n## Status\n\nThis driver is a work in progress.\nIt implements mysql's binary protocol to create prepared statements.\nContributions are most welcome.\n\n## Installation\n\nAdd this to your application's `shard.yml`:\n\n```yml\ndependencies:\n  mysql:\n    github: crystal-lang/crystal-mysql\n```\n\n## Usage\n\n```crystal\nrequire \"mysql\"\n\n# connect to localhost mysql test db\nDB.open \"mysql://root@localhost/test\" do |db|\n  db.exec \"drop table if exists contacts\"\n  db.exec \"create table contacts (name varchar(30), age int)\"\n  db.exec \"insert into contacts values (?, ?)\", \"John Doe\", 30\n\n  args = [] of DB::Any\n  args \u003c\u003c \"Sarah\"\n  args \u003c\u003c 33\n  db.exec \"insert into contacts values (?, ?)\", args: args\n\n  puts \"max age:\"\n  puts db.scalar \"select max(age) from contacts\" # =\u003e 33\n\n  puts \"contacts:\"\n  db.query \"select name, age from contacts order by age desc\" do |rs|\n    puts \"#{rs.column_name(0)} (#{rs.column_name(1)})\"\n    # =\u003e name (age)\n    rs.each do\n      puts \"#{rs.read(String)} (#{rs.read(Int32)})\"\n      # =\u003e Sarah (33)\n      # =\u003e John Doe (30)\n    end\n  end\nend\n```\n\nWhen running this example, if you get the following exception:\n\n\u003e Unhandled exception: Client does not support authentication protocol requested by server; consider upgrading MySQL client (Exception)\n\nYou have two options, set a password for root, or (most recommended option) create another user with access to `test` database.\n\n```mysql\nCREATE USER 'test'@'localhost' IDENTIFIED WITH mysql_native_password BY 'yourpassword';\nGRANT ALL PRIVILEGES ON test.* TO 'test'@'localhost' WITH GRANT OPTION;\nFLUSH PRIVILEGES;\nquit\n```\n\nThen use the example above changing the `DB.open` line to\n\n```crystal\nDB.open \"mysql://test:yourpassword@localhost/test\" do |db|\n```\n\n### Connection URI\n\nThe connection string has the following syntax:\n\n```\nmysql://[user[:[password]]@]host[:port][/schema][?param1=value1\u0026param2=value2]\n```\n\n#### Transport\n\nThe driver supports tcp connection or unix sockets\n\n- `mysql://localhost` will connect using tcp and the default MySQL port 3306.\n- `mysql://localhost:8088` will connect using tcp using port 8088.\n- `mysql:///path/to/other.sock` will connect using unix socket `/path/to/other.sock`.\n\nAny of the above can be used with `user@` or `user:password@` to pass credentials.\n\n#### Default database\n\nA `database` query string will specify the default database. \nConnection strings with a host can also use the first path component to specify the default database.\nQuery string takes precedence because it's more explicit.\n\n- `mysql://localhost/mydb`\n- `mysql://localhost:3306/mydb`\n- `mysql://localhost:3306?database=mydb`\n- `mysql:///path/to/other.sock?database=mydb`\n\n#### Secure connections (SSL/TLS)\n\nBy default a tcp connection will establish a secure connection, whether a unix socket will not.\n\nYou can tweak this default behaviour and require further validation of certificates using `ssl-mode` and the following query strings.\n\n- `ssl-mode`: Either `disabled`, `preferred` (default), `required`, `verify_ca`, `verify_identity`.\n- `ssl-key`: Path to the client key.\n- `ssl-cert`: Path to the client certificate.\n- `ssl-ca`: Path to the CA certificate.\n\n#### Other query params\n\n- `encoding`: The collation \u0026 charset (character set) to use during the connection.\n            If empty or not defined, it will be set to `utf8_general_ci`.\n            The list of available collations is defined in [`MySql::Collations::COLLATIONS_IDS_BY_NAME`](src/mysql/collations.cr)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrystal-lang%2Fcrystal-mysql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcrystal-lang%2Fcrystal-mysql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrystal-lang%2Fcrystal-mysql/lists"}