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

```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, migration and management. The only things you have to do is to write your JSON configuration, the package will do the rest.

Features:
- [x] Manage multiple databases (according to the database-driver)
- [x] Push a json configuration to a database (mysql)
- [x] Pull a database schema to a json file
- [ ] Migrate a database : automatically detect changes to apply

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 = dBuilder::load();

// loads the custom schema
$dbuilder = dBuilder::load('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) Pull a configuration from a database

```php
// pulls into the default schema (default database-driver config)
$dbuilder = dBuilder::pull();

// pulls into the custom schema
$dbuilder = dBuilder::pull('custom');

// pulls into the default schema ('custom-db' database-driver config)
$dbuilder = dBuilder::pull(null, 'custom-db');

// pulls into the custom schema ('custom-db' database-driver config)
$dbuilder = dBuilder::pull('custom', 'custom-db);
```


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

You must use the default MySQL field types.