=head1 NAME

OpenResty::Spec::MetaModel - Metamodel for OpenResty backends

=head1 VERSION

This document describes OpenResty 0.5.1's meta model, version 0.007.

=head1 DESCRIPTION

The metamodel in OpenResty is a set of internal database schemas or tables for
storing meta information regarding the user data. They're usually invisible
to the outside users and their names are carefully chosen so as to prevent
potential naming conflicts with users' objects.

=head1 Global metamodel

The global metamodel stores the global (system-wide) information about the
OpenResty users.

It sits in a separate PostgreSQL schema named C<_global>. It owns the following
meta tables:

=over

=item _general

The definition of the C<_general> table is

    create table _general (
        version varchar(10),
        captcha_key char(16)
    )

Usually it stores the version and other general information of
the global metamodel itself. Note that the
version of the metamodel is independent of the version number of the whole
OpenResty server implementation. For instance, the OpenResty 0.1.8
uses metamodel 0.001 while the versions earlier does not have a versioned
metamodel.

This table usually has only one row. But it's also fine to keep track of all the version history. The largest version number will be considered the current version of the metamodel in the I<current> user schema.

The C<captcha_key> column stores the secret key used in captcha generation,
whose value must be exactly 16 bytes long and contains only characters in
C<[0-9a-zA-Z]>.

=item _accounts

The C<_accounts> table stores the list of all the available OpenResty accounts
in the whole system. It has the following definition:

    create table _accounts (
        id serial primary key,
        name text unique not null,
    )

The C<name> column specifies the name of the account.

=back

=head1 Local metamodel

Each OpenResty account registered by an outside user has a PostgreSQL schema
for storing its models, views, roles, actions, and other user objects. Such
schema has the same name as the account name. For instance, account C<carrie>
has a corresponding database schema (or namespace) named C<carrie>. The
C<carrie> schema has the following meta tables:

=over

=item _general

The definition of the C<_general> table is

    create table _general (
        version varchar(10),
        created timestamp (0) with time zone default now()
    )

The C<version> column keeps the metamodel version number for the current
account while the C<created> column records its creation time.

=item _roles

The C<_roles> table stores the meta information of the OpenResty Role objects.

    create table _roles (
        id serial primary key,
        name text unique not null,
        login text not null,
        password text,
        description text not null,
        created timestamp(0) with time zone default now()
    );

The C<login> column specifies the login method used by the role. Allowed
values are C<'password'>, C<'anonymous'>, and C<'captcha'>.

The C<password> column must be not null when the C<login> column has the
value of C<'password'>. Its values should be null otherwise.

=item _access

The C<_access> table stores the information of the access rules
associated with the OpenResty Role objects.

    create table _access (
        id serial primary key,
        role text not null,
        method varchar(10) not null,
        prefix text not null,
        segments smallint,
        prohibiting boolean default false not null
    );

The C<role> column stores the name of the role which owns the current rule.

Each access rule has two components, HTTP method and the (abbreviated) URL,
which are saved in the columns C<method>, C<prefix>, and C<segments>, respectively. An example
is that C<method> has a value of C<'GET'> and C<url> has a value of
C<'/=/model/~/~/~'>.

=item _models

The C<_models> table stores the meta information regarding the OpenResty
models.

The definition of _models is

    create table _models (
        id serial primary key,
        name text unique not null,
        description text,
        created timestamp(0) with time zone default now()
    );

The C<name> column stores the names of user models. Every user model is
represented by a physical PostgreSQL table under the same schema and the
leading character of its name must be case-sensitive letters. Table names
leading by an underscore are preserved for meta tables.

The C<description> column stores users' textual description for their models.

Neither C<name> nor C<description> can be null.

=item _columns

The C<_columns> table stores the meta information regarding OpenResty models'
columns.

    create table _columns (
        id serial primary key,
        name text not null,
        model text not null,
        label text not null,
        type text not null,
        "default" text,
        indexed text,
        unique(model, name)
    );

The C<name> column keeps the names of user models' columns and the C<model>
column stores the names of the corresponding models.

The C<lable> column stores the textual label provided by the user who created
the column and types of the model columns are stored in the C<type> column.

None of the columns above but C<default> and C<indexed> can be null
and in addition, the combination of the columns C<model> and C<name> should
be unique.

User columns have default values and the corresponding JSON representation
is stored in the C<default> column. Note that the values for
C<default> are JSON literals, for instance, C<"32">, C<["now()"]>,
and etc.

The C<indexed> column stores the index method applied to the current user
column if any; null otherwise. Possible values are 'fulltext', 'btree',
'rtree', 'gist', and 'hash'.

=item _views

The C<_views> table stores the information of the OpenResty View objects.

    create table _views (
        id serial primary key,
        description text,
        name text unique not null,
        definition text not null,
        created timestamp(0) with time zone default now()
    );

All of the columns have similar meaning as the C<_model> table
except that the C<definition> column stores the minisql string
defining the functionality of the view.

=item _actions

The C<_actions> table stores the information of the OpenResty Action objects.

    create table _actions (
        id serial primary key,
        name text unique not null,
        definition text not null,
        description text,
        compiled text,
        created timestamp(0) with time zone default now()
    );

    create table _action_params (
        id serial primary key,
        name text not null,
        type text not null,
        label text,
        default_value text,
        used bool not null,
        action_id integer references _actions(id) on delete cascade
    );

Most of the columns are similar to those in the C<_view> table except that
it takes an auxiliary table C<_action_params>.

[TODO: add the C<confirmed_by> column to specify the confirmation
method used to fire the action. Allowed values for this column are "email", "cellphone", and "captcha".]

=item _feeds

The C<_feeds> table stores the meta information for the OpenResty Feed objects.

    create table _feeds (
        id serial primary key,
        name text unique not null,
        description text not null,
        view text not null,
        title text not null,
        link text not null,
        logo text,
        copyright text,
        language text,
        author text,
        created timestamp (0) with time zone default now()
    );

The C<view> argument specifies the OpenResty view name from which the RSS/Atom feed is generated.

The C<title>, C<link>, C<logo>, C<copyright>, and C<author> are properties of the web site the current feed is referred to.

=back

=head1 AUTHOR

agentzh C<< <agentzh@yahoo.cn> >>

=head1 COPYRIGHT AND LICENSE

Copyright (c)  2008  Yahoo! China EEEE Works, Alibaba Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts. A copy of the license can be found at

L<http://www.gnu.org/licenses/fdl.html>

=head1 SEE ALSO

L<OpenResty::Spec::Upgrading>, L<openresty>, L<OpenResty>, L<OpenResty::Spec::Overview>.

