📝 Improvements to provider docs

Split each provider out into a separate section to avoid cramming all the info onto a single page Introduce a limitations doc for SQLite Resolves #32
dotnet · Jan 21, 2016 · c5387ae · c5387ae
1 parent 65a6cdf
commit c5387ae
Show file tree

Hide file tree

Showing 7 changed files with 281 additions and 92 deletions.
diff --git a/docs/providers/in-memory/index.rst b/docs/providers/in-memory/index.rst
@@ -0,0 +1,34 @@
+InMemory (for testing)
+======================
+
+.. contents:: `In this article:`
+    :depth: 2
+    :local:
+
+Getting Started
+---------------
+
+See the `tests for the UnicornStore sample application <https://github.com/rowanmiller/UnicornStore/blob/master/UnicornStore/src/UnicornStore.Tests/Controllers/ShippingControllerTests.cs>`_ for an example of using this provider.
+
+Supported Database Engines
+--------------------------
+
+Built-in in-memory database (designed for testing purposes only)
+
+Supported Platforms
+-------------------
+
+  * Full .NET (4.5.1 onwards)
+  * DNX/ASP.NET 5 (dnx451 and dnxcore50)
+  * Mono (4.2.0 onwards)
+  * Universal Windows Platform
+
+Status
+------
+
+`Pre-release EntityFramework.InMemory package on NuGet.org <https://www.nuget.org/packages/EntityFramework.InMemory>`_
+
+Project Site
+------------
+
+`EntityFramework GitHub project <https://github.com/aspnet/EntityFramework>`_
diff --git a/docs/providers/index.rst b/docs/providers/index.rst
@@ -1,95 +1,13 @@
 Database Providers
 ==================
 
