====== Apricot データベース ======
 --- //[[http://www.y2sunlight.com|y2sunlight]] 2020-07-29//

[[apricot:usage:ja|Apricot ドキュメント に戻る]]

目次

  * [[apricot:usage:ja:features|Apricot 特徴と概要]]
  * [[apricot:usage:ja:config|Apricot 配置と構成]]
  * [[apricot:usage:ja:errors-logging|Apricot ログとエラー処理]]
  * [[apricot:usage:ja:http|Apricot リクエストとレスポンス]]
  * [[apricot:usage:ja:frontend|Apricot フロントエンド]]
  * Apricot データベース
  * [[apricot:usage:ja:model|Apricot モデルとサービス]]
  * [[apricot:usage:ja:middleware|Apricot ミドルウェア]]
  * [[apricot:usage:ja:controller|Apricot コントローラ]]
  * [[apricot:usage:ja:validation|Apricot バリデーション]]
  * [[apricot:usage:ja:provider|Apricot サービスプロバイダー]]
  * [[apricot:usage:ja:authentication|Apricot ユーザ認証]]
  * [[apricot:usage:ja:utility|Apricot ユーティリティ]]

----

===== ORMの利用 =====

Apricotでは、ORマッパーに[[basic-library:idiorm:1.5|Idiorm]]を使用します。詳しい使い方やメソッドについてはIdiormの[[https://idiorm.readthedocs.io/en/latest/|マニュアル]]を参照して下さい。

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

<code php>
$user = ORM::for_table('user')->find_many();
</code>

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

\\

===== Idiormの設定ファイル =====

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

{{fa>folder-open-o}} ** /your-project/config/setting **
<code php 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,
                ],
            ],
        ],
    ],
];
</code>

  * 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の[[https://www.php.net/manual/en/pdo.drivers.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には以下のセットアップファイルが存在します。セットアップの動作をカスタマイズした場合は、このファイルを変更して下さい。

<code>
/your-project/config/setup/idiorm.setup.php
</code>

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

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

\\

==== データベースへの接続 ====

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

\\

==== テーブルの自動作成 ====

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

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


テーブル自動作成のトリガーは以下の２つです。この何れかに該当する場合に限り、''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  ^:::^:::^:::^
|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()'' の例です。このメソッドは成否を返します。

<code php>
$successful = ORM::raw_execute('DROP TABLE user');
</code>

''get_db()'' はPHPの[[https://www.php.net/manual/en/class.pdo.php|PDOオブジェクト]]を返します。上の例を''get_db()''を使用して行うと以下のようになります。PDO の ''exec()'' メソッドは作用した行数または失敗した場合にfalseを返します。

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

\\

==== 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文を実行しています。

<code php>
$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);
    }
}
</code>

\\

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

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

{{fa>folder-open-o}} ** /your-project/assets/sql/sqlite **
<code sql 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
);
</code>

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

\\