schema manager - documentation

docs/content/index.md

@@ -17,7 +17,7 @@ hero:
       link: /introduction/features
     - theme: alt
       text: View on GitHub
-      link: https://github.com/makinacorpus/query-builder
+      link: https://github.com/makinacorpus/php-query-builder
 
 features:
   - title: Easy and readable

docs/content/introduction/features.md

@@ -129,3 +129,57 @@ Factory method in the following table refers to methods of the `MakinaCorpus\Que
 Future work is planned on `ARRAY` and `JSON` operators: they were previously implemented in
 `makinacorpus/goat-query` package and will be restored in a near future.
 :::
+
+## Schema alteration (experimental)
+
+| Feature | MariaDB | MySQL | PostgreSQL | SQLite | SQL Server | Notes |
+|:--------|:-------:|:-----:|:----------:|:------:|:----------:|:------|
+| Add column | Yes | Yes | Yes | Yes | Planned | Collations might have problems |
+| Drop column | Yes | Yes | Yes | Yes | Planned | - |
+| Modify column | Downgrade | Downgrade | Yes | Planned | Planned | Collations might have problems |
+| Rename column | Yes | Yes | Yes | No | Planned | - |
+| Drop any constraint | Yes | Yes | Yes | No | Planned | - |
+| Modify any constraint | No | No | No | No | No | - |
+| Rename any constraint | No | No | No | No | No | - |
+| Add foreign key | Downgrade | Downgrade | Yes | Planned | Planned | - |
+| Modify foreign key | No | No | No | No | No | - |
+| Remove foreign key | Yes | Yes | Yes | Planned | Planned | - |
+| Rename foreign key | No | No | No | No | No | - |
+| Create index | Yes | Yes | Yes | Yes | Planned | - |
+| Drop index | Yes | Yes | Yes | Yes | Planned | - |
+| Rename index | Yes | Yes | Yes | Yes | Planned | - |
+| Add primary key | Yes | Yes | Yes | Planned | Planned | - |
+| Drop primary key | Yes | Yes | Yes | Planned | Planned | - |
+| Create table | Yes | Yes | Yes | Yes | Planned | - |
+| Drop table | Yes | Yes | Yes | Yes | Planned | - |
+| Rename table | Yes | Yes | Yes | Planned | Planned | - |
+| Add unique key | Yes | Yes | Yes | Yes | Planned | - |
+| Drop unique key | Yes | Yes | Yes | Yes | Planned | - |
+
+:::info
+MySQL and MariaDB do not support the `DEFERRABLE` constraints. It will simply be
+ignored when specified.
+:::
+
+:::info
+MySQL and MariaDB do not support `NULLS [NOT] DISTINCT` on keys, attempts in
+using this feature will raise exceptions.
+:::
+
+:::warning
+SQLite requires a `DROP` then `CREATE` or `ADD` for most modification or rename
+operations. This hasn't be implemented yet.
+:::
+
+:::warning
+SQLite requires a `DROP` then `CREATE` or `ADD` for most modification or rename
+operations. This hasn't be implemented yet.
+:::
+
+:::warning
+SQL Server is not implemented yet, but is planned.
+:::
+
+:::warning
+Collation support is unforgiving, it simply passes the collation names to the SQL server.
+:::

docs/content/query/schema.md

@@ -25,17 +25,17 @@ $schemaManager = $bridge->getSchemaManager();
 
 The schema manager allows reading the current schema:
 
- - read table data,
+ - read table definitions,
  - read table columns data,
  - read table foreign key and reverse foreign key data.
 
 Other implementations will come later.
 
 :::warning
-When possible, this API uses the `information_schema` tables, nevertheless each database vendor
-has its own dialect, even when considering the information schema. Please be aware that each
+When possible, this API uses the `information_schema` tables. Nevertheless each database vendor
+has its own dialect, even when considering the information schema. Keep in mind that each
 vendor will apply its own access control over information it gives back when reading those
-catalogs, and result may vary depending upon the current user access rights.
+catalogs. Result may vary depending upon the current user access rights.
 :::
 
 First, you may want to list databases:
@@ -53,7 +53,7 @@ $schemas = $schemaManager->listSchemas('my_database');
 ```
 
 :::info
-All schema manager methods takes a mandatory `$database` parameter, and an optional
+All schema manager methods take a mandatory `$database` parameter, and an optional
 `$schema` parameter: schemas are namespaces inside a database and are not isolated
 from each other, you can work with the full database at once.
 
@@ -62,11 +62,11 @@ least PostgreSQL when you create a database from scratch.
 :::
 
 :::warning
-MySQL doesn't not support schemas, this parameter will always be ignored when working
+MySQL doesn't support schemas, this parameter will always be ignored when working
 with it, and `listSchemas()` will always return a single value which is `public`.
 :::
 
