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

Links
====

[[1] User guide](#user-guide)
- [1 - Overview](#1---overview)
	- [(1) introduction & features](#1-introduction--features)
- [2 - Usage](#2---usage)
	- [(1) setup](#1-setup)
	- [(2) php requirements](#2-php-requirements)
	- [(3) from php](#3-from-php)
- [3 - Configuration](#3---configuration)
	- [(1) Syntax](#1-syntax)
	- [(2) Field types](#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](#3---configuration)))

## (2) Php requirements

> ### 1) include the `autoloader` file

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

> ### 2) load useful classes

```php
use \dbschema\core\dBuilder;

```

## (3) From php


> ### 1) Load configuration schema

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

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

> ### 2) Push the loaded schema to the database

```php
// 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

```json
{

	"{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`|