updated migration and piccolo app documentation

Author: dantownsend

docs/src/index.rst

@@ -9,6 +9,7 @@ Welcome to Piccolo's documentation!
    piccolo/query_types/index
    piccolo/query_clauses/index
    piccolo/schema/index
+   piccolo/projects_and_apps/index
    piccolo/engines/index
    piccolo/migrations/index
    piccolo/authentication/index

docs/src/piccolo/getting_started/database_support.rst

@@ -0,0 +1,10 @@
+.. _DatabaseSupport:
+
+Database Support
+================
+
+Postgres is the primary database which Piccolo was designed for.
+
+Limited SQLite support is available, mostly to enable tooling like the
+playground. Postgres is the only database we recommend for use in production
+with Piccolo.

docs/src/piccolo/getting_started/index.rst

@@ -5,6 +5,7 @@ Getting Started
     :caption: Contents:
 
     ./what_is_piccolo
+    ./database_support
     ./installing_piccolo
     ./playground
     ./installing_postgres

docs/src/piccolo/getting_started/what_is_piccolo.rst

@@ -1,12 +1,13 @@
 What is Piccolo?
 ================
 
-Piccolo is a fast, easy to learn ORM.
+Piccolo is a fast, easy to learn ORM and query builder.
 
 Some of it's stand out features are:
 
 * Support for sync and async - see :ref:`SyncAndAsync`.
 * A builtin playground, which makes learning a breeze - see :ref:`Playground`.
 * Works great with `iPython <https://ipython.org/>`_ and
   `VSCode <https://code.visualstudio.com/>`_ - see :ref:`tab_completion`.
-* Batteries included - a User model, authentication, an admin, and more.
+* Batteries included - a User model, authentication, migrations, an admin,
+  and more.

docs/src/piccolo/migrations/create.rst

@@ -1,22 +1,25 @@
 Creating migrations
 ===================
 
-Migrations are used to create and modify tables in the database.
+Migrations are Python files which are used to modify the database schema in a
+controlled way. Each migration belongs to a Piccolo app (see :ref:`PiccoloApps`).
 
-.. code-block:: bash
+You can either manually populate migrations, or allow Piccolo to do it for you
+automatically. To create an empty migration:
 
-    piccolo migration new
+.. code-block:: bash
 
-This creates a migrations folder, along with a migration file.
+    piccolo migration new my_app
 
-The migration filename is a timestamp, which also serves as the migration ID.
+This creates a new migration file in the migrations folder of the app. The
+migration filename is a timestamp, which also serves as the migration ID.
 
 .. code-block:: bash
 
-    migrations/
+    piccolo_migrations/
         2018-09-04T19:44:09.py
 
-The contents of the migration file look like this:
+The contents of an empty migration file looks like this:
 
 .. code-block:: python
 
@@ -28,43 +31,26 @@ The contents of the migration file look like this:
     async def backwards():
         pass
 
-Populating the migration
-------------------------
+Populating an empty migration
+-----------------------------
 
 At the moment, this migration does nothing when run - we need to populate the
 forwards and backwards functions.
 
 .. code-block:: python
 
-    from piccolo.columns import Varchar
-    from piccolo.tables import Table
-
-
     ID = '2018-09-04T19:44:09'
 
 
-    class Band(Table):
-        name = Varchar(length=100)
-
-
     async def forwards():
-        await Band.create_table().run()
+        await run_some_sql()
 
 
     async def backwards():
-        await Band.alter().drop_table().run()
+        await run_some_other_sql()
 
 If making multiple changes to the database in a single migration, be sure to
-wrap it in a transaction.
-
-.. code-block:: python
-
-    async def forwards():
-        async with Band._meta.db.transaction:
-            await Band.create_table().run()
-            await Manager.create_table().run()
-
-See :ref:`Transactions`.
+wrap it in a transaction. See :ref:`Transactions`.
 
 The golden rule
 ~~~~~~~~~~~~~~~
@@ -92,33 +78,28 @@ someone runs your migrations in the future, they will get different results.
 Make your migrations completely independent of other code, so they're
 self contained and repeatable.
 
-Running migrations
-------------------
-
-When the migration is run, the forwards function is executed. To do this:
-
-.. code-block:: bash
-
-    piccolo migration forwards
+Auto migrations
+---------------
 
-Inspect your database, and a ``band`` table should now exist.
+Manually writing your migrations gives you a good level of control, but Piccolo
+supports `auto migrations` which can save a great deal of time.
 
-Reversing migrations
---------------------
+Piccolo will work out what tables to add by comparing previous auto migrations,
+and your current tables. In order for this to work, you have to register
+your app's tables with the `AppConfig` in the piccolo_app.py file at the root
+of your app (see :ref:`PiccoloApps`).
 
