Apricot データベース

— y2sunlight 2020-07-29

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— データベース名 (初期設定値は sqlite )
caching — キャッシングの有無
logging — ロギングの有無
connections — データベース毎の接続を設定します
initial_data — テーブル毎の初期データを設定します

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

connections

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

connection_string — 接続文字列
db_file — データベースファイルのパス (初期設定値は var/db/apricot.sqlite)
username — データベースのユーザ名
password — ユーザのパスワード
driver_options — データベースドライバー毎のオプション
check_tables — アプリケーションで使用するテーブルの存在を確認するSQL文
initial_statements — 接続直後に実行する初期化SQL文

connection_string は必須です。db_file は SQLite のようなファイル共有型のデータベースの場合に必要で、username と password は MySQL のようなクライアント-サーバ型のデータベースの場合に必要になります。connection_string と driver_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を記述します(複数指定可)
rows — 初期データとして挿入するカラム毎のデータ(複数指定可)

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

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

Idiormのセットアップ

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

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

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

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

データベースへの接続

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

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

設定値 db_file で指定されいるファイルが存在しなかった時
設定値 check_tables で指定されいるクエリー結果が空の時

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

初期データの自動作成

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

データベースの構築

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

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

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

userテーブル

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

カラム名	型		主Key	属性	説明
カラム名	SQLite	MySQL	主Key	属性	説明
id	integer	int	●	autoincrement	ID
account	text	VARCHAR(255)		unique not null	アカウント
password	text	VARCHAR(255)		not null	パスワード
email	text	VARCHAR(255)			Eメールアドレス
note	text	text			備考
remember_token	text	VARCHAR(255)			自動ログイン用
created_at	text	datetime		not null	作成日
updated_at	text	datetime		not null	更新日
version_no	integer	int		default 0 not null	バージョンNo

account と password カラムは、ログイン認証で使用されます。
remember_token は自動ログイン用の認証トークンとして使用されます。
新しくレコードが挿入される時、created_atとupdated_at が設定されます。
レコードが変更される時、created_atとversion_no が設定されます。
version_no はレコードのバージョンを表し、楽観的ロックで使用されます。

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

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

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):array	SQLファイルを読み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
);

SQLの文法及び使用できる関数などは使用しているデーターベース( 上例では SQLite )に依存します。
行コメント( -- Comment )とブロックコメント( /* Comment */ )の両方が使用できます。
文はセミコロン( ; )で区切って複数入力できます。
連続する空白( TAB, Space, 改行文字 )は1つの空白と同じにみなされます。

目次