DatabaseSchema/design/design-1.3.txt

eZ component: DatabaseSchema, Design, 1.3
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:Author: Frederik Holljen
:Revision: $Rev:$
:Date: $Date:$
:Status: Draft

.. contents::

Introduction
============

Version 1.3 of DatabaseSchema will include scripts that support:
 - outputing a database schema
 - writing a database schema to a database
 - outputing a database diff
 - writinga database diff to a database
 - schema validating

The corresponding issue in the issue tracker to this design document is
#010534.

Design description
==================

The implementation will consist of five scripts and will use ConsoleTools for
handling of parameters. The scripts in this proposal are writtin in UNIX style
accepting intput from STDIN and writing to STDOUT by default.

Saving a database schema
------------------------

The script will have the following parameters and options:

dbschemasave SRC

SRC is the full DSN of the database to read from.

 -f, --format=FORMAT          One of xml[default], php.
 -n, --native-format=FORMAT   Overrides -f, one of db handler names.
 -t, --target-file=FILE       Path to filename to write output to.

By default it will write the output to STDOUT in the XML format. If the user
has added additional formats they too can be used with -f.


Loading a database schema
-------------------------

The script will have the following parameters and options:

dbschemaload TARGET

TARGET is the full DSN of the database to write to.

 -f, --format=FORMAT     One of xml[default] or php.
 -t, --target-file=FILE  Path to filename to read from.

By default it will load the input from STDIN. If -t is used the tool will try
to guess the format based on the file extension. The format can always be
overriden with -f. If the user has added additional formats they too can be 
used with -f.


Saving a diff
-------------

The script will have the following parameters and options:

dbchemadiff FROM TO

 -f, --format=FORMAT     One of xml[default] or php.
 -t, --target-file=FILE  Path to filename to write output to
 -n, --native-format=FORMAT   Overrides -f, one of db handler names.

FROM and TO can both be DSN's specifying databases to read from
or they can be paths to files containing db schema definitions.
By default it will write the output to STDOUT in the XML format. If the user
has added additional formats they too can be used with -f.

Applying a diff
--------------

The script will have the following parameters and options:

dbschemadiffapply TARGET

 -f, --format=FORMAT     One of xml[default] or php.
 -t, --target-file=FILE  Path to filename to write output to

TARGET is the DSN to the database that should have the diff applied. By default
the script will load the diff from STDIN. This can be overriden with -t.

Since this script can be potentially harmful to your database should we
should issue a warning by default and ask if the user is sure he/she wants to
continue. This could be surpressed with an optional parameter.


Validating a schema
-------------------

The script will have the following parameters and options:

dbschemavalidate

 -f, --format=FORMAT     One of xml[default] or php.
 -t, --target-file=FILE  Path or DSN to validate.

Validates the schema from STDIN or given by -f.


..
   Local Variables:
   mode: rst
   fill-column: 79
   End: 
   vim: et syn=rst tw=79