Python×MariaDB完全ガイド｜インストール・接続・CRUD操作・エラーハンドリング

1. はじめに

PythonでMariaDBを操作したい方へ

こんな悩みはありませんか？

• PythonからMariaDBに接続する方法がわからない
• データの追加・取得・更新・削除をPythonで簡単に操作したい
• よくあるエラーとその対処法を知りたい

本記事で学べること

• MariaDBにPythonから簡単に接続する方法
• CRUD（データの追加・取得・更新・削除）の実装方法
• よくあるエラーとその解決策
• トランザクション処理でデータの整合性を守る方法

2. 環境の準備（MariaDB & Pythonのインストール）

MariaDBとは？

必要なツール

• Python（バージョン3.x以上推奨）
• MariaDB（サーバー）
• MariaDBのPythonコネクタ（mariadbライブラリ）

MariaDBのインストール手順（OS別）

Windowsの場合

1. 公式サイトからMariaDBのインストーラーをダウンロード。
2. インストーラーを実行し、指示に従ってインストール。
3. インストール後、以下のコマンドでMariaDBの動作を確認。

mysql -u root -p

4. 正常にログインできれば、インストール完了。

Macの場合

1. Homebrewがインストールされていない場合は、以下のコマンドでインストール。

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. MariaDBをインストール。

brew install mariadb

3. MariaDBを起動。

brew services start mariadb

4. インストールの確認。

mysql -u root -p

Linux（Ubuntu）の場合

1. パッケージリストを更新し、MariaDBをインストール。

sudo apt update
sudo apt install mariadb-server mariadb-client

2. MariaDBを起動。

sudo systemctl start mariadb

3. MariaDBを有効化（起動時に自動起動するように設定）。

sudo systemctl enable mariadb

4. MariaDBの設定を行う。

sudo mysql_secure_installation

Pythonと必要なライブラリのインストール

1. pipを使用してmariadbライブラリをインストール。

pip install mariadb

2. インストールの確認。

import mariadb
print("MariaDBライブラリが正常にインストールされました。")

3. MariaDBへの接続

MariaDBにPythonで接続する方法

必要なライブラリのインポート

import mariadb

データベースへ接続する基本コード

import mariadb

# データベース接続情報
config = {
    "host": "localhost",   # MariaDBサーバーのホスト名
    "user": "root",        # MariaDBのユーザー名
    "password": "password", # MariaDBのパスワード
    "database": "sample_db" # 接続するデータベース名
}

try:
    # MariaDBに接続
    conn = mariadb.connect(**config)
    print("MariaDBに接続しました！")

    # カーソルを作成
    cursor = conn.cursor()

    # 接続が成功したら、接続を閉じる
    cursor.close()
    conn.close()
except mariadb.Error as e:
    print(f"接続エラー: {e}")

connect() 関数の引数について

環境変数を使用したセキュアな接続方法

python-dotenv のインストール

pip install python-dotenv

.env ファイルを作成し、接続情報を記述

DB_HOST=localhost
DB_USER=root
DB_PASSWORD=password
DB_NAME=sample_db

Pythonスクリプトで環境変数を読み込む

import mariadb
import os
from dotenv import load_dotenv

# .envファイルを読み込む
load_dotenv()

config = {
    "host": os.getenv("DB_HOST"),
    "user": os.getenv("DB_USER"),
    "password": os.getenv("DB_PASSWORD"),
    "database": os.getenv("DB_NAME")
}

try:
    conn = mariadb.connect(**config)
    print("MariaDBにセキュアに接続しました！")
    conn.close()
except mariadb.Error as e:
    print(f"接続エラー: {e}")

よくある接続エラーとその対処法

Access denied for user 'root'@'localhost'

エラー内容

mariadb.OperationalError: Access denied for user 'root'@'localhost' (using password: YES)

原因

• ユーザーの認証情報が間違っている
• MariaDBの認証設定が適切でない

解決策

1. MariaDBにログインし、ユーザーの権限を確認する。

