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, migration 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)
• 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))

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

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

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

{

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