目次

Apricot データベース

y2sunlight 2020-07-29

Apricot ドキュメント に戻る

目次


ORMの利用

Apricotでは、ORマッパーにIdiormを使用します。詳しい使い方やメソッドについてはIdiormのマニュアルを参照して下さい。

Idiorm の典型的な使用例を示します:

$user = ORM::for_table('user')->find_many();

これは、userテーブルから全件を検索する例です。このように、IdiormではORMクラスの静的メソッドの呼び出しを使ってコーディングします。これはApricotのシングルトンと同じ方法で、実際にORMクラスもシングルトンです。


Idiormの設定ファイル

以下はApricotが提供している初期のIdiormの設定ファイル( idiorm.setting.php )です。

/your-project/config/setting

idiorm.setting.php
<?php
/**
 * This file contains Idiorm settings.
 */
$now = date("Y-m-d H:i:s");
return
[
    'database'=>'sqlite',
    'caching' => true,
    'logging' => true,
    'connections' =>
    [
        'sqlite' => [
            'connection_string' => 'sqlite:'.var_dir('db/apricot.sqlite'),
            'db_file' => var_dir('db/apricot.sqlite'),
        ],
        'mysql' => [
            'connection_string' => 'mysql:host=localhost;port=3306;dbname=apricotdb',
            'username' => 'apricot',
            'password' => 'password',
            'driver_options' => [PDO::MYSQL_ATTR_INIT_COMMAND => 'set names utf8'],
            'check_tables' => 'show tables like \'user\'',
            'initial_statements'=> [
                'set names utf8',
            ],
        ],
    ],
    'initial_data' => [
        'user'=> [
            'exec:sqlite' =>[
                'delete from sqlite_sequence where name=\'user\'',
            ],
            'exec:mysql' =>[
                'alter table user auto_increment = 1;',
            ],
            'rows' => [
                [
                    'account' =>'root',
                    'password' =>password_hash('', PASSWORD_DEFAULT),
                    'email' =>'root@sample.com',
                    'note' =>'Initial User',
                    'created_at' => $now,
                    'updated_at' => $now,
                ],
            ],
        ],
    ],
];

database は任意の名前が指定できますが、connections の中で使用する名前と一致している必要があります。connectionsには、複数のデータベースの接続を含める事ができますが、実際に使用されるのは database で指定されたものだけです。

connections

各データベースの設定値には以下の項目が含まれます。

connection_string は必須です。db_file は SQLite のようなファイル共有型のデータベースの場合に必要で、usernamepassword は MySQL のようなクライアント-サーバ型のデータベースの場合に必要になります。connection_stringdriver_options についてはを PHPのPDO driver-specific documentation 参照して下さい。

接続設定及び接続文字列の詳細は以下を参照して下さい:
https://idiorm.readthedocs.io/en/latest/configuration.html#id1

check_tables はオプションで、アプリケーションで使用するテーブルの存在を調べるSQLクエリ文を設定します。詳しくは次項のIdiormのセットアップを参照して下さい。

initial_statements はオプションで、データベースとの接続直後に実行するSQL文を設定します。このSQL文は複数指定することができます。

initial_data

テーブル毎に初期データが設定できます。各テーブルの設定値は以下の通りです。

exec には初期データを挿入する前に実行されるSQL文を設定する事ができます。exec には上例のように接尾語として :{データベース名} を付加する事ができます。SQL文がデータベースの種類の依存する場合に使用して下さい。

初期データについては、次項のIdiormのセットアップも参照して下さい。


Idiormのセットアップ

Idiormには以下のセットアップファイルが存在します。セットアップの動作をカスタマイズした場合は、このファイルを変更して下さい。

/your-project/config/setup/idiorm.setup.php

このセットアップファイルでは以下の事をおこないます:

  1. データベースへの接続 — ORMオブジェクトの初期化
  2. テーブルの自動作成 — 新しくデータベースを作った時
  3. 初期データの自動作成 — テーブルが空の時


データベースへの接続

Idiormの設定ファイル( idiorm.setting.php ) に従ってデータベースへの接続を行います。db_file が設定されている場合は、それが設置されるディレクトリを自動作成します。そして、IdiormのORMオブジェクトを初期化し、設定に応じてキャッシングを開始します。ロギングが有効な場合は、Apricotのログイン設定に従ってINFOレベルのログを出力します。


テーブルの自動作成

新しくデータベースを作った時に、テーブルを自動作成する事ができます。自動作成で使用するSQL文はファイル( create.sql )の中に保存し、各データベース毎に以下のディレクトリーに配置して下さい。この時、データベースを表すディレクトリー名は設定値である database と同じにします。