-The following providers are either available or being developed:
- - `EntityFramework.MicrosoftSqlServer`_
- - `EntityFramework.SQLite`_
- - `EntityFramework.InMemory`_
- - `EntityFramework.SqlServerCompact40`_
- - `EntityFramework.SqlServerCompact35`_
- - `EntityFramework.Npgsql`_
-
-EntityFramework.MicrosoftSqlServer
-----------------------------------
-
-**Database Engine:** Microsoft SQL Server (2008 onwards)
-
-**Platforms:** Full .NET (4.5.1 onwards), DNX/ASP.NET 5 (dnx451 and dnxcore50), Mono (4.2.0 onwards)
-
-.. caution::
-    Using this provider on Mono will make use of the Mono SQL Client implementation, which has a number of known issues. For example, it does not support secure connections (SSL).
-
-**Status:** `Pre-release EntityFramework.MicrosoftSqlServer package on NuGet.org <https://www.nuget.org/packages/EntityFramework.MicrosoftSqlServer>`_ that supports the latest EF7 pre-release
-
-**Project Site:** `EntityFramework GitHub project <https://github.com/aspnet/EntityFramework>`_
-
-**Getting Started:** See :doc:`/getting-started/full-dotnet/index` or :doc:`/getting-started/aspnet5/index` for a walkthrough that uses this provider. The `UnicornStore <https://github.com/rowanmiller/UnicornStore/tree/master/UnicornStore>`_ sample application also uses this provider.
-
-
-EntityFramework.SQLite
-----------------------
-
-**Database Engine:** SQLite (3.7 onwards)
-
-**Platforms:** Full .NET (4.5.1 onwards), DNX/ASP.NET 5 (dnx451 and dnxcore50), Mono (4.2.0 onwards), Universal Windows Platform (local development only)
-
-**Status:** `Pre-release EntityFramework.SQLite package on NuGet.org <https://www.nuget.org/packages/EntityFramework.SQLite>`_ that supports the latest EF7 pre-release
-
-**Project Site:** `EntityFramework GitHub project <https://github.com/aspnet/EntityFramework>`_
-
-**Getting Started:** See :doc:`/getting-started/uwp`, :doc:`/getting-started/linux` or :doc:`/getting-started/osx` for walkthroughs that use this provider
-
-
-EntityFramework.InMemory
-------------------------
-
-**Database Engine:** Built-in in-memory database (designed for testing purposes only)
-
-**Platforms:** Full .NET (4.5.1 onwards), DNX/ASP.NET 5 (dnx451 and dnxcore50), Mono (4.2.0 onwards), Universal Windows Platform (local development only)
-
-**Status:** `Pre-release EntityFramework.InMemory package on NuGet.org <https://www.nuget.org/packages/EntityFramework.InMemory>`_ that supports the latest EF7 pre-release
-
-**Project Site:** `EntityFramework GitHub project <https://github.com/aspnet/EntityFramework>`_
-
-**Getting Started:** See the `tests for the UnicornStore sample application <https://github.com/rowanmiller/UnicornStore/blob/master/UnicornStore/src/UnicornStore.Tests/Controllers/ShippingControllerTests.cs>`_ for an example of using this provider.
-
-
-EntityFramework.SqlServerCompact40
-----------------------------------
-
-**Database Engine:** SQL Server Compact Edition 4.0
-
-**Platforms:** Full .NET (4.5.1 onwards), DNX/ASP.NET 5 (dnx451 only)
-
-**Status:** `Pre-release EntityFramework.SqlServerCompact40 package on NuGet.org <https://www.nuget.org/packages/EntityFramework.SqlServerCompact40>`_ that supports the latest EF7 pre-release
-
-**Project Site:** `ErikEJ/EntityFramework.SqlServerCompact GitHub Project <https://github.com/ErikEJ/EntityFramework.SqlServerCompact>`_
-
-**Getting Started:** See the `documentation for this project <https://github.com/ErikEJ/EntityFramework.SqlServerCompact/wiki/Using-EF7-with-SQL-Server-Compact-in-Traditional-.NET-Applications>`_
-
-EntityFramework.SqlServerCompact35
-----------------------------------
-
-**Database Engine:** SQL Server Compact Edition 3.5
-
-**Platforms:** Full .NET (4.5.1 onwards), DNX/ASP.NET 5 (dnx451 only)
-
-**Status:** `Pre-release EntityFramework.SqlServerCompact35 package on NuGet.org <https://www.nuget.org/packages/EntityFramework.SqlServerCompact35>`_ that supports the latest EF7 pre-release
-
-**Project Site:** `ErikEJ/EntityFramework.SqlServerCompact GitHub Project <https://github.com/ErikEJ/EntityFramework.SqlServerCompact>`_
-
-**Getting Started:** See the `documentation for this project <https://github.com/ErikEJ/EntityFramework.SqlServerCompact/wiki/Using-EF7-with-SQL-Server-Compact-in-Traditional-.NET-Applications>`_
-
-
-EntityFramework.Npgsql
-----------------------
-
-**Database Engine:** PostgreSQL
-
-**Platforms:** Full .NET (4.5.1 onwards), DNX/ASP.NET 5 (dnx451 and dnxcore50), Mono (4.2.0 onwards)
-
-**Status:** `Pre-release EntityFramework7.Npgsql package on NuGet.org <https://www.nuget.org/packages/EntityFramework7.Npgsql/>`_ that supports the latest EF7 pre-release
-
-**Project Site:** `Npgsql.org <http://www.npgsql.org>`_
-
-**Getting Started:** See the `getting started documentation at the Npgsql site <http://www.npgsql.org/doc/ef7.html>`_
+.. toctree::
+    :titlesonly:
+    :caption: The following providers are available
+    :maxdepth: 1
+
+    sql-server/index
+    sqlite/index
+    sql-compact/index
+    npgsql/index
+    in-memory/index
diff --git a/docs/providers/npgsql/index.rst b/docs/providers/npgsql/index.rst
@@ -0,0 +1,33 @@
+Npgsql (PostgreSQL)
+===================
+
+.. contents:: `In this article:`
+    :depth: 2
+    :local:
+
+Getting Started
+---------------
+
+See the `getting started documentation on the Npgsql site <http://www.npgsql.org/doc/ef7.html>`_
+
+Supported Database Engines
+--------------------------
+
+PostgreSQL
+
+Supported Platforms
+-------------------
+
+ * Full .NET (4.5.1 onwards)
+ * DNX/ASP.NET 5 (dnx451 and dnxcore50)
+ * Mono (4.2.0 onwards)
+
+Status
+------
+
+`Pre-release EntityFramework7.Npgsql package on NuGet.org <https://www.nuget.org/packages/EntityFramework7.Npgsql/>`_
+
+Project Site
+------------
+
+`Npgsql.org <http://www.npgsql.org>`_
diff --git a/docs/providers/sql-compact/index.rst b/docs/providers/sql-compact/index.rst
@@ -0,0 +1,35 @@
+Microsoft SQL Server Compact Edition
+====================================
+
+.. contents:: `In this article:`
+    :depth: 2
+    :local:
+
+Getting Started
+---------------
+
+See the `getting started documentation on the project site <https://github.com/ErikEJ/EntityFramework.SqlServerCompact/wiki/Using-EF7-with-SQL-Server-Compact-in-Traditional-.NET-Applications>`_
+
+Supported Database Engines
+--------------------------
+
+* SQL Server Compact Edition 3.5
+* SQL Server Compact Edition 4.0
+
+Supported Platforms
+-------------------
+
+ * Full .NET (4.5.1 onwards)
+ * DNX/ASP.NET 5 (dnx451 only)
+
+Status
+------
+
+Pre-release packages vailable on NuGet.org
+ * `EntityFramework.SqlServerCompact35 <https://www.nuget.org/packages/EntityFramework.SqlServerCompact35>`_
+ * `EntityFramework.SqlServerCompact40 <https://www.nuget.org/packages/EntityFramework.SqlServerCompact40>`_
+
+Project Site
+------------
+
+`ErikEJ/EntityFramework.SqlServerCompact GitHub Project <https://github.com/ErikEJ/EntityFramework.SqlServerCompact>`_
diff --git a/docs/providers/sql-server/index.rst b/docs/providers/sql-server/index.rst
@@ -0,0 +1,41 @@
+Microsoft SQL Server
+====================
+
+.. contents:: `In this article:`
+    :depth: 2
+    :local:
+
+Getting Started
+---------------
+
+The following tutorials use this provider:
+  * :doc:`/getting-started/full-dotnet/index`
+  * :doc:`/getting-started/aspnet5/index`
+
+The following sample applications use this provider:
+  * `UnicornStore <https://github.com/rowanmiller/UnicornStore/tree/master/UnicornStore>`_
+
+Supported Database Engines
+--------------------------
+
+Microsoft SQL Server (2008 onwards)
+
+Supported Platforms
+-------------------
+
+ * Full .NET (4.5.1 onwards)
+ * DNX/ASP.NET 5 (dnx451 and dnxcore50)
+ * Mono (4.2.0 onwards)
+
+.. caution::
+    Using this provider on Mono will make use of the Mono SQL Client implementation, which has a number of known issues. For example, it does not support secure connections (SSL).
+
+Status
+------
+
+`Pre-release EntityFramework.MicrosoftSqlServer package on NuGet.org <https://www.nuget.org/packages/EntityFramework.MicrosoftSqlServer>`_
+
+Project Site
+------------
+
+`EntityFramework GitHub project <https://github.com/aspnet/EntityFramework>`_
diff --git a/docs/providers/sqlite/index.rst b/docs/providers/sqlite/index.rst
@@ -0,0 +1,51 @@
+SQLite
+======
+
+.. toctree::
+    :hidden:
+
+    limitations
+
+.. contents:: `In this article:`
+    :depth: 2
+    :local:
+
+Getting Started
+---------------
+
+The following tutorials use this provider:
+  * :doc:`/getting-started/uwp`
+  * :doc:`/getting-started/linux`
+  * :doc:`/getting-started/osx`
+
+The following sample applications use this provider:
+  * `Unicorn Clicker <https://github.com/rowanmiller/UnicornStore/tree/master/UnicornClicker/UWP>`_
+  * `Unicorn Packer <https://github.com/rowanmiller/UnicornStore/tree/master/UnicornPacker>`_
+
+Supported Database Engines
+--------------------------
+
+SQLite (3.7 onwards)
+
+Supported Platforms
+-------------------
+
+ * Full .NET (4.5.1 onwards)
+ * DNX/ASP.NET 5 (dnx451 and dnxcore50)
+ * Mono (4.2.0 onwards)
+ * Universal Windows Platform
+
+Status
+------
+
+`Pre-release EntityFramework.SQLite package on NuGet.org <https://www.nuget.org/packages/EntityFramework.SQLite>`_
+
+Project Site
+------------
+
+`EntityFramework GitHub project <https://github.com/aspnet/EntityFramework>`_
+
+Limitations
+-----------
+
+See :doc:`limitations` for some important limitations of the SQLite provider.
diff --git a/docs/providers/sqlite/limitations.rst b/docs/providers/sqlite/limitations.rst
@@ -0,0 +1,77 @@
+SQLite Limitations
+==================
+
+When using the SQLite provider, there are a number of limitations you should be aware of. Most of these are a result of limitations in the underlying SQLite database engine and are not specific to EF.
+
+Modeling Limitations
+--------------------
+
+The common relational library (shared by Entity Framework relational database providers) defines APIs for modelling concepts that are common to most relational database engines. A number of these concepts are not supported by the SQLite provider.
+
+* Schemas
+* Sequences
+
+Migrations Limitations
+----------------------
+
+The SQLite database engine does not support a number of schema operations that are supported by the majority of other relational databases. If you attempt to apply one of the unsupported operations to a SQLite database then a ``NotSupportedException`` will be thrown.
+
+.. |yes| unicode:: U+2714
+.. |no| unicode:: U+2717
+
++-------------------------+------------+
+| Operation               | Supported? |
++=========================+============+
+| **AddColumn**           | |yes|      |
++-------------------------+------------+
+| AddForeignKey           | |no|       |
++-------------------------+------------+
+| AddPrimaryKey           | |no|       |
++-------------------------+------------+
+| AddUniqueConstraint     | |no|       |
++-------------------------+------------+
+| AlterColumn             | |no|       |
++-------------------------+------------+
+| AlterSequence           | |no|       |
++-------------------------+------------+
+| **CreateIndex**         | |yes|      |
++-------------------------+------------+
+| CreateSchema            | |no|       |
++-------------------------+------------+
+| CreateSequence          | |no|       |
++-------------------------+------------+
+| **CreateTable**         | |yes|      |
++-------------------------+------------+
+| DropColumn              | |no|       |
++-------------------------+------------+
+| DropForiegnKey          | |no|       |
++-------------------------+------------+
+| **DropIndex**           | |yes|      |
++-------------------------+------------+
+| DropPrimaryKey          | |no|       |
++-------------------------+------------+
+| DropSchema              | |no|       |
++-------------------------+------------+
+| DropSequence            | |no|       |
++-------------------------+------------+
+| **DropTable**           | |yes|      |
++-------------------------+------------+
+| DropUniqueConstraint    | |no|       |
++-------------------------+------------+
+| RenameColumn            | |no|       |
++-------------------------+------------+
+| RenameIndex             | |no|       |
++-------------------------+------------+
+| RenameSequence          | |no|       |
++-------------------------+------------+
+| **RenameTable**         | |yes|      |
++-------------------------+------------+
+| RestartSequence         | |no|       |
++-------------------------+------------+
+
+.. tip::
+  You can workaround some of these limitations by manually writing code in your migrations to perform a table rebuild. A table rebuild involves renaming the existing table, creating a new table, copying data to the new table, and dropping the old table. You will need to use the ``Sql(string)`` method to perform some of these steps.
+
+  See `Making Other Kinds Of Table Schema Changes <http://sqlite.org/lang_altertable.html#otheralter>`_ in the SQLite documentation for more details.
+
+  In the future, EF may support some of these operations by using the table rebuild approach under the covers. You can `track this feature on our GitHub project <https://github.com/aspnet/EntityFramework/issues/329>`_.