xdrm-framework/notice/db-schema/1.0.md

module: db-schema
version: 1.0
requires:
  - database: 2.0

Links

[1] User guide

• 1 - Overview
  • (1) introduction & features
• 2 - Usage
  • (1) setup
  • (2) php requirements
  • (3) from php
• 3 - Configuration
  • (1) Syntax
  • (2) Field types

[2]. Advanced guide

User guide

1 - Overview

(1) Introduction & features

The db-schema package (v1.0) allows you to easily create a database (mysql-like) from a json file. It allows you to have a human-readable representation of your database that you can recover automatically.

The aim of this package is to make your life easier working with database creation and management. The only things you have to do is to write your JSON configuration, the package will do the rest.

Features:

• Manage multiple databases (according to the database-driver)
• Push a json configuration to a database (mysql)
• (todo) Pull a database schema to a json file

2 - Usage

(1) Setup

In order to make the package work, you have to :

1. Edit the database-driver configuration file according to your credentials
2. Write your database configuration (cf. configuration))

(2) Php requirements

1) include the autoloader file

<?php require_once '../autoloader.php';

2) load useful classes

use \dbschema\core\dBuilder;

(3) From php

1) Load configuration schema

// loads the default schema
dBuilder::parse();

// loads the custom schema
dBuilder::parse('custom');

2) Push the loaded schema to the database

// push to the default database
dBuilder::push();

// push a custom database
dBuilder::push('custom-db');

Note: In the first line, it will use the database-driver default configuration. In the second line, it will use the database-driver custom configuration.

3 - configuration

(1) Syntax

{

	"{table_name}": {

		"{field_name}": {
			"type":           "{field_type}",
			"null":           "{null_allowed}",
			"primary":        "{is_primary}",
			"unique":         "{is_unique}",
			"auto_increment": "{auto_inc}",
			"default":        "{default_value}",
		},

		// the '#' tells it is a foreign key
		"#{field_name}": {
			"ref":            [ "{ref_table}", "{ref_field}" ],
			"type":           "{field_type}",
			"null":           "{null_allowed}",
			"primary":        "{is_primary}",
			"unique":         "{is_unique}",
			"auto_increment": "{auto_inc}",
			"default":        "{default_value}"
		}

	}
}

variable	description	exemple
{table_name}	table name	"user"
{field_name}	column name in table	"username"
{field_type}	field type/format	"int"
{null_allowed}	boolean if false, NOT NULL	false
{is_primary}	boolean if true, PRIMARY KEY	true
{is_unique}	boolean if true, UNIQUE	true
{auto_inc}	boolean if true, AUTO_INCREMENT	true
{default_value}	any single variable, default value	12.4
{ref_table}	foreign key reference table	"user"
{ref_field}	foreign key reference field	"id_user"

(2) Field types

Default types

Type	Example	Description
bool	true	Boolean (true or false)
boolean	true	Boolean (true or false)
bit	true	Boolean (true or false)
char	a	Any character
int	10	Positive integer number between 0 and 2147483647
integer	10	Positive integer number between 0 and 2147483647
number	10	Positive integer number between 0 and 2147483647
float	-10.2, 23.4	Any real number
double	-10.2, 23.4	Any real number
decimal	-10.2, 23.4	Any real number
real	-10.2, 23.4	Any real number
time	12:23,32	Time
date	12-08-2017	Date
datetime	12-08-2017 12:23,32	Datetime
timestamp	1504954629	Timestamp

Complex types

Type	Description
varchar(a)	Text of a maximum length of a
double(a,b)	Decimal number with a size of a and a decimal size of b
float(a,b)	Decimal number with a size of a and a decimal size of b
decimal(a,b)	Decimal number with a size of a and a decimal size of b
real(a,b)	Decimal number with a size of a and a decimal size of b