Actually *add* the database schema management utilities

In r397874, the scripts were removed... but not replaced. Thanks to
Michael Young for noticing this!
........

Merged revisions 397911 from http://svn.asterisk.org/svn/asterisk/branches/12


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@397912 65c4cc65-6c06-0410-ace0-fbb531ad65f3

1 files changed, 63 insertions, 0 deletions

diff --git a/contrib/ast-db-manage/README.md b/contrib/ast-db-manage/README.md
new file mode 100644
index 000000000..3444dd5cd
--- /dev/null
+++ b/contrib/ast-db-manage/README.md
@@ -0,0 +1,63 @@
+Asterisk Database Manager
+=========================
+
+Asterisk includes optional database integration for a variety of features.
+The purpose of this effort is to assist in managing the database schema
+for Asterisk database integration.
+
+This is implemented as a set of repositories that contain database schema
+migrations, using [Alembic](http://alembic.readthedocs.org).  The existing
+repositories include:
+
+ * `config` - Tables used for Asterisk realtime configuration
+ * `voicemail` - Tables used for `ODBC_STOARGE` of voicemail messages
+
+Alembic uses SQLAlchemy, which has support for
+[many databases](http://docs.sqlalchemy.org/en/rel_0_8/dialects/index.html).
+
+IMPORTANT NOTE: This is brand new and the initial migrations are still subject
+to change.  Only use this for testing purposes for now.
+
+Example Usage
+-------------
+
+First, create an ini file that contains database connection details.  For help
+with connection string details, see the
+[SQLAlchemy docs](http://docs.sqlalchemy.org/en/rel_0_8/core/engines.html#database-urls).
+
+    $ cp config.ini.sample config.ini
+    ... edit config.ini and change sqlalchemy.url ...
+
+Next, bring the database up to date with the current schema.
+
+    $ alembic -c config.ini upgrade head
+
+In the future, as additional database migrations are added, you can run
+alembic again to migrate the existing tables to the latest schema.
+
+    $ alembic -c config.ini upgrade head
+
+The migrations support both upgrading and downgrading.  You could go all the
+way back to where you started with no tables by downgrading back to the base
+revision.
+
+    $ alembic -c config.ini downgrade base
+
+`base` and `head` are special revisions.  You can refer to specific revisions
+to upgrade or downgrade to, as well.
+
+    $ alembic -c config.ini upgrade 4da0c5f79a9c
+
+Offline Mode
+------------
+
+If you would like to just generate the SQL statements that would have been
+executed, you can use alembic's offline mode.
+
+    $ alembic -c config.ini upgrade head --sql
+
+Adding Database Migrations
+--------------------------
+
+The best way to learn about how to add additional database migrations is to
+refer to the [Alembic documentation](http://alembic.readthedocs.org).