your-project
 |
 ├── assets
 |    ├── sql
 |    |    |
 |    |    ├── sqlite  [SQLite用]
 |    |    |    |
 |    |    |    └─ create.sql
 |    |    |
 |    |    ├── mysql   [MySQL用]
 |    |    |    |
 |    |    |    └─ create.sql

テーブル自動作成のトリガーは以下の2つです。この何れかに該当する場合に限り、create.sql が実行されます。create.sql の書式については SQLファイル を参照して下さい。

一般的に、db_file は SQLite のようなファイル共有型のデータベースの場合に使用し、check_tables は MySQL のようなクライアント-サーバ型のデータベースの場合に使用します。


初期データの自動作成

設定ファイルの initial_data に設定されているテーブルが空の場合、そのテーブルに初期データを自動的に挿入します。これは、テーブル作成の直後だけでなく、全てのレコードが消されテーブルが空になった場合も含まれることに注意して下さい。


データベースの構築

ここでは、create.sql ファイルを使用したデータベースの構築方法について説明しますが、実際のデータベースの構築にあたっては、アプリケーションに応じた戦略を検討して下さい。

Apricotのスケルトンには、ユーザテーブルが含まれています。ユーザテーブルはログイン認証で使用される基本的なテーブルで、Aproctに初期実装されているアプリケーションでは、このテーブルをメンテナンス(新規作成、変更、削除)する機能が実装されています。

Apricotを最初に起動したとき、ユーザテーブルは自動的に作成され、初期データがロードされるように予め設定されています。自動作成するテーブルのSQL文は create.sql ファイルに格納します。必要に応じて、新しいテーブルを追加するようにして下さい。


userテーブル

以下はuserテーブルの定義です。Apricotのスケルトンで初期設定されているデータベースはSQLiteです。

カラム名 主Key 属性 説明
SQLite MySQL
idintegerintautoincrementID
accounttextVARCHAR(255) unique not nullアカウント
passwordtextVARCHAR(255) not nullパスワード
emailtextVARCHAR(255) Eメールアドレス
notetexttext 備考
remember_tokentextVARCHAR(255) 自動ログイン用
created_attextdatetime not null作成日
updated_attextdatetime not null更新日
version_nointegerint default 0 not nullバージョンNo

ユーザテーブルには必要に応じて新しいカラムを追加することができます。

Apricotのスケルトンでは、アプリケーションが使用する全てのテーブルで created_at、updated_at、version_no の3つカラムが存在することを前提しています。この前提を変更する場合は、モデルのベースクラスを変更して下さい。


Raw SQL

アプリケーションでは、テーブルを作成したり削除するような生のSQLを直接実行することもあります。このような為に、IdiromではDDL用のSQLを実行するメソッドして raw_execute()get_db() が提供されています。

以下は raw_execute() の例です。このメソッドは成否を返します。

$successful = ORM::raw_execute('DROP TABLE user');

get_db() はPHPのPDOオブジェクトを返します。上の例をget_db()を使用して行うと以下のようになります。PDO の exec() メソッドは作用した行数または失敗した場合にfalseを返します。

$result = ORM::get_db()->exec('DROP TABLE user');


SQLファイル

テーブルの自動作成で使用される create.sql ファイルは、以下のヘルパー関数によってSQL文の配列として読み込まれます。

関数機能
file_get_sql(string $filename):arraySQLファイルを読みSQL文の配列を返す

file_get_sql() 関数 はアプリケーションの中で任意のSQLファイルに使用できます。但し、SQLファイルの保存先は create.sql ファイルと同じ場所を推奨します。

Idiormのセットアップコードでは、file_get_sql() 関数を使用して以下のように create.sql を読み込んでSQL文を実行しています。

$sql_text = file_get_sql(assets_dir("sql/{$database}/create.sql"));
if (!empty($sql_text))
{
    foreach($sql_text as $sql)
    {
        ORM::get_db()->exec($sql);
    }
}


SQLファイルの形式について

以下に、Apricotのスケルトンで提供されているSQLite用のSQLファイルを示します。

/your-project/assets/sql/sqlite

create.sql
/*
 * User Table
 */
CREATE TABLE IF NOT EXISTS USER
(
    id INTEGER PRIMARY KEY autoincrement,
    account text UNIQUE NOT NULL,
    password text NOT NULL,
    email text,
    note text,
    remember_token text,
    created_at text NOT NULL,
    updated_at text NOT NULL,
    version_no INTEGER DEFAULT 0 NOT NULL
);