-To reverse the migration, run this:
+Creating an auto migration:
 
 .. code-block:: bash
 
-    piccolo migration backwards 2018-09-04T19:44:09
-
-This executes the backwards function.
+    piccolo migration new my_app --auto
 
-You can try going forwards and backwards a few times to make sure it works as
-expected.
-
-Altering tables
----------------
+.. hint:: Auto migrations are the preferred way to create migrations with
+    Piccolo. We recommend using `empty migrations` for special circumstances which
+    aren't support by auto migrations, or to modify the data held in tables, as
+    opposed to changing the tables themselves.
 
-To alter tables, you'll use mostly use alter queries (see :ref:`alter`), and
-occasionally raw queries (see :ref:`raw`).
+.. warning:: Auto migrations aren't supported in SQLite, because of SQLite's
+    extremely limited support for SQL Alter statements. This might change in
+    the future.

docs/src/piccolo/migrations/index.rst

@@ -1,4 +1,4 @@
-.. _Migrations:
+.. _migrations:
 
 Migrations
 ==========
@@ -7,3 +7,4 @@ Migrations
     :maxdepth: 1
 
     ./create
+    ./running

docs/src/piccolo/migrations/running.rst

@@ -0,0 +1,36 @@
+Running migrations
+==================
+
+Forwards
+--------
+
+When the migration is run, the forwards function is executed. To do this:
+
+.. code-block:: bash
+
+    piccolo migration forwards my_app
+
+Reversing migrations
+--------------------
+
+To reverse the migration, run this:
+
+.. code-block:: bash
+
+    piccolo migration backwards 2018-09-04T19:44:09
+
+This executes the backwards function.
+
+You can try going forwards and backwards a few times to make sure it works as
+expected.
+
+.. warning:: Auto migrations don't currently support going backwards.
+
+Checking migrations
+-------------------
+
+You can easily check which migrations have amd haven't ran using the following:
+
+.. code-block:: bash
+
+    piccolo migration check

docs/src/piccolo/projects_and_apps/index.rst

@@ -0,0 +1,10 @@
+.. _ProjectsAndApps:
+
+Projects and Apps
+=================
+
+.. toctree::
+    :maxdepth: 1
+
+    ./piccolo_projects
+    ./piccolo_apps

docs/src/piccolo/projects_and_apps/piccolo_apps.rst

@@ -0,0 +1,80 @@
+.. _PiccoloApps:
+
+Piccolo Apps
+============
+
+By leveraging Piccolo apps you can unlock some useful functionality like auto
+migrations.
+
+Creating an app
+---------------
+
+Run the following command within your project:
+
+.. code-block:: bash
+
+    piccolo app new my_app
+
+
+This will create a folder like this:
+
+.. code-block:: bash
+
+    my_app/
+        __init__.py
+        piccolo_app.py
+        piccolo_migrations/
+            __init__.py
+        tables.py
+
+
+It's important to register this app with your `piccolo_conf.py` app.
+
+.. code-block:: python
+
+    # piccolo_conf.py
+    APP_REGISTRY = AppRegistry(apps=['my_app.piccolo_app'])
+
+
+Anytime you invoke the `piccolo` command, you will now be able to perform
+operations on your app, the most important of which is :ref:`Migrations`.
+
+AppConfig
+---------
+
+Inside the `piccolo_app.py` file is an AppConfig instance. This is how you
+customise how your app's settings.
+
+.. code-block:: python
+
+    import os
+
+    from piccolo.conf.apps import AppConfig
+    from .tables import (
+        Author,
+        Post,
+        Category,
+        CategoryToPost,
+    )
+
+
+    CURRENT_DIRECTORY = os.path.dirname(os.path.abspath(__file__))
+
+
+    APP_CONFIG = AppConfig(
+        app_name='blog',
+        migrations_folder_path=os.path.join(CURRENT_DIRECTORY, 'piccolo_migrations'),
+        table_classes=[Author, Post, Category, CategoryToPost],
+        migration_dependencies=[],
+    )
+
+table_classes
+~~~~~~~~~~~~~
+
+Use this to register your app's tables. This is important for auto migrations (see :ref:`Migrations`).
+
+migration_dependencies
+~~~~~~~~~~~~~~~~~~~~~~
+
+Used to specify other Piccolo apps whose migrations need to be run before the
+current app's migrations.

docs/src/piccolo/projects_and_apps/piccolo_projects.rst

@@ -0,0 +1,17 @@
+.. _PiccoloProjects:
+
+Piccolo Projects
+================
+
+A Piccolo project is a collection of apps.
+
+A project requires a `piccolo_conf.py` file. To create this file, use the following command:
+
+.. code-block:: bash
+
+    piccolo project new
+
+The piccolo_conf file serves two important purposes:
+
+ * Contains your database settings
+ * Is used for registering :ref:`PiccoloApps`.