mysql -u root -p

2. 必要な権限をユーザーに付与する。

GRANT ALL PRIVILEGES ON *.* TO 'root'@'localhost' IDENTIFIED BY 'password' WITH GRANT OPTION;
FLUSH PRIVILEGES;

3. 再度接続を試みる。

Can't connect to MySQL server on 'localhost'

エラー内容

mariadb.OperationalError: Can't connect to MySQL server on 'localhost' (10061)

原因

• MariaDBサーバーが起動していない
• host の設定が間違っている

解決策

1. サーバーが起動しているか確認。

sudo systemctl status mariadb

2. サーバーが停止している場合は起動する。

sudo systemctl start mariadb

3. host の設定が正しいか確認。

まとめ

• mariadb.connect() を使用した基本的な接続方法
• .env ファイルを活用したセキュアな接続方法
• よくある接続エラーとその対策

4. データベースとテーブルの作成

データベースの作成

MariaDB管理ツールでデータベースを作成する

CREATE DATABASE sample_db;

SHOW DATABASES;

Pythonを使ってデータベースを作成する

import mariadb

# データベース接続（データベース指定なし）
config = {
    "host": "localhost",
    "user": "root",
    "password": "password"
}

try:
    conn = mariadb.connect(**config)
    cursor = conn.cursor()

    # データベースの作成
    cursor.execute("CREATE DATABASE IF NOT EXISTS sample_db")

    print("データベース 'sample_db' を作成しました。")

    cursor.close()
    conn.close()
except mariadb.Error as e:
    print(f"エラー発生: {e}")

IF NOT EXISTS を付けることで、既に同じ名前のデータベースが存在する場合にエラーを防げます。

テーブルの作成

テーブルの基本構造

SQLでテーブルを作成

USE sample_db;

