From cca6d23c46dc986cf03232a2005254d79ada9aba Mon Sep 17 00:00:00 2001 From: xdrm-brackets Date: Sat, 9 Sep 2017 13:02:19 +0200 Subject: [PATCH] Add db-schema:1.0 notice --- README.md | 3 + notice/db-schema/1.0.md | 166 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 169 insertions(+) create mode 100644 notice/db-schema/1.0.md diff --git a/README.md b/README.md index 96600f4..f25e9ec 100644 --- a/README.md +++ b/README.md @@ -72,3 +72,6 @@ xdrm-framework is based on `all in config` so you will have this structure : #### [3.4] orm - sql orm #### [3.5] router - apache2 router #### [3.6] lightdb - fast key-value storage +#### [3.7] db-schema - Json to Mysql + +> version 1.0 - [documentation](/notice/db-schema/1.0.md) diff --git a/notice/db-schema/1.0.md b/notice/db-schema/1.0.md new file mode 100644 index 0000000..c6688b4 --- /dev/null +++ b/notice/db-schema/1.0.md @@ -0,0 +1,166 @@ +```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 + ### 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`|