IDbAdvanced

Interface for database engines. To make a database usable in Artaengine two classes must be created, one must implement IDbAbstract and one IDbAdvanced.
Source
IDbAdvanced.php
Implementations
MySqliAdvanced , PostgreSqlAdvanced

Methods

__construct

IDbAdvanced $obj = new IDbAdvanced(IDbAbstract | array param)

Connect to a database. Either connection configs or an "DBIAbstract" instance must be passed. If an instance of "DBIAbstract" is passed a new database connection will not be made but the old connection related to the instance will be set for the new "DBIAdvanced" object.

Arguments

    param (IDbAbstract | array)
    An instance of "IDbAbstract" or a connection configs array
    {
        string server   : localhost database server address,
        string port     : 5432 database server port,
        string dbname   : database name,
        string user     : database user-name,
        string password : database password,
        string advanced : false
            false=create an IDbAbstract instance
            true=create an IDbAdvanced instance,
    }
    

Returns

void

Throws

alterTable

string $obj->alterTable(
    string table,
    array cols=null,
    array constraints=null,
    string | array extra=null,
    bool exe=true
)

Alter table.

Arguments

    table (string)
    Table name
    cols=null (array)
    Column definitions
    {
        array add : {
            array column-name : {
                bool   key       : false true=column is the primary key,
                const  type      : Artaengine data type constant,
                int    len       : 255   string-column max length,
                bool   unsigned  : false numeric-column is unsigned,
                bool   required  : false
                    true=column can't be null (or use nullable),
                bool   nullable  : true
                    false=column can't be null (or use required),
                string default   : false column default value,
                bool   unique    : false true=column values must be unique,
                string check     : check constraint expression,
                array  reference : column is a foreign key {
                    string table : reference table-name,
                    string col   : reference column-name,
                }
            }
        }
        array alter : {
            array column-name : {
                const  type     : Artaengine data type constant,
                int    len      : string-column max length,
                bool   unsigned : numeric-column is unsigned,
                bool   required :
                    true=column can't be null (or use nullable),
                bool   nullable :
                    false=column can't be null (or use required),
                string default  : column default value,
            }
        }
        array drop : [
            columns-to-drop,
        ]
        array rename : {
            string column-name : new-column-name,
            int    0 : new-table-name,
        }
    }
    
    constraints=null (array)
    Constraint definitions
    {
        array add : [
            {
                string type : "PRIMARY KEY",
                string name : constraint name,
                array  cols : [
                    "column-name",
                ]
            },
    
            {
                string type : "UNIQUE",
                string name : constraint name,
                array  cols : [
                    "column-name",
                ]
            },
    
            {
                string type     : "CHECK",
                string name     : constraint name,
                string col_name : column name,
                string exp      : check constraint expression,
            },
    
            {
                string type      : "FOREIGN KEY",
                string name      : constraint name,
                bool   delete    : false true=cascade on delete,
                bool   update    : false true=cascade on update,
                array  reference : {
                    string table : reference table-name,
                    array  cols  : {
                        string column-name : reference column-name,
                    },
                }
            },
    
            {
                string type      : "FOREIGN KEY",
                string name      : constraint name,
                bool   delete    : false true=cascade on delete,
                bool   update    : false true=cascade on update,
                string table     : reference table-name,
                array  reference : {
                    string column-name : reference column-name,
                }
            },
        ]
        array alter : {
            string constraint-name : {
                new-constraint-definitions
            },
        }
        array drop : [
            columns-to-drop,
        ]
    }
    
    extra=null (string | array)
    Extra DBMS specific table parameters
    exe=true (bool)
    true=execute the ALTER TABLE on database

Returns

string
ALTER TABLE SQL

Throws

artaType2DbType

array $obj->artaType2DbType()

Get a dictionary of Artaengine data types mapped to database data types.

Returns

array
{T::TYPE_CONST: db-type-string,}

constraintName

string $obj->constraintName(string prefix, string table, string name)

Make a valid database constraint name.

Arguments

    prefix (string)
    Such as 'PK', 'FK', 'CK', etc.
    table (string)
    Table name
    name (string)
    Constraint main name

Returns

string
Constraint name

createTable

string $obj->createTable(
    string table,
    array cols=null,
    array constraints=null,
    string | array extra=null,
    bool exe=true
)

Create table.

Arguments

    table (string)
    Table name
    cols=null (array)
    Column definitions
    {
        string column-name : {
            bool   key       : false true=column is the primary key,
            const  type      : Artaengine data type constant,
            int    len       : 255   string-column max length,
            bool   unsigned  : false numeric-column is unsigned,
            bool   required  : false
                true=column can't be null (or use nullable),
            bool   nullable  : true
                false=column can't be null (or use required),
            string default   : false column default value,
            bool   unique    : false true=column values must be unique,
            string check     : check constraint expression,
            array  reference : column is a foreign key {
                string table : reference table-name,
                string col   : reference column-name,
            }
        }
    }
    
    constraints=null (array)
    Constraint definitions
    [
        {
            string type : "PRIMARY KEY",
            string name : constraint name,
            array  cols : [
                "column-name",
            ]
        },
    
        {
            string type : "UNIQUE",
            string name : constraint name,
            array  cols : [
                "column-name",
            ]
        },
    
        {
            string type     : "CHECK",
            string name     : constraint name,
            string col_name : column name,
            string exp      : check constraint expression,
        },
    
        {
            string type      : "FOREIGN KEY",
            string name      : constraint name,
            bool   delete    : false true=cascade on delete,
            bool   update    : false true=cascade on update,
            array  reference : {
                string table : reference table-name,
                array  cols  : {
                    string column-name : reference column-name,
                },
            }
        },
    
        {
            string type      : "FOREIGN KEY",
            string name      : constraint name,
            bool   delete    : false true=cascade on delete,
            bool   update    : false true=cascade on update,
            string table     : reference table-name,
            array  reference : {
                string column-name : reference column-name,
            }
        },
    ]
    
    extra=null (string | array)
    Extra DBMS specific table parameters
    exe=true (bool)
    true=execute the CREATE TABLE on database