CREATE TABLE users (
    id INT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    email VARCHAR(100) UNIQUE NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

SHOW TABLES;

Pythonを使ってテーブルを作成

import mariadb

# データベース接続
config = {
    "host": "localhost",
    "user": "root",
    "password": "password",
    "database": "sample_db"
}

try:
    conn = mariadb.connect(**config)
    cursor = conn.cursor()

    # テーブル作成SQL
    table_creation_query = """
    CREATE TABLE IF NOT EXISTS users (
        id INT AUTO_INCREMENT PRIMARY KEY,
        name VARCHAR(100) NOT NULL,
        email VARCHAR(100) UNIQUE NOT NULL,
        created_at DATETIME DEFAULT CURRENT_TIMESTAMP
    )
    """

    cursor.execute(table_creation_query)
    print("テーブル 'users' を作成しました。")

    cursor.close()
    conn.close()
except mariadb.Error as e:
    print(f"エラー発生: {e}")

IF NOT EXISTS を付けることで、テーブルが既に存在する場合にエラーを防ぎます。

データ型の選び方

既存のテーブルを確認・削除する方法

既存のテーブルを確認する

SHOW TABLES;

DESCRIBE users;

テーブルを削除する

DROP TABLE users;

cursor.execute("DROP TABLE IF EXISTS users")

まとめ

• MariaDBのデータベースを作成する方法
• Pythonを使ってテーブルを作成する方法
• 適切なデータ型の選び方
• 既存のテーブルの確認・削除方法

5. CRUD操作（データの追加・取得・更新・削除）

データの追加（INSERT）

SQLによるデータ追加

INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com');

SELECT * FROM users;

Pythonでデータを追加する

import mariadb

# データベース接続設定
config = {
    "host": "localhost",
    "user": "root",
    "password": "password",
    "database": "sample_db"
}

try:
    conn = mariadb.connect(**config)
    cursor = conn.cursor()

    # データの挿入
    insert_query = "INSERT INTO users (name, email) VALUES (?, ?)"
    data = ("Alice", "alice@example.com")
    cursor.execute(insert_query, data)

    # 変更を保存
    conn.commit()
    print("データを追加しました！")

    cursor.close()
    conn.close()
except mariadb.Error as e:
    print(f"エラー発生: {e}")

ポイント:

• ? プレースホルダーを使うことで、SQLインジェクションを防ぐことができます。
• conn.commit() を実行しないと、データがデータベースに保存されません。

データの取得（SELECT）

SQLによるデータ取得

SELECT * FROM users;

SELECT * FROM users WHERE email = 'alice@example.com';

Pythonでデータを取得する

import mariadb

config = {
    "host": "localhost",
    "user": "root",
    "password": "password",
    "database": "sample_db"
}

try:
    conn = mariadb.connect(**config)
    cursor = conn.cursor()

    # データ取得
    select_query = "SELECT id, name, email FROM users"
    cursor.execute(select_query)

    # 取得したデータを表示
    for (id, name, email) in cursor:
        print(f"ID: {id}, 名前: {name}, メール: {email}")

    cursor.close()
    conn.close()
except mariadb.Error as e:
    print(f"エラー発生: {e}")

ポイント:

• cursor.execute(select_query) でSQLを実行し、cursor オブジェクトからデータを取得します。
• for ループを使ってデータを1件ずつ処理できます。

データの更新（UPDATE）

SQLによるデータ更新

UPDATE users SET name = 'Alice Smith' WHERE email = 'alice@example.com';

Pythonでデータを更新する

import mariadb

config = {
    "host": "localhost",
    "user": "root",
    "password": "password",
    "database": "sample_db"
}

try:
    conn = mariadb.connect(**config)
    cursor = conn.cursor()

    # データの更新
    update_query = "UPDATE users SET name = ? WHERE email = ?"
    data = ("Alice Smith", "alice@example.com")
    cursor.execute(update_query, data)

    # 変更を保存
    conn.commit()
    print("データを更新しました！")

    cursor.close()
    conn.close()
except mariadb.Error as e:
    print(f"エラー発生: {e}")

データの削除（DELETE）

SQLによるデータ削除

DELETE FROM users WHERE email = 'alice@example.com';

Pythonでデータを削除する

import mariadb

config = {
    "host": "localhost",
    "user": "root",
    "password": "password",
    "database": "sample_db"
}

try:
    conn = mariadb.connect(**config)
    cursor = conn.cursor()

    # データの削除
    delete_query = "DELETE FROM users WHERE email = ?"
    data = ("alice@example.com",)
    cursor.execute(delete_query, data)

    # 変更を保存
    conn.commit()
    print("データを削除しました！")

    cursor.close()
    conn.close()
except mariadb.Error as e:
    print(f"エラー発生: {e}")

まとめ

• データの追加（INSERT）
• データの取得（SELECT）
• データの更新（UPDATE）
• データの削除（DELETE）

6. トランザクションとロールバック（データ整合性の確保）

トランザクションとは？

トランザクションの特徴

• ACID特性
• Atomicity（原子性） ：処理はすべて完了するか、全く行われないかのどちらかである。
• Consistency（一貫性） ：データは整合性を維持する。
• Isolation（独立性） ：同時に実行されるトランザクションは互いに影響を与えない。
• Durability（耐久性） ：処理が完了したら、その変更は永続的に保存される。

トランザクションの基本操作（COMMITとROLLBACK）

Pythonでトランザクションを使う

複数のデータ操作を1つのトランザクションで管理

import mariadb

config = {
    "host": "localhost",
    "user": "root",
    "password": "password",
    "database": "sample_db"
}

try:
    conn = mariadb.connect(**config)
    cursor = conn.cursor()

    # トランザクション開始
    conn.start_transaction()

    # データの追加
    cursor.execute("INSERT INTO users (name, email) VALUES (?, ?)", ("Bob", "bob@example.com"))
    cursor.execute("INSERT INTO users (name, email) VALUES (?, ?)", ("Charlie", "charlie@example.com"))

    # すべての処理が成功したらコミット（確定）
    conn.commit()
    print("データを正常に追加しました。")

    cursor.close()
    conn.close()
except mariadb.Error as e:
    print(f"エラー発生: {e}")
    conn.rollback()  # エラーが発生した場合はロールバック（元に戻す）

ポイント

• conn.start_transaction() でトランザクションを開始。
• conn.commit() で変更を確定（確定後は元に戻せない）。
• エラーが発生した場合、conn.rollback() でデータの変更を取り消し、元の状態に戻す。

トランザクションを活用したエラーハンドリング

エラーハンドリング付きのトランザクション管理

import mariadb

config = {
    "host": "localhost",
    "user": "root",
    "password": "password",
    "database": "sample_db"
}

try:
    conn = mariadb.connect(**config)
    cursor = conn.cursor()

    # トランザクション開始
    conn.start_transaction()

    try:
        # データの追加（1件目は成功）
        cursor.execute("INSERT INTO users (name, email) VALUES (?, ?)", ("Dave", "dave@example.com"))

        # 2件目の処理でエラー発生（メールアドレスの重複）
        cursor.execute("INSERT INTO users (name, email) VALUES (?, ?)", ("Eve", "dave@example.com"))

        # すべての処理が成功したらコミット
        conn.commit()
        print("データを追加しました。")

    except mariadb.Error as e:
        print(f"データ処理中にエラーが発生: {e}")
        conn.rollback()  # エラー発生時は変更を取り消す
        print("データをロールバックしました。")

    cursor.close()
    conn.close()

except mariadb.Error as e:
    print(f"データベース接続エラー: {e}")

まとめ

• トランザクションの重要性とACID特性
• Pythonで commit() と rollback() を使う方法
• エラーハンドリングを組み合わせたトランザクション管理

7. エラーハンドリング（よくあるエラーと対策）

Access denied for user（ユーザー認証エラー）

エラー内容

mariadb.OperationalError: Access denied for user 'root'@'localhost' (using password: YES)

発生原因

• ユーザー名またはパスワードが間違っている
• MariaDBのユーザーに適切な権限が設定されていない

解決策

1. MariaDBにログインしてユーザー権限を確認

   mysql -u root -p

2. ユーザーの権限を設定

   GRANT ALL PRIVILEGES ON *.* TO 'root'@'localhost' IDENTIFIED BY 'password' WITH GRANT OPTION;
   FLUSH PRIVILEGES;

3. MariaDBを再起動

   sudo systemctl restart mariadb

Can't connect to MySQL server on 'localhost'（接続エラー）

エラー内容

mariadb.OperationalError: Can't connect to MySQL server on 'localhost' (10061)

発生原因

• MariaDBサーバーが起動していない
• host の設定が誤っている

解決策

1. MariaDBサーバーが動作しているか確認

   sudo systemctl status mariadb

2. サーバーが停止している場合は起動

   sudo systemctl start mariadb

3. サーバーを常に起動するように設定

   sudo systemctl enable mariadb

Unknown database 'sample_db'（データベースが存在しない）

エラー内容

mariadb.ProgrammingError: Unknown database 'sample_db'

発生原因

• 指定したデータベースが存在しない
• データベース名のスペルミス

解決策

1. データベース一覧を確認

   SHOW DATABASES;

2. データベースがない場合は作成

   CREATE DATABASE sample_db;

Table doesn't exist（テーブルが存在しない）

エラー内容

mariadb.ProgrammingError: Table 'sample_db.users' doesn't exist

発生原因

• 指定したテーブルが存在しない
• USE sample_db; でデータベースを選択していない

解決策

1. テーブル一覧を確認

   SHOW TABLES;

2. テーブルがない場合は作成

   CREATE TABLE users (
       id INT AUTO_INCREMENT PRIMARY KEY,
       name VARCHAR(100) NOT NULL,
       email VARCHAR(100) UNIQUE NOT NULL,
       created_at DATETIME DEFAULT CURRENT_TIMESTAMP
   );

Duplicate entry（データの重複エラー）

エラー内容

mariadb.IntegrityError: Duplicate entry 'alice@example.com' for key 'users.email'

発生原因

• email カラムに UNIQUE 制約があるため、同じ値を挿入できない

解決策

• データを挿入する前に、重複チェックを行う
• ON DUPLICATE KEY UPDATE を使用する

Pythonで重複を防ぐコード

try:
    cursor.execute("INSERT INTO users (name, email) VALUES (?, ?)", ("Alice", "alice@example.com"))
    conn.commit()
except mariadb.IntegrityError:
    print("エラー: メールアドレスが既に存在します。")

または ON DUPLICATE KEY UPDATE を使用

INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com')
ON DUPLICATE KEY UPDATE name = 'Alice Updated';

Incorrect number of bindings（パラメータ数の不一致）

エラー内容

mariadb.ProgrammingError: Incorrect number of bindings supplied. The current statement uses 2, and there are 1 supplied.

発生原因

• SQLに必要なパラメータの数と、実際に渡した引数の数が一致していない

解決策

• プレースホルダーの数とデータの数を一致させる

誤ったコード

cursor.execute("INSERT INTO users (name, email) VALUES (?, ?)", ("Alice"))

正しいコード

cursor.execute("INSERT INTO users (name, email) VALUES (?, ?)", ("Alice", "alice@example.com"))

まとめ

• Access denied for user（認証エラー）
• Can't connect to MySQL server（接続エラー）
• Unknown database（データベースが存在しない）
• Table doesn't exist（テーブルが存在しない）
• Duplicate entry（データの重複エラー）
• Incorrect number of bindings（パラメータ数の不一致）

8. まとめ

記事の振り返り

環境の準備

• MariaDBのインストール方法（Windows / Mac / Linux）
• PythonとMariaDBの接続ライブラリ（mariadb）のインストール

MariaDBへの接続

• 基本的なデータベース接続方法
• 環境変数を利用したセキュアな接続
• 接続時に発生するエラーの解決策

データベースとテーブルの作成

• データベースの作成（SQL・Python）
• テーブルの作成とデータ型の選び方
• 既存のテーブルの確認・削除方法

CRUD操作（データの追加・取得・更新・削除）

• Pythonを使ったデータの基本操作
• SQLインジェクション対策としてプレースホルダーを使用
• 適切なエラーハンドリング

トランザクションとロールバック

• トランザクションの重要性（ACID特性）
• エラー発生時にデータを元に戻す方法（ロールバック）
• AutoCommitを無効化して手動でトランザクションを管理

エラーハンドリング（よくあるエラーと対策）

• 認証エラー (Access denied for user)
• 接続エラー (Can't connect to MySQL server)
• データベース・テーブルが存在しないエラー
• データの重複エラー (Duplicate entry)
• デッドロックの発生とリトライ処理の実装

PythonとMariaDBを組み合わせる際のポイント

1. プレースホルダーを活用する

   cursor.execute("INSERT INTO users (name, email) VALUES (?, ?)", ("Alice", "alice@example.com"))

2. 適切なトランザクション管理を行う

• conn.commit() を使って 変更を明示的に確定。
• エラー時に conn.rollback() で データの整合性を保つ。

2. エラーハンドリングをしっかり行う

• try-except を活用し、発生しうるエラーを事前にキャッチ。
• OperationalError や IntegrityError など、エラーごとの対応策を準備。

2. パフォーマンスを考慮する

• バルクインサート（複数レコードを一括で追加）
• 適切なインデックス設定（検索速度を向上）

さらなる学習のためのリソース

公式ドキュメント

• MariaDB公式ドキュメント

関連する学習コンテンツ

• SQLの基礎（W3Schools）
• Pythonによるデータベース操作（Real Python）

おすすめの書籍

• 「SQL 第2版 ゼロからはじめるデータベース操作」 – SQLの基礎をしっかり学べる
• 「Effective Python ―Pythonプログラムを改良する90項目」 – Pythonのベストプラクティスを学べる

まとめ