-Then fetch some table list:
+Then fetch table list for a particular database/schema:
 
 ```php
 foreach ($schemaManager->listTables('my_database', 'my_schema') as $tableName) {
@@ -82,7 +82,7 @@ $table = $schemaManager->getTable('my_database', 'my_table', 'my_schema');
 // $table is now an instance of MakinaCorpus\QueryBuilder\Schema\Table
 ```
 
-This API is still experimental, and currently work only with MySQL and derivatives
+This API is still experimental, and currently works only with MySQL and derivatives
 and PostgreSQL. Your IDE and browsing the code will give you all methods that you
 should know of easily. More documentation will come later.
 
@@ -105,6 +105,11 @@ transaction started. For now, only PostgreSQL will benefit from a real database
 transaction.
 :::
 
+:::tip
+Please read the [feature matrix](../introduction/features#schema-alteration-experimental)
+for current feature status.
+:::
+
 ### Basic transaction
 
 Considering the API is fluent and all methods can be chained, here is an example
@@ -260,7 +265,7 @@ More detailed documentation will be written later, but here is an example of usa
 ```php
 $schemaManager
     // Create the transaction object, no transaction will be started at this
-    // point, but a in-memory changelog is created for recording all changes
+    // point, but an in-memory changelog is created for recording all changes
     // you are going to do.
     ->modify(database: 'my_database')
 
@@ -275,7 +280,7 @@ $schemaManager
                 nullable: false,
             )
             // Primary key is not mandatory, and may contain more than one
-            // columns, in case you'd ask.
+            // column, in case you'd ask.
             ->primaryKey(['id'])
 
             // Another column, with a default value. Same as types here,
@@ -317,7 +322,7 @@ $schemaManager
                     'user_id' => 'id',
                 ],
 
-                // All constraints and indexes can be explicitely be named.
+                // All constraints and indexes can be explicitly named.
                 name: 'user_role_user_id_fk',
 
                 // And you may target another schema as well:
@@ -334,7 +339,7 @@ $schemaManager
             )
         ->endTable()
 
-        // All methods exist outside of table as well
+        // All methods exist outside the table builder as well:
 
         ->addColumn(/* ... */)
         ->dropColumn(/* ... */)
@@ -369,7 +374,7 @@ $schemaManager
     ->commit()
 ```
 
-There's much more you can do, but beware that for now, most rename actions are
+There's much more you can do, but beware that for now, most renaming actions are
 not implemented yet, because generally each vendor has its own syntax regarding
 those alteration. For now, it requires you to first drop then recreate for most
 things (except for columns and tables which can be renamed). You may also drop

src/Bridge/AbstractBridge.php

@@ -421,7 +421,7 @@ public function getWriter(): Writer
     }
 
     /**
-     * Create default writer based upon server name and version.
+     * Create default schema manager based upon server name and version.
      */
     protected function createSchemaManager(): SchemaManager
     {
@@ -443,7 +443,7 @@ protected function createSchemaManager(): SchemaManager
             return new SQLiteSchemaManager($this, $this);
         }
 
-        throw new UnsupportedFeatureError(\sprintf("Schema reader is not implemented yet for vendor '%s'", $serverFlavor));
+        throw new UnsupportedFeatureError(\sprintf("Schema manager is not implemented yet for vendor '%s'", $serverFlavor));
     }
 
     /**

src/Schema/SchemaManager.php

@@ -67,6 +67,8 @@
  * There are a few exceptions, documented along the way, sometime all vendors
  * have their own dialect, in this case, we almost always prefere PostgreSQL
  * in this class.
+ *
+ * @experimental
  */
 abstract class SchemaManager implements LoggerAwareInterface
 {
@@ -884,15 +886,15 @@ public function applyChange(AbstractChange $change): void
         $expressions = match (\get_class($change)) {
             CallbackChange::class => $this->executeCallbackChange($change),
             ColumnAdd::class => $this->writeColumnAdd($change),
-            ColumnModify::class => $this->writeColumnModify($change),
             ColumnDrop::class => $this->writeColumnDrop($change),
+            ColumnModify::class => $this->writeColumnModify($change),
             ColumnRename::class => $this->writeColumnRename($change),
             ConstraintDrop::class => $this->writeConstraintDrop($change),
             ConstraintModify::class => $this->writeConstraintModify($change),
             ConstraintRename::class => $this->writeConstraintRename($change),
             ForeignKeyAdd::class => $this->writeForeignKeyAdd($change),
-            ForeignKeyModify::class => $this->writeForeignKeyModify($change),
             ForeignKeyDrop::class => $this->writeForeignKeyDrop($change),
+            ForeignKeyModify::class => $this->writeForeignKeyModify($change),
             ForeignKeyRename::class => $this->writeForeignKeyRename($change),
             IndexCreate::class => $this->writeIndexCreate($change),
             IndexDrop::class => $this->writeIndexDrop($change),