From 085777e3469b62b7cdb4ebc8b1adb813ec4ce8c8 Mon Sep 17 00:00:00 2001
From: collerek <collerek@gmail.com>
Date: Mon, 26 Oct 2020 10:04:42 +0100
Subject: [PATCH] update docs for db init and migrations

---
 docs/fastapi.md             |  7 +++++-
 docs/models.md              | 45 ++++++++++++++++++++++++++++++++++++-
 docs_src/fastapi/docs001.py |  2 +-
 3 files changed, 51 insertions(+), 3 deletions(-)

diff --git a/docs/fastapi.md b/docs/fastapi.md
index fbb6f11..6078053 100644
--- a/docs/fastapi.md
+++ b/docs/fastapi.md
@@ -6,6 +6,10 @@ you need to do is substitute pydantic models with ormar models.
 
 Here you can find a very simple sample application code.
 
+!!!warning
+    This example assumes that you already have a database created. If that is not the case please visit [database initialization][database initialization] section.
+
+
 ## Imports and initialization 
 
 First take care of the imports and initialization 
@@ -98,4 +102,5 @@ def test_all_endpoints():
     You can read more on testing fastapi in [fastapi][fastapi] docs. 
 
 [fastapi]: https://fastapi.tiangolo.com/
-[models]: ./models.md
\ No newline at end of file
+[models]: ./models.md
+[database initialization]: ./models.md/#database-initialization-migrations
\ No newline at end of file
diff --git a/docs/models.md b/docs/models.md
index 6e2c73b..3562a7b 100644
--- a/docs/models.md
+++ b/docs/models.md
@@ -58,6 +58,47 @@ But for now you cannot change the ManyToMany column names as they go through oth
 ```Python hl_lines="18"
 --8<-- "../docs_src/models/docs010.py"
 ```
+### Database initialization/ migrations
+
+Note that all examples assume that you already have a database.
+
+If that is not the case and you need to create your tables, that's super easy as `ormar` is using sqlalchemy for underlying table construction.
+
+All you have to do is call `create_all()` like in the example below.
+
+```python
+import sqlalchemy
+# get your database url in sqlalchemy format - same as used with databases instance used in Model definition
+engine = sqlalchemy.create_engine("sqlite:///test.db")
+# note that this has to be the same metadata that is used in ormar Models definition
+metadata.create_all(engine)
+```
+
+You can also create single tables, sqlalchemy tables are exposed in `ormar.Meta` class.
+
+```python
+import sqlalchemy
+# get your database url in sqlalchemy format - same as used with databases instance used in Model definition
+engine = sqlalchemy.create_engine("sqlite:///test.db")
+# Artist is an ormar model from previous examples
+Artist.Meta.table.create(engine)
+```
+
+!!!warning
+    You need to create the tables only once, so use a python console for that or remove the script from your production code after first use.
+
+Likewise as with tables, since we base tables on sqlalchemy for migrations please use [alembic][alembic].
+
+Use command line to reproduce this minimalistic example.
+
+```python
+alembic init alembic
+alembic revision --autogenerate -m "made some changes"
+alembic upgrade head
+```
+
+!!!info
+    You can read more about table creation, altering and migrations in [sqlalchemy table creation][sqlalchemy table creation] documentation.
 
 ### Dependencies
 
@@ -260,4 +301,6 @@ For example to list table model fields you can:
 [sqlalchemy-core]: https://docs.sqlalchemy.org/en/latest/core/
 [sqlalchemy-metadata]: https://docs.sqlalchemy.org/en/13/core/metadata.html
 [databases]: https://github.com/encode/databases
-[sqlalchemy connection string]: https://docs.sqlalchemy.org/en/13/core/engines.html#database-urls
\ No newline at end of file
+[sqlalchemy connection string]: https://docs.sqlalchemy.org/en/13/core/engines.html#database-urls
+[sqlalchemy table creation]: https://docs.sqlalchemy.org/en/13/core/metadata.html#creating-and-dropping-database-tables
+[alembic]: https://alembic.sqlalchemy.org/en/latest/tutorial.html
\ No newline at end of file
diff --git a/docs_src/fastapi/docs001.py b/docs_src/fastapi/docs001.py
index a1d13c5..30ca75f 100644
--- a/docs_src/fastapi/docs001.py
+++ b/docs_src/fastapi/docs001.py
@@ -8,7 +8,7 @@ import ormar
 
 app = FastAPI()
 metadata = sqlalchemy.MetaData()
-database = databases.Database("sqlite:///test.db", force_rollback=True)
+database = databases.Database("sqlite:///test.db")
 app.state.database = database