Permalink
Browse files

docs!

  • Loading branch information...
1 parent 3b47e45 commit 7a6913729f84810c978c627e9f5f5c14493af5b2 @piranha committed Sep 21, 2012
Showing with 109 additions and 11 deletions.
  1. +9 −2 README.rst
  2. +16 −9 docs/index.rst
  3. +40 −0 docs/quick-start.rst
  4. +1 −0 docs/test-basic.rst
  5. +1 −0 docs/test-urls.rst
  6. +32 −0 docs/urls.rst
  7. +5 −0 tests/basic.t
  8. +5 −0 tests/urls.t
View
@@ -12,12 +12,15 @@ migrate and can run pre- and post-processing routines written in any language
.. image:: https://github.com/piranha/nomad/raw/master/docs/nomad.jpg
+.. begin-writeup
+
Concept
-------
Nomad's migration store is a directory with ``nomad.ini`` and a other
directories inside. Each directory in it containing ``migration.ini`` is a
-single migration and name of child directory is an identifier of migration.
+single migration and name of this child directory is an unique identifier of a
+migration.
It looks like this::
@@ -32,7 +35,9 @@ It looks like this::
2-up.sql
3-post.py
-Main properties:
+
+Main properties
+---------------
- There is no downgrades - nobody ever tests them, they are rarely necessary
- You can write migration in whatever language you want, tool only helps you
@@ -44,3 +49,5 @@ Main properties:
- Name matters - everything is executed in order. Order is determined by using
human sort (so that ``x-1.sql`` is earlier than ``x-10.sql``, you can always
check sorting with ``ls --sort=version``).
+
+.. end-writeup
View
@@ -1,20 +1,27 @@
-.. nomad documentation master file, created by
- sphinx-quickstart on Sat Sep 3 17:08:47 2011.
- You can adapt this file completely to your liking, but it should at least
- contain the root `toctree` directive.
-
-Welcome to nomad's documentation!
-=================================
+Nomad
+=====
Contents:
.. toctree::
- :maxdepth: 2
+ :maxdepth: 1
+
+ quick-start
+ urls
+ Basic tests <test-basic>
+ URL acquiring tests <test-urls>
+
+.. note:: Right now only SQL databases are supported (SQLite/MySQL/PgSQL through
+ DB API or anything what SQLAlchemy supports), but whole architecture is
+ structured so that it is easy to add support for NoSQL dbs.
+
+.. include:: ../README.rst
+ :start-after: begin-writeup
+ :end-before: end-writeup
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
-
View
@@ -0,0 +1,40 @@
+Quick Start
+===========
+
+To use nomad, you'll have to supply some basic configuration, in ``ini``
+format::
+
+ [nomad]
+ engine = sqla
+ url = sqlite:///test.db
+
+.. note:: See :doc:`urls` about ways you can use to specify url of database.
+
+Save this in a file named `nomad.ini`. The directory, containing this file, will
+be your nomad environment. You can store file under any other name, but then
+you'll have to supply it as an option to nomad calls (like ``nomad -c myconf.ini``).
+
+Then initialize your database to be used with nomad::
+
+ $ nomad init
+
+This will create a table in your database with 2 fields - ``name`` and
+``date``. This table is used then for tracking which migrations have been
+applied already to this database.
+
+And then you can create a migration::
+
+ $ nomad create 2012-09-21-first
+
+This will create directory with name ``2012-09-21-first`` and two files inside:
+``migration.ini`` and ``up.sql``. Name of first file matters - it contains
+information about dependencies of a migration (which can be passed as ``-d``
+option to ``create`` command). Name of second file doesn't matter - any
+``*.sql`` or executable files (file with executable bit set) will be
+run. ``*.sql`` files are applied to database, while executable files (which can
+be your script to do something before or after migration, or even migration
+itself) are just executed.
+
+You can then list or apply migrations - just read help about them (``nomad help
+ls`` or ``nomad help apply``). Also, reading :doc:`test-basic` can be helpful as
+well.
View
View
View
@@ -0,0 +1,32 @@
+================
+ Acquiring URLs
+================
+
+Nomad supports few different ways of specification how it should connect to
+database.
+
+There are two parameters it has to acquire: ``engine`` and ``url``.
+
+Engine is specified as a string. Supported engines right now consist of
+``dbapi`` and ``sqla``. Both of them support SQLite, MySQL and PostgreSQL
+databases, the first one requiring only db api modules and second one requiring
+SQLAlchemy library.
+
+URL can be specified in few different ways:
+
+ - ``url`` - just a string, path like ``sqlite:///test.db`` or
+ ``mysql://user:pass@host/db``
+
+ - ``url-python`` - taking variable from Python module, has two approaches to
+ fetching python module:
+
+ - From ``sys.path``, when it looks like one: ``yourapp.settings:dburl``
+
+ - From filesystem, when it looks like path to file: ``../settings.py:dburl``
+
+ - ``url-file`` - taking contents of a file: ``../dburl.txt``
+
+ - ``url-command`` - taking output of a command: ``grep mysql ../settings.txt``
+
+
+.. note:: Look at :doc:`test-urls` to see how various options are used.
View
@@ -1,5 +1,10 @@
.. -*- mode: rst -*-
+Basic nomad tests
+=================
+
+.. highlight:: console
+
First, set up environment::
$ cat > nomad.ini <<EOF
View
@@ -1,7 +1,12 @@
.. -*- mode: rst -*-
+URL acquiring test
+==================
+
Test different methods to acquire URLs.
+.. highlight:: console
+
Directly specified URL::
$ cat > nomad.ini <<EOF

0 comments on commit 7a69137

Please sign in to comment.