Returns

string
CREATE TABLE SQL

Throws

dbType2ArtaType

array $obj->dbType2ArtaType()

Get a dictionary of database data types mapped to Artaengine data types.

Returns

array
{db-type-string: T::TYPE_CONST,}

getMetaConstraints

array $obj->getMetaConstraints(string table=null, string constraint=null)

Get table constraints meta data.

Arguments

    table=null (string)
    Table name, null=get all constraints that exist in the database
    constraint=null (string)
    Constraint name to get info about, null=get info about all constraints

Returns

array
table=null then [{def},] or table!=null then {constraint-name: {def},} if constraint!=null then {def} def=
{
    string name  : constraint name,
    string type  : constraint type,
    string table : table name,
    array  cols  : [
        list of table columns affected by the constraint
    ],
    string delete : action on delete,
    string update : action on update,
    array  reference : {
        string table : reference table name,
        array  cols  : [
            list of columns referenced by the constraint
        ],
    },
    string match              : only for foreign keys,
    string is_deferrable      : only for foreign keys,
    string initially_deferred : only for foreign keys,
    string defer              : only for foreign keys,
    string definition         : only for check constraints,
}

getMetaIndexes

array $obj->getMetaIndexes(string table)

Get table indexes meta data (Experimental - subject to change).

Arguments

    table (string)
    table name, null=return all

Returns

array
array {index-name: {meta},} meta=
{
    string name       : index name,
    string definition : index definition,
}

getMetaTable

array $obj->getMetaTable(string table=null, int shape=2)

Get metadata of tables.

Arguments

    table=null (string)
    Table name, null=return a list of database tables
    shape=2 (int)
    1=return column definitions only, 2=return column definitions and constrain statuses, 3=return column definitions and constraint definitions

Returns

array
if table=null {table-name: table-name,} else {col-name: {meta},} where meta is: [DbAdvanced.getMetaTable]

getMetaTableStatus

array $obj->getMetaTableStatus(string table=null)

Get information about a table. The result is DBMS specific.

Arguments

    table=null (string)
    Table name

Returns

array
[@PostgeSql.getMetaTableStatus]

getMetaViews

array $obj->getMetaViews(string view=null, bool thin=false)

Get database view list or view(s) meta data.

Arguments

    view=null (string)
    View name, null=return for all views
    thin=false (bool)
    true=return only a list of view names

Returns

array
if thin=true return {view-name: view-name,} if view name is specified return {meta} if view name is not specified return {view-name: {meta},} meta=
{
    string schema     : database schema,
    string name       : view name,
    string owner      : database user,
    string definition : view definition,
    array cols        : [
        list of view columns
    ],
}

getTablePrimaryKeys

array $obj->getTablePrimaryKeys(string table)

Get table primary keys.

Arguments

    table (string)
    Table name

Returns

array
Array of primary key column names {pk-col-name: pk-col-name,}

info

array $obj->info()

Get info about the dbms and class.

Since
Artaengine 1.1.0

Returns

array
Info array
{
    string server     : PostgreSQL server version,
    string client     : PostgreSQL client version,
    string class      : "Arta.PostgreSqlAdvanced",
    string version    : Class version,
    string extension  : "postgresql",
    string dbms       : "PostgreSQL",
    array  connection : {
        string server   : database server address,
        string port     : database server port,
        string dbname   : database name,
        string user     : database user-name,
        string password : database password,
        string advanced :
            false=create an IDbAbstract instance
            true=create an IDbAdvanced instance,
    },
}

realType

const|array $obj->realType(const type)

Get the database data type for virtual data types such as PASSWORD/EMAIL, etc.

Arguments

    type (const)
    T::TYPE_CONST (An Artaengine data type)

Returns

const|array
Artaengine data type | [artaengine-data-type, len]

toType

string $obj->toType(const type, int | array length=null, bool unsigned=false)

Returns the database type definition of a T::TYPE_CONST (Artaengine data type).

Arguments

    type (const)
    T::TYPE_CONST (Artaengine data type)
    length=null (int | array)
    Max length or [min-length, max-length]
    unsigned=false (bool)
    Signed or Unsigned (if supported by database)

Returns

string
Database column type definition

truncate

string $obj->truncate(bool delete=false)

Get truncate/delete SQL string for all database tables.

Arguments

    delete=false (bool)
    bool false=TRUNCATE TABLE, true=DELETE FROM

Returns

string
TRUNCATE/DELETE SQL