wip table declaration documentation

squill-doc/README.md

@@ -1,5 +1,5 @@
 ### Table of Contents
 
 1. [Data Types](data-type/README.md)
-1. Table Declaration
+1. [Table Declaration](table-declaration/README.md)
 1. Expressions

squill-doc/table-declaration/README.md

@@ -0,0 +1,15 @@
+### Table Declaration
+
+Before we build queries, and have them checked at compile-time,
+we need to tell the library about the tables in our schema.
+
+1. [Table constructor](table-constructor.md)
+1. [Adding columns](add-columns.md)
+1. [Declaring the Primary Key](declaring-the-primary-key.md)
+1. [Declaring default values](declaring-default-values.md)
+1. [Declaring generated columns](declaring-generated-columns.md)
+1. [Restricting UPDATE statements/Declaring mutable columns](declaring-mutable-columns.md)
+1. [Disabling INSERT statements]()
+1. [Disabling DELETE statements]()
+1. [Declaring the schema]()
+1. [Renaming the table]()

squill-doc/table-declaration/add-columns.md

@@ -0,0 +1,31 @@
+### `.addColumns()`
+
+We use the `.addColumns()` method to add columns to the table.
+
+```ts
+import * as sql from "@squill/squill";
+
+const myTable = tsql.table("myTable")
+    .addColumns({
+        myTableId : sql.dtBigIntSigned(),
+        title : sql.dtVarChar(255),
+        createdAt : sql.dtDateTime(3),
+    });
+```
+
+[Code Sample](https://anyhowstep.github.io/tsql-sqlite3-browser/test-playground/public/#pre-ts/CIJQ8gCgBAKgggIQDIFEoEkBiUUA10DKMBUAtgJ4wCGARgDYCmA3AFADCIKcMa8yaFavQZQAFCyhQAkINqN0AEwwA5HgHEUIKBBDoAsnBABNKAGkUJuAFUYYdMo4o9KVVGVgYbq0iQAaCdIALgCWgYxQAGqGbAAShqIATACsSQCUbh5ePv6SUgDGAE4MVIEMCnCBUMDcKDD6KKIAzOnunsreSFUomNZInqIAzoEFAGYhpAyiAOQApEYAtDOki0ozMQBcM3qbI1O+UFMAdgD2AO5TqaksqawsAA4FVADmpFRQgXIMAPoAHsGHI2OolkwhuLBY9gImk89lsUBYMkonzEITCDHSLCiSCsKBICOmMQYdDox32p2OBToCguTCAA#ts/PQKgUABFEIIDZwgewGYQC4AsCWBnCeEAhgMYkCmuu2ARnORAOZxI1EICeBAdhjvgAU4RDowBOSAK7cAJgDowkaNgC2AByRj0EEMXy4AjohQSVEAEQABQ5OwJgNu3HMBuJVFUatOvRENxsdHIAZggTJDMrR3t-QJCAWhoJAHdccjFXdwgZchJhMQYSJG5cbQ0kRAAuPwM44LkBJAq3EGBFIpLtFQ4AFSI6BgBeGrg5dH76AApzbr6B8wBKLLkiGRkAYQrJFRLJgG8s6AhZifIASRkIav85GXQAIWxGM+50AGUn7nIZSYWAGkO0HQgXoVxGt3QADUiGJ1pgYZMAEwAVmR-0BUBIBSIQRkMG01yMEIAIjjyD1VORJsF0UcAL4LNxHMDlUakAy2AqTIi4DjcEgQSYdL4kYHFBYQQYAPggByOwGAQlIDHYiBkOP6PMKqvw2BK2ByEEw6XIWQ6pQgKUlxGSREC4PCKkmJwGSyORzkaXooqFWx2+GlEAA2kU4NsSgBdN3uqByFDkdAkTDwOC+7gisXcRlm4q4CrkOQsRiTFLZhluIA#post-ts/MoUQMiDCAqAEBUsBiAlA8gWVgWwJ7QEMAjAGwFMBuIA)
+
+-----
+
+We need to specify the column alias, and data type of each column.
+
+For more information about the data types used in the code sample,
+see [Default supported data types](../data-type/default-supported-data-types.md)
+
+-----
+
+Now that the table has a few columns, we can now start writing queries with it.
+
+However, this table definition is far from being useful. We can add more to the table definition.
+
+For example, [declaring the primary key](declaring-the-primary-key.md) of the table.

squill-doc/table-declaration/declaring-default-values.md

@@ -0,0 +1,56 @@
+### Declaring default values
+
+Most columns do not have default values.
+
+When performing an INSERT, we must provide values for all columns that do not have default values.
+
+However, if a column has a default value,
+then we can let the database use it for INSERTs.
+
+-----
+
+### Nullable columns
+
+Nullable columns have an implicit default value of `NULL`.
+
+```ts
+import * as sql from "@squill/squill";
+
+const myTable = sql.table("myTable")
+    .addColumns({
+        myTableId : sql.dtBigIntSigned(),
+        title : sql.dtVarChar(255),
+        //Implicit default value of `NULL`
+        createdAt : sql.dtDateTime(3).orNull(),
+    })
+    .setAutoIncrement(columns => columns.myTableId);
+```
+
+[Code Sample](https://anyhowstep.github.io/tsql-sqlite3-browser/test-playground/public/#pre-ts/CIJQ8gCgBAKgggIQDIFEoEkBiUUA10DKMBUAtgJ4wCGARgDYCmA3AFADCIKcMa8yaFavQZQAFCyhQAkINqN0AEwwA5HgHEUIKBBDoAsnBABNKAGkUJuAFUYYdMo4o9KVVGVgYbq0iQAaCdIALgCWgYxQAGqGbAAShqIATACsSQCUbh5ePv6SUgDGAE4MVIEMCnCBUMDcKDD6KKIAzOnK3kgsqawsAA4FVADmpFRQgXIMAPoAHsEAdgBmAPaissKdLCz2BJqe9rZQLDKUY2IhYQzpLFFIVigkB6IA5DEMdHQLvlAA7gsFdAoPnSAA#ts/PQKgUABFEIIDZwgewGYQC4AsCWBnCeEAhgMYkCmuu2ARnORAOZxI1EICeBAdhjvgAU4RDowBOSAK7cAJgDowkaNgC2AByRj0EEMXy4AjohQSVEAEQABQ5OwJgNu3HMBuJVFUatOvRENxsdHIAZggTJDMrR3t-QJCAWhoJAHdccjFXdwgZchJhMQYSJG5cbQ0kRAAuPwM44LkBJAq3EGBFIpLtFQ4AFSI6BgBeGrg5dH76AApzbr6B8wBKLLkiGRkAYQrJFRLJgG8s6AhZifIASRkIav85GXQAIWxGM+50AGUn7nIZSYWAGkO0HQgXoVxGt3QADUiGJ1pgYZMAEwAVmR-0BUBIBSIQRkMG01yMEIAIjjyD1VORJsEFnJNAA5SQIX4Ao4AXyWRzkaXQMEk6CQLyx5BU5FekyKcG2JQggwAfBBJdLcHITgMLgs3EcwOVRqQDLYCpMiLgONwSBAJcUviRgcUFrKFQcjsBgEJSAx2IgZDj+ibCl78NgStgchBMOlyFkOqUeGktN8AEpIZKy4jJIiBY69U5yYPx3myABi5HQJEwkwxiutuTt3FZR2gzsbLeB6FB1XM9w45D+EGSmjgMnMDZbLuAPX4BHw3CQ2gKBuwBUuNFyREkaSr4+SDHhADdPbxPAESFmcih13BtHv2JJyAox43XcKyXiCRBuEy4KPG2yspro2KXAKnvFhGGmfN0lxZNkhHOMoKTFMAMAzp4ITGQYMRNMiAzLM1XoPMSigmBi1LctK0fDobTrH8jmbR8oDbDsLAACWwR4+wHMQhxHLdoFdFiU3IA8xE4hgVBECA1AkPdQ0PCByAADzUE9Aj4qBXRvKUGBQTQ+EKLYdlosdXXzIJVmQNAN2DRh9OycgLyZa9byjBjoBfXF8TBL5U1JIJpkRAAGABGQL4hC8Lgp6YLgkqQLAriwK5HiwKAC1FmMqA-yOACjhjEC5DAiCiPQzC4Mg0qU0RACOTcIA#post-ts/MoUQMiDCAqAEBUsBiAlA8gWVgWwJ7QEMAjAGwFMBuIA)
+
+-----
+
+### `.addExplicitDefaultValue()`
+
+```ts
+import * as sql from "@squill/squill";
+
+const myTable = sql.table("myTable")
+    .addColumns({
+        myTableId : sql.dtBigIntSigned(),
+        title : sql.dtVarChar(255),
+        createdAt : sql.dtDateTime(3),
+    })
+    .setAutoIncrement(columns => columns.myTableId)
+    .addExplicitDefaultValue(columns => [
+        columns.createdAt
+    ]);
+```
+
+[Code Sample](https://anyhowstep.github.io/tsql-sqlite3-browser/test-playground/public/#pre-ts/CIJQ8gCgBAKgggIQDIFEoEkBiUUA10DKMBUAtgJ4wCGARgDYCmA3AFADCIKcMa8yaFavQZQAFCyhQAkINqN0AEwwA5HgHEUIKBBDoAsnBABNKAGkUJuAFUYYdMo4o9KVVGVgYbq0iQAaCdIALgCWgYxQAGqGbAAShqIATACsSQCUbh5ePv6SUgDGAE4MVIEMCnCBUMDcKDD6KKIAzOnunsreSFUomNZInqIAzoEFAGYhpAyiAOQApEYAtDOki0ozMQBcM3qbI1O+UFMAdgD2AO5TqaksqawsAA4FVADmpFRQgXIMAPoAHsGHI2OolkwhuLBY9gImk89lsUBYMkonzEITCDHSLCiSCsKBICOmMQYdDox32p2OBToCguTCAA#ts/PQKgUABFEIIDZwgewGYQC4AsCWBnCeEAhgMYkCmuu2ARnORAOZxI1EICeBAdhjvgAU4RDowBOSAK7cAJgDowkaNgC2AByRj0EEMXy4AjohQSVEAEQABQ5OwJgNu3HMBuJVFUatOvRENxsdHIAZggTJDMrR3t-QJCAWhoJAHdccjFXdwgZchJhMQYSJG5cbQ0kRAAuPwM44LkBJAq3EGBFIpLtFQ4AFSI6BgBeGrg5dH76AApzbr6B8wBKLLkiGRkAYQrJFRLJgG8s6AhZifIASRkIav85GXQAIWxGM+50AGUn7nIZSYWAGkO0HQgXoVxGt3QADUiGJ1pgYZMAEwAVmR-0BUBIBSIQRkMG01yMEIAIjjyD1VORJsF0UcAL5LI5yNLoGCSdBIF5Y8gqcivSZFODbEoQQYAPggguFuDkJwGF0Z0BWawAogAPNQBEiBYnkFBESRwKHsSRUqU7fDiiAAbQxkq2Frk3LJePQWQAugs3EcwOVRqQDLYCpMiLgONwSBABcUviRgcUFqKJQcjsBgEJSAx2IgZDj+qHCtn8NgStgchBMOlyFkOqUeGktN8AEpIZKi4jJIiBY69U5yEsN1myABi5HQJEwkztHVj8e4AKORxTi5XwPQoOq5nuHHIfwgyU0cBk5gXK8XaZ6-AI+G4SG0BUD2AKlxouQNaTtqeAyQY8IAblmvDkBqWrdjk+qGtof4muQChnuewDOri+Jgl8bakkEvyniudJZF6NbFLgFSwSwjDTAO6S4i2yQnvWlHNq2+EEZ0dGNjI1GIu2RCdt2cr0P2JSUTAI5jhOU7wTOuRzthi7LvBUBrhuFgABLYI8e4HmIR4np+0BpsprbkABYgaQwKgiBAagSH+ZaARAwGatg2puvJenANBQoMCgmh8IUDrzrpUBpgOQSrMgaCSNQ3CML52R6gaRoQB5pqBZK2LIQSEBoRAGFUuYiIAAwAIwFfExVlUVPRFcElQFQVtUFXIdUFQAWosMn0nh3rQLWxFyKR5GCWxHG0RRw2toi+EMm4QA#post-ts/MoUQMiDCAqAEBUsBiAlA8gWVgWwJ7QEMAjAGwFMBuIA)
+
+-----
+
+### `.removeExplicitDefaultValue()`
+
+You should not have to use this method often, if at all.

squill-doc/table-declaration/declaring-generated-columns.md

@@ -0,0 +1,29 @@
+### Declaring generated columns
+
+When performing an INSERT/UPDATE, we **cannot** provide values for generated columns.
+
+The value of generated columns is always set by the database.
+
+-----
+
+### `.addGenerated()`
+
+```ts
+import * as sql from "@squill/squill";
+
+const triangle = sql.table("triangle")
+    .addColumns({
+        a : sql.dtDouble(),
+        b : sql.dtDouble(),
+        hypSquared : sql.dtDouble(),
+    })
+    .addGenerated(columns => [columns.hypSquared]);
+```
+
+[Code Sample](https://anyhowstep.github.io/tsql-sqlite3-browser/test-playground/public/#pre-ts/CIJQ8gCgBAKgggIQDIFEoEkBiUUA10DKMBUALgE4CWAhgHYDmANgKYDcAUAMIgpwxrxkaCjQYsoACnZQZUalGBgAqkKgA5MDHVKkSADTTZAIwXLVGrWp37DASAC09qAAtSpAA4BnAFwB6X-SUpM4ArkYAdADGAPYAtr5wtACeztEA7gSkzO6+pJ4Ajoz2BYxBzADM9kbk6Z7M5L6Unp4hzJ6+AByGMs5J7gT5IdTkzAAmpiqo6praulBwJFK2ttQAVPIA1FBGq0bstgCU7Acc7O7k1PSx8qTURiwA+gAelLQAZtESInRMzCfs7HQagIKBAWiBMDA+2+YmYkmoem2RwAanAkEoUAR9hIAIyInEHAy2CTlREAVkJ2I6+IATCcgA#ts/PQKgUABFEIIDZwgewGYQC4AsCWBnCeEAhgMYkCmuu2ARnORAOZxI1EICeBAdhjvgAU4RDowBOSAK7cAJgDowkaNgC2AByRj0EEMXy4AjohQSVEAEQABQ5OwJgNu3HMBuJVFUatOvRENxsdHIAZggTJDMrR3t-QJCAWhoJAHdccjFXdwgZchJhMQYSJG5cbQ0kRAAuPwM44LkBJAq3EGAwIpLtdDFsIm5mBgBeGrg5dCI6cgAKc27e-vpzAEosuSIZGQBhCskVEqmAbyzoYghq-zkZdAARKUmppYAaY+gaM5HLm7v6B+eTk8wHDUAGUDJIiAUZO8LldbpJ7k8sgBfFYnNYbADi5G46SIQRkUyKcF2JQggwAfBAANpEkm4OSAkFgiHkGQAXSWbjA5VGpDB2AKUyIuA43BIEEJxRxJHQ2GKSzJlKOJ2AwCEpAY7EQMjxE2FhS1+GwJWwOQgmHS5CyRGSRECGB6fQGcmNaS0AHkcVMXlAOtLZcU-v8oMrg-8iO9ggAmOQARiDYde7yj9QA7AnExBVQBVMURFTY2X9PiEZJOCBqCQySQUU5FdR2BjpCRiH3-VWM0HgyHvACc-YzJyRWU5YBRbiAA#post-ts/MoUQMiDCAqAEBUsBiAlA8gWVgFwE4EsBDAOwHMAbAUwG4g)
+
+-----
+
+### `.removeGenerated()`
+
+You should not have to use this method often, if at all.

squill-doc/table-declaration/declaring-mutable-columns.md

@@ -0,0 +1,69 @@
+### Restricting UPDATE statements/Declaring mutable columns
+
+This library makes all columns of a table immutable by default.
+
+This means you cannot modify column values with UPDATE statements.
+
+-----
+
+You need to explicitly declare which columns are mutable.
+
+-----
+
+### `.addAllMutable()`
+
+A convenience method for declaring that every column is mutable.
+```ts
+import * as sql from "@squill/squill";
+
+const myTable = sql.table("myTable")
+    .addColumns({
+        myTableId : sql.dtBigIntSigned(),
+        title : sql.dtVarChar(255),
+        content : sql.dtVarChar(255),
+    })
+    .setAutoIncrement(columns => columns.myTableId)
+    .addAllMutable();
+```
+
+[Code Sample](https://anyhowstep.github.io/tsql-sqlite3-browser/test-playground/public/#pre-ts/CIJQ8gCgBAKgggIQDIFEoEkBiUUA10DKMBUAtgJ4wCGARgDYCmA3AFADCIKcMa8yaFavQZQAFCyhQAkINqN0AEwwA5HgHEUIKBBDoAsnBABNKAGkUJuAFUYYdMo4o9KVVGVgYbq0iQAaCdIALgCWgYxQAGqGbAAShqIATACsSQCUbh5ePv6SUgDGAPYAdoEMJZHRcSCJKenunsreSCyprCwADgBOVADmpFRQgXIMAPoAHsFFAGYForLCrSws9gSanva2UCwylMNiIWEMvlCFJWWB6SxRSFYoJNuiAOQxDHR0BccA7gWddAqPx0eSB+DFIUGC7QAzgBXUiPVpAA#ts/PQKgUABFEIIDZwgewGYQC4AsCWBnCeEAhgMYkCmuu2ARnORAOZxI1EICeBAdhjvgAU4RDowBOSAK7cAJgDowkaNgC2AByRj0EEMXy4AjohQSVEAEQABQ5OwJgNu3HMBuJVFUatOvRENxsdHIAZggTJDMrR3t-QJCAWhoJAHdccjFXdwgZchJhMQYSJG5cbQ0kRAAuPwM44LkBJAq3EGBFIpLtFQ4AFSI6BgBeGrg5dH76AApzbr6B8wBKLLkiGRkAYQrJFRLJgG8s6AhZifIASRkIav85GXQAIWxGM+50AGUn7nIZSYWAGkO0HQgXoVxGt3QADUiGJ1pgYZMAEwAVmR-0BUA6QVeYJud2hsPhYiRqPRRwAvksjnI0ugYJJ0EgXiQCipyK9JkU4NsShBBgA+CBcnm4OQnAYXKnQFZreBwACyDNOvzcRzA5VGpAMtgKkyIuA43BIEE5xS+JGBxQWfMFByOwGAQlIDHYiBkRHGbDSQtd+GwJWwOQgmHS5CyRGSRECx16pzk-rSWhgsgAYuR0CRMJMMUKzblLdwAUcjnbi2XgehQdVzPcOOQ-hBkpo4DJzEWy8WseztNWZBVNH5o0Q2eg2znyVkFqroOHI9HxfQc3JkiGCgBRAwCMSqGEcADS5A4+xzRwX50u1Uezw5AEYyR3KUvJGp3UFsx3O3mLdhiu2P5ith2fABQgUt-2LAp0EkMReDA8COwrKtwQ6EgPXfeCMPMABVF8PW+asGxPDDoGFICxhBMNiI7e8qKOLscWuIw5BQtCiKo7DcKCGQCIgNjiNIkpmOKbF0D4j8aOI8lp3AidxLcSk3CAA#post-ts/MoUQMiDCAqAEBUsBiAlA8gWVgWwJ7QEMAjAGwFMBuIA)
+
+Auto-increment columns are special and require [extra effort](declaring-the-primary-key.md#enableExplicitAutoIncrementValue) to declare as mutable.
+
+-----
+
+### `.addMutable()`
+
+This method lets you specify which columns are mutable.
+```ts
+import * as sql from "@squill/squill";
+
+const myTable = sql.table("myTable")
+    .addColumns({
+        myTableId : sql.dtBigIntSigned(),
+        title : sql.dtVarChar(255),
+        content : sql.dtVarChar(255),
+    })
+    .setAutoIncrement(columns => columns.myTableId)
+    .addMutable(columns => [
+        columns.title,
+    ]);
+```
+
+Mutable columns may be modified with UPDATE statements.
+
+[Code Sample](https://anyhowstep.github.io/tsql-sqlite3-browser/test-playground/public/#pre-ts/CIJQ8gCgBAKgggIQDIFEoEkBiUUA10DKMBUAtgJ4wCGARgDYCmA3AFADCIKcMa8yaFavQZQAFCyhQAkINqN0AEwwA5HgHEUIKBBDoAsnBABNKAGkUJuAFUYYdMo4o9KVVGVgYbq0iQAaCdIALgCWgYxQAGqGbAAShqIATACsSQCUbh5ePv6SUgDGAPYAdoEMJZHRcSCJKenunsreSCyprCwADgBOVADmpFRQgXIMAPoAHsFFAGYForLCrSws9gSanva2UCwylMNiIWEMvlCFJWWB6SxRSFYoJNuiAOQxDHR0BccA7gWddAqPx0eSB+DFIUGC7QAzgBXUiPVpAA#ts/PQKgUABFEIIDZwgewGYQC4AsCWBnCeEAhgMYkCmuu2ARnORAOZxI1EICeBAdhjvgAU4RDowBOSAK7cAJgDowkaNgC2AByRj0EEMXy4AjohQSVEAEQABQ5OwJgNu3HMBuJVFUatOvRENxsdHIAZggTJDMrR3t-QJCAWhoJAHdccjFXdwgZchJhMQYSJG5cbQ0kRAAuPwM44LkBJAq3EGBFIpLtFQ4AFSI6BgBeGrg5dH76AApzbr6B8wBKLLkiGRkAYQrJFRLJgG8s6AhZifIASRkIav85GXQAIWxGM+50AGUn7nIZSYWAGkO0HQgXoVxGt3QADUiGJ1pgYZMAEwAVmR-0BUA6QVeYJud2hsPhYiRqPRRwAvksjnI0ugYJJ0EgXiQCipyK9JkU4NsShBBgA+CBcnm4OQnAYXKnQFZrACyDNOnK2O3wAogAG0MULlSUxiDyACjgBdBZuI5gcqjUgGWwFSZEXAcbgkCBK7hfEjA4oLPmCg5HYDAISkBjsRAyIjjNhpIVh-DYErYHIQTDpchZIjJIiBY69U5yBNpLQwWQAMXI6BImEmWo6Hq93ENR2g-ubbeB6FB1XM9w4BogyU0cBk5ibbaOWPZ2m7Mgqmj8OaIbPQo615KypqyGazOfF9C1cmSqYKAFEDAIxKoYRwANLkDj7LVHPfnS7VR7PDkARjJ48pB8kNQIyCGtx2bOtcgbMcwO1bkVV9CBWxg5sCnQSQxF4JDkPHDsu3BDoSEjUDsJI8wAFUgMjb5uz+CAnxI6BhRVPVO3TBjx1-diA2AMjnQiNlXgTRg+EIZInCYbAADc2K47iiG1dQ7AYdIJDEejkNAdSYMnHFriMOQCKIrTSIo4DqIsWjjOwpjdR09ArLbTjZIgQNWgciByTNbD1zAzdKTcIA#post-ts/MoUQMiDCAqAEBUsBiAlA8gWVgWwJ7QEMAjAGwFMBuIA)
+
+Auto-increment columns are special and require [extra effort](declaring-the-primary-key.md#enableExplicitAutoIncrementValue) to declare as mutable.
+
+-----
+
+### `.removeAllMutable()`
+
+You should not have to use this method often, if at all.
+
+-----
+
+### `.removeMutable()`
+
+You should not have to use this method often, if at all.