# Connector/Ruby Guide

### Quickstart Guide: MariaDB Connector/Ruby (using `mysql2` gem)

While there isn't a separate "MariaDB Connector/Ruby" gem, the widely used `mysql2` gem serves as the primary and highly compatible Ruby client for connecting to both MariaDB and MySQL databases. It provides a robust API for database interactions in Ruby applications.

#### 1. Overview

The `mysql2` gem provides a Ruby interface to the MariaDB/MySQL C client library (either `libmysqlclient` or MariaDB Connector/C). It allows Ruby applications to execute SQL queries, fetch results, and manage database connections efficiently. It's available on [rubygems.org/gems/mysql2](https://rubygems.org/gems/mysql2).

#### 2. Installation

Before installing the `mysql2` gem, you might need to install development libraries for MariaDB Connector/C or MySQL Client on your system.

**a. Install System Dependencies (e.g., on Debian/Ubuntu):**

```bash
sudo apt update
sudo apt install libmariadb-dev # Or libmysqlclient-dev
```

On other systems (Fedora, CentOS, macOS), the package names might differ (e.g., `mariadb-devel`, `mysql-devel`).

**b. Install the `mysql2` gem:**

Once the system dependencies are in place, install the gem using Bundler (recommended for Rails/Gemfile projects) or directly via `gem install`:

```bash
# If using Bundler (e.g., in a Rails project's Gemfile)
# Gemfile
# gem 'mysql2'
bundle install

# Or directly
gem install mysql2
```

#### 3. Basic Usage

Here's how to connect to MariaDB and perform common database operations using the `mysql2` gem:

**a. Connect to the Database:**

```ruby
require 'mysql2'

begin
  client = Mysql2::Client.new(
    host: 'localhost',
    port: 3306,
    username: 'your_username',
    password: 'your_password',
    database: 'your_database_name'
  )
  puts "Successfully connected to MariaDB!"

  # ... database operations ...

rescue Mysql2::Error => e
  puts "Error connecting to database: #{e.message}"
ensure
  client&.close # Ensure the connection is closed
end
```

Replace `localhost`, `3306`, `your_username`, `your_password`, and `your_database_name` with your actual database details.

**b. Execute a SELECT Query:**

```ruby
# Assuming 'client' is an open connection
results = client.query("SELECT id, name FROM your_table_name WHERE status = 'active'")

puts "\nSelected Rows:"
results.each do |row|
  puts "ID: #{row['id']}, Name: #{row['name']}"
end
```

The `results` object behaves like an enumerable, allowing you to iterate over rows. Column names are accessible as hash keys.

**c. Execute INSERT/UPDATE/DELETE Queries:**

For data manipulation, use `query`. For safety, **always use prepared statements or proper escaping** for user-provided input.

```ruby
# INSERT Example (using prepared statement)
statement = client.prepare("INSERT INTO your_table_name (name, status) VALUES (?, ?)")
insert_result = statement.execute("New Item", "pending")
puts "\nRows inserted: #{insert_result.affected_rows}, Last ID: #{insert_result.last_id}"

# UPDATE Example
update_result = client.query("UPDATE your_table_name SET status = 'completed' WHERE name = 'New Item'")
puts "Rows updated: #{update_result.affected_rows}"

# DELETE Example
delete_result = client.query("DELETE FROM your_table_name WHERE name = 'New Item'")
puts "Rows deleted: #{delete_result.affected_rows}"
```

**d. Prepared Statements (Recommended for security and performance):**

Prepared statements allow you to separate the SQL query structure from the data, preventing SQL injection and improving performance for repeated queries.

```ruby
# Assuming 'client' is an open connection
statement = client.prepare("SELECT * FROM users WHERE login_count = ?")

# Execute with different parameters
result1 = statement.execute(1)
puts "\nUsers with login_count = 1:"
result1.each { |row| puts row.inspect }

result2 = statement.execute(5)
puts "\nUsers with login_count = 5:"
result2.each { |row| puts row.inspect }
```

**Before Running:**

1. Ensure you have a MariaDB server running and a database/table set up.
2. Replace placeholder values with your actual database credentials and table/column names.

#### Important Notes:

* **Error Handling:** Always wrap your database operations in `begin...rescue...end` blocks to catch `Mysql2::Error` exceptions.
* **Connection Closing:** Ensure your `Mysql2::Client` connection is closed using `client.close` in a `ensure` block to release database resources.
* **Prepared Statements/Escaping:** Never concatenate user-provided strings directly into SQL queries. Use prepared statements with placeholders (`?`) or `client.escape()` for string literals.

#### Further Resources:

* [mysql2 gem on RubyGems.org](https://rubygems.org/gems/mysql2)
* [mysql2 gem Documentation (Rubydoc.info)](https://www.rubydoc.info/gems/mysql2/)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://mariadb.com/docs/connectors/connectors-quickstart-guides/connector-ruby-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.