diff --git a/squill-doc/README.md b/squill-doc/README.md index 7ee71c9d..266bb4cb 100644 --- a/squill-doc/README.md +++ b/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 diff --git a/squill-doc/table-declaration/README.md b/squill-doc/table-declaration/README.md new file mode 100644 index 00000000..26e99761 --- /dev/null +++ b/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]() diff --git a/squill-doc/table-declaration/add-columns.md b/squill-doc/table-declaration/add-columns.md new file mode 100644 index 00000000..87c15eec --- /dev/null +++ b/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. diff --git a/squill-doc/table-declaration/declaring-default-values.md b/squill-doc/table-declaration/declaring-default-values.md new file mode 100644 index 00000000..1af77b67 --- /dev/null +++ b/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. diff --git a/squill-doc/table-declaration/declaring-generated-columns.md b/squill-doc/table-declaration/declaring-generated-columns.md new file mode 100644 index 00000000..92c8e1a2 --- /dev/null +++ b/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. diff --git a/squill-doc/table-declaration/declaring-mutable-columns.md b/squill-doc/table-declaration/declaring-mutable-columns.md new file mode 100644 index 00000000..65a35d48 --- /dev/null +++ b/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. diff --git a/squill-doc/table-declaration/declaring-the-primary-key.md b/squill-doc/table-declaration/declaring-the-primary-key.md new file mode 100644 index 00000000..607ac9e3 --- /dev/null +++ b/squill-doc/table-declaration/declaring-the-primary-key.md @@ -0,0 +1,115 @@ +### Declaring the primary key + +There are two ways to declare a primary key, ++ `.setAutoIncrement()` ++ `.setPrimaryKey()` + +A primary key is a candidate key that we designate as **the** candidate key we wish to use in most cases. + +A primary key must also not have nullable columns. + +It is recommended for every table to have a primary key. + +----- + +### Highly Recommended Practice + +This library's query-building features work best when you follow these recommendations, + ++ **DO NOT** use `"id"` as the name of primary key columns! ++ **DO** use the more descriptive `entityName + "Id"` as the name of primary key columns! + +Given tables `user`, `book`, and `read`, the following primary keys are bad, ++ `user (id)` ++ `book (id)` ++ `read (userId, bookId)` + +The following primary keys are good, ++ `user (userId)` ++ `book (bookId)` ++ `read (userId, bookId)` + +----- + +If you wish, you may continue to use `"id"` as a column name. + +However, you will lose access to many convenience functions relation to JOIN operations, +when building queries. + ++ [Code Sample for `"id"`](https://anyhowstep.github.io/tsql-sqlite3-browser/test-playground/public/#pre-ts/CIJQ8gCgBAKgggIQDIFEoEkBiUUA10DKMBUARAK4DOApgE6kDcAUAMIgpwxrzJoU30oACiZQoASACWAEwwA5LgHEUIKBBDoAsnBABNKAGkU+uAFUYYdHLYpNKBVDlgYj00iQAaURKp0AdgCGALbUUABqOiwAEjpCAEwArAkAlI7Oru5MycxMAA60AQDmQQFQAC4BAEYANtQA+gAekn4AZgD2Qvx0pNlMTFYEKi5WFlBM4l2CQr60gSGpTBFIpigk40IA5HDVkgDG1BvJXuKbCG2Vh8ziTKCQsIioGNh4hMRklW1tANaMrOyc3AefA+31Iwm8UlkIxQylU6i0On0RhM5ks1nYdgcThccjcnghZUkZVq4UiMRA8SSqWxGSQWRy+SKJXKVVqjWa7U6IJ+vX6ckGIGGCjAYwm3LBQkJxOoCyWKzWJw2mgCu0q1DKAAtDsdNjANaEQAEAG7UPza9YbPWhYDkPwAdz2GqgUTatForsu4y9t2gPEeWBw+CIJFItGoAWkvxsAPuvDIYYjEohM3QUIUMJUaRxeK8YnE3NT8iUmZpuPcuYkCekcDKUGAAJgWhQQgAzNT0mWkHWUJgzEgYEJKGVaC1CSFNgBSXQAWgnQVnsgnUQAXBPNKuWhsPFANn42nbDsl6X1GcVShUavUmq0OqHw5HeQMhkWReM74nhCnpNuC9JZXBllWUUhAARm3ECjnWMCoDiSCTjibdYJ1BCoDbK4mCAA#ts/PQKgUABFEIIDZwgewGYQC4AsCWBnCeEAhgMYkCmuu2ARnORAOZxI1EICeBAdhjvgAU4RDowBOSAK7cAJgDowkaNgC2AByRj0EEMXy4AjohQSVEAEQABQ5OwJgNu3HMBuJVFUatOvRENxsdHIAZggTJDMrR3t-QJCAWhoJAHdccjFXdwgZchJhMQYSJG5cbQ0kRAAuPwM44LkBJAq3EGBFIpLtSTSxCABeGrg5dCI6cgAKc2708wBKLLkiGRkAYQrJFRLxgG8s6AIZCGr-ORl0ACFsRgBJbnQAZSvuchlx2YAaPehpsW4iFQYxyMp3QADUiGIVpgIeMAEwAVnhHyyAF95vs5Gl0DBJOgkLcSAUAXdxkU4BsSv0AHwQMkU3BybAyWZufZgDqlCA0JoAa36g2Go3ok25SB5cwWS1W602uB2Xw8hyBQzOlxud0ejGer2R+326EC9COArO4Mh0LEcMRuugaIWWJxeIJRPIJLpsuptJlJUZzNZ0HZxU5BSW-JOIzGkxDMglGKla3Jsvleu+PWuSpNFyutweTxeb0+Kagop56eNJ1V2Y1eZ1haL0Zg2mVIIAIkQggAVVQTYI2qB2jFYgRiVQQjgAaXIHFJ3vwfRpAG0FV7Ez6fum6yn3T6SxusgBdFlZMDlIakAy2ArjIi4DjcEgQGfcZ4kA3FWae3b7YDAISkBjsIgMjtqMN6FIB+DYCUTIMJg6TkFkHLaCkc7EMkRCBIMy5yOEKjjNG6JFoyz7pAAUkgUHjMu+w-JuRZQNuc40ic5AGFR9H0Yxcg-L6dEcdAXHRtxaYyNR0CESmEl6sRzxiORlFicWvJ8UWjGeixbGKXqXElrxWn7IJ5BLHIu6ifxUBSfslnQJi5D0K+M6rkxEBLuZK70sJ6Seb8-zkCpW6ziZvLDIaflaYZxkNug-kQIe2GaDkYjnNOanzi54WBTxTKLLgJAFhlTlBWKvo5XlfZ6nF9E4eQ6AkJg8BwE+L5vtwR4GUGFTkHILCMFGSCpOY7wQChR5om4QA#post-ts/MoUQMiDCAqAEBUsBiAlA8gWVgIgK4GcBTAJ2wG4AoC0CGBZdLbAIwHtWBrcqmqORVJhzFCAQwAm3auD4UAkARIA7UQFtCAGnkAXAJbaANpvkiJAQW0VBGedlOSKASQByzkClgApNC9uLSFGjOfkSkAHS64rAAvMJikmH+juJOru5ePsFyLOxcgVk5nNgRUbF28cVsnMmBKAAi6QBCAJohJMWRsGbAkFrZVVwlXT1kQA) + + We had to use the `.innerJoin()` function with a custom `ON` clause specified. + ++ [Code Sample for `entityName + "Id"`](https://anyhowstep.github.io/tsql-sqlite3-browser/test-playground/public/#pre-ts/CIJQ8gCgBAKgggIQDIFEoEkBiUUA10DKMBUARAK4DOApgE6kDcAUAMIgpwxrzJoU30oACiZQoASCp10AEwwA5LgHEUIKBBDoAsnBABNKAGkUBuAFUYYdPLYotKRVHlgYTs0iQAaURKm0AdgCGALbUUABquiwAErpCAEwArIkAlE4ubh5MKcxMAA60gQDmwYFQAC6BAEYANtQA+gAeAJb+AGYA9kL8dKQ5TEzWBKqu1pZQTOI9gkJ+QaFpTJFIZigkk0IA5HA1zQDG1Jsp3uJbCB1VR8ziTKCQsIioGNh4hMRkVR0dANaMrOycbiPPifH6kYQ+cSg76yBTKVTqTQ6fRGExQcyWay2eyOZyueTuLyQ8rNcp1CJRWIgBLJNJ4zJIbK5ArFUoVap1JqtTrdaF9XJDEZwsATKZ84QksnURbLVbrU6bLSBPZVajlAAWRxOWxg6rCIECADdqP4tRtNrqwsByP4AO77dVQaIdWi0F1XSaeu7QHhPLA4fBEEikWjUQIyP62QEPXhkUPh8EiMSSASwsYoFRqekEjzeZPQtOKDMI7OEvMSeMyODlKDAQEwbQoIQAZjpGRzSFrKEw5iQMCElHKtDaJNCWwApHoALTj4IzuTj6IALnHWhXbU2nigm38HVtRxSTIGLJKZUqtQaLXaXRDYYj-UG8mGIFGihFk1vCeEflkW4LMhlOAVjWUUhAARi3MDjg2CCoHiaDTniLd4O1JCoFba4mCAA#ts/PQKgUABFEIIDZwgewGYQC4AsCWBnCeEAhgMYkCmuu2ARnORAOZxI1EICeBAdhjvgAU4RDowBOSAK7cAJgDowkaNgC2AByRj0EEMXy4AjohQSVEAEQABQ5OwJgNu3HMBuJVFUatOvRENxsdHIAZggTJDMrR3t-QJCAWhoJAHdccjFXdwgZchJhMQYSJG5cbQ0kRAAuPwM44LkBJAq3EGBFIpLtSTSxCABeGrg5dCI6cgAKc2708wBKLLkiGRkAYQrJFRLxgG8s6AhpsQBJGQhq-zkZdAAhbEYj7nQAZTvuchlx2YAaPehD7iIKgY5yMl3QADUiGIVpgoeMAEwAVkR3yyAF95vs5Gl0DBJOgkA8SAUgY9xkU4BsSv0AHwQClU3ByQ4nWZufZgDqlCA0JoAa36g2Go3ok15SD5cwWS1W602uB2vyg4r5JzOQqut3ujxejDeH1R+326EC9HVFyukOhsLECORhugGIWOLxBKJJPIZIZ8tp9LlJTkKtZ7OgnOK3IKS0FFxGY0mkZkUqxMrWlPliqNfx6apBQ01dwez1e70+P0zyv5OY1NwLOuLBrL5YTMG0ubBABEiEEACqqCbBB1QJ1YnECMSqKEcADS5A45P9+D6dIA2kq-WmAyyZI3M96A0Ht1kALpsrJgcpDUgGWwFcZEXAcbgkCDz7hvEgm4qzX27fbAYBCKQDDsIgMhdqM96FCB+DYCU2A5BAmDpOQWRctoKSLsQyREIEgxrnI4QqOMCaYuWciwW8YgAFJILBACq1DcIwY4TmI06zuMa7GiKlC+rG9BMgmO7llAhxrqRmbkW+6Q0fRjHMeOKiTjOc5cdA-G8UuGA8YJ5BLMJIkquJ+FpPQH7zhui4rmpUB7kyhzMj0AJAgZ5Z2YG-LDKa5CubuC5yAmAV6TILa+RAJ74ZoORiNcc52b6q4ifs7kOVuiy4CQpY2eujIeRKeWqvI96ZYORoRSJBHkOgJCYPAcCvu+n7cKeyXhhU5ByCwjDxkgqTmF8EAYaeGJuEAA#post-ts/MoUQMiDCAqAEBUsBiAlA8gWVgIgK4GcBTAJ2wG4AoC0CGBZdLbAIwHtWBrcqmqORVJhzFCAQwAm3auD4UAkARIA7UQFtCAGnkAXAJbaANpvkiJAQW0VBGedlOSKASQByzkClgApNC9uLSFACqwC4A4rAAFP6O4gCUTq7uXj7Otmyc2EEhzuER6Rwx8WgoACJJAEIAmn5EpAB00eKwZsCQWnIs7Fx1+THNrWRAA) + + The `.innerJoinUsingPrimaryKey()` convenience function makes joins easier, and safer, to write. + +----- + +### `.setAutoIncrement()` + +An auto-increment column has a unique value generated for it when a new row is inserted (if no value is explicitly assigned). + +```ts +import * as sql from "@squill/squill"; + +const myTable = sql.table("myTable") + .addColumns({ + myTableId : sql.dtBigIntSigned(), + title : sql.dtVarChar(255), + }) + .setAutoIncrement(columns => columns.myTableId); +``` + +[Code Sample](https://anyhowstep.github.io/tsql-sqlite3-browser/test-playground/public/#pre-ts/CIJQ8gCgBAKgggIQDIFEoEkBiUUA10DKMBUAtgJ4wCGARgDYCmA3AFADCIKcMa8yaFavQZQAFCyhQAkINqN0AEwwA5HgHEUIKBBDoAsnBABNKAGkUJuAFUYYdMo4o9KVVGVgYbq0iQAaCdIALgCWgYxQAGqGbAAShqIATACsSQCUbh5ePiyprCwADgBOVADmpFRQgXIMAPoAHsEAdgBmAPaissK5LCz2BJqe9rZQLDKU1WIhYQzpLFFIVigko6IA5DEMdHStvlAA7q2FdAqruUA#ts/PQKgUABFEIIDZwgewGYQC4AsCWBnCeEAhgMYkCmuu2ARnORAOZxI1EICeBAdhjvgAU4RDowBOSAK7cAJgDowkaNgC2AByRj0EEMXy4AjohQSVEAEQABQ5OwJgNu3HMBuJVFUatOvRENxsdHIAZggTJDMrR3t-QJCAWhoJAHdccjFXdwgZchJhMQYSJG5cbQ0kRAAuPwM44LkBJAq3EGBFIpLtFQ4AFSI6BgBeGrg5dH76AApzbr6B8wBKLLkiGRkAYQrJFRLJgG8s6AhZifIASRkIav85GXQAIWxGM+50AGUn7nIZSYWAGkO0HQgXoVxGt3QADUiGJ1pgYZMAEwAVmR-yyAF8lkc5Gl0DBJOgkC8SAUVORXpMinBtiUIIMAHwQam03ByE4DC4LNxHMDlUakAy2AqTIi4DjcEgQKnFL4kYHFBb0pkHI7AYBCUgMdiIGREcZsNLMnX4bAlbA5CCYdLkLIdUo8NJab4AJSQyXpxGSRECx16pzkZqd+NkADFyOgSJhJoCoB05QruACjkdVSn08D0KDquZ7hxyH8IMlNHAZOZk+mIBisty7cVcBVyHIWIxpkH0kEZG7kuXHR3Xe7a3XOhAUgBGT1Eb2+jn0WMQOTJa0FACiBgEYlUMI4AGlyBx9vOjrPzpdqo9npSx+jK1XsZW5CgI1GAPJfGXcBPYRU86D2xvNkgrbmOOvbjkORz2toKQAJwAAxwROwxTj6XT+gM86Lsu5BrhuW5iLu+6Hrex7ofQFxgheLzoJM8GITelZYphT6Rpgb7kB+X6KphmgAKqyOQKBmt8vy-nG9YAS20ywQhY5ge6dHXm4YBYm4QA#post-ts/MoUQMiDCAqAEBUsBiAlA8gWVgWwJ7QEMAjAGwFMBuIA) + +----- + +### `.setPrimaryKey()` + +```ts +import * as sql from "@squill/squill"; + +const pageOfBook = sql.table("pageOfBook") + .addColumns({ + bookId : sql.dtBigIntSigned(), + pageNumber : sql.dtBigIntSigned(), + content : sql.dtLongText(), + }) + .setPrimaryKey(columns => [ + columns.bookId, + columns.pageNumber, + ]); +``` + +[Code Sample](https://anyhowstep.github.io/tsql-sqlite3-browser/test-playground/public/#pre-ts/CIJQ8gCgBAKgggIQDIFEoEkBiUUA10DKMBUADgIYDmApmAGYID2jA1gNwBQAwiCnDGnjI0FGvSasoACg5QoASABGzFugAmGAHICA4ihBRNYGIYCqSJABpZC0dU0BXALaLqAJy279h42YvW5eQBjRgA7ABdqCKgkME0dWDwTI2TzKxt5CBB0AFk4EABNKABpFCKpZVZ1SzIqe2dXNwBKDibODlI3KidyKHDyRQAbagB9AA8AS1C6Rik7cRU2jg50TQJ9E1WYMA55eYYVaUrVNRq7Rxd3GpCIqPCWgDU4JFMUAl2ZeXkAdl-reUCADZgf9AgByCDkNxOagAZ3IoSgAAtyLCoIoHOEAJ5uCZBKDkIITNRg3ZtIA#ts/PQKgUABFEIIDZwgewGYQC4AsCWBnCeEAhgMYkCmuu2ARnORAOZxI1EICeBAdhjvgAU4RDowBOSAK7cAJgDowkaNgC2AByRj0EEMXy4AjohQSVEAEQABQ5OwJgNu3HMBuJVFUatOvRENxsdHIAZggTJDMrR3t-QJCAWhoJAHdccjFXdwgZchJhMQYSJG5cbQ0kRAAuPwM44LkBJAq3EGBFIpKyokZyAHkUACEmgGsIAF4auDl0IjpyAApzNW6+wZHzAEosuSIZGQBhCskVEvmAbyzoCBoRgEkZCGr-ORl0AexGW+50AGUP7nIMnmGwANJdoMsegA5Y40dKPSYvN4fL6-f6A4Fgq5XDpBb4I56vAAyxUYABVyAAPdCYrIAXy2VzkaXQAjEqiIYg4AGlyBx5kU4McSuMAHwQADa4KgguFuDkNyQw3uWOxMqOJ3lkPIMJUcLEqqgAF0Nm4wOUpqQDLYCvMiLgONwSBABcUASR0NhihsxRALldgMAhKQGOxEDIiDM2GkICQw-hsCVsDkIJh0uQsh1Sjw0lpAQAlJDJcbEZJEQIQbX9IZKuSJ3PoGCyABi5HQJEw82lsbduU9xUN2P9auxiuVD2q70+33mABYAEyg7tXbW6-UIqeo+YANgAnEuR9jceR8dVzCSCmZsGpcMdzIOrnSsqbM8VcBVyHIWIxFvX0kEZELZJ7xzf8CyLF9X06CAUgAdnggB9bdkJLIgywrKs1iVbs5GSNMCgAUQMNkOS5Xl+WHQ8oDHe4NxRGd4Ngg8qKgVdYXhSd6JpZDt2YtUGRwlA2w7XoAVdbh3X7bgXxxN8Py-JAf3MODEJ4kCVNgpDkMg2ToJSAARJBKChJB0AIyk8G0CY0PLLoemrEYcLw9MiJIlROR5PlzmXaAaInCBNxnXcAAZgoARj4qi2L1DiAq4+Zgsix9GRHOQhPbTBRIWDpJK9aScM0ABVWRyBQRMMRk6As3k79FgMozcBMsyLNKdSi0M4zTPMyyXwZNwgA#post-ts/MoUQMiDCAqAEBUsBiAlA8gWVgBwIYHMBTNAMwCEB7CgawG4g) + +----- + +### `.enableExplicitAutoIncrementValue()` + +This library has a strong opinion that you should not explicitly set the value of auto-increment columns, +for INSERT and UPDATE statements. + +This opinion is enforced, by default. + +[Code Sample](https://anyhowstep.github.io/tsql-sqlite3-browser/test-playground/public/#pre-ts/CIJQ8gCgBAKgggIQDIFEoEkBiUUA10DKMBUAtgJ4wCGARgDYCmA3AFADCIKcMa8yaFavQZQAFCyhQAkINqN0AEwwA5HgHEUIKBBDoAsnBABNKAGkUJuAFUYYdMo4o9KVVGVgYbq0iQAaCdIALgCWgYxQAGqGbAAShqIATACsSQCUbh5ePiyprCwADgBOVADmpFRQgXIMAPoAHsEAdgBmAPaissK5LCz2BJqe9rZQLDKU1WIhYQzpLFFIVigko6IA5DEMdHStvlAA7q2FdAqruUA#ts/PQKgUABFEIIDZwgewGYQC4AsCWBnCeEAhgMYkCmuu2ARnORAOZxI1EICeBAdhjvgAU4RDowBOSAK7cAJgDowkaNgC2AByRj0EEMXy4AjohQSVEAEQABQ5OwJgNu3HMBuJVFUatOvRENxsdHIAZggTJDMrR3t-QJCAWhoJAHdccjFXdwgZchJhMQYSJG5cbQ0kRAAuPwM44LkBJAq3EGBFIpLtFQ4AFSI6BgBeGrg5dH76AApzbr6B8wBKLLkiGRkAYQrJFRLJgG8s6AhZifIASRkIav85GXQAIWxGM+50AGUn7nIZSYWAGkO0HQgXoVxGt3QADUiGJ1pgYZMAEwAVmR-yyAF8lkc5Gl0DBJOgkC8SAUVORXpMinBtiUIIMAHwQam03ByE4DC7Y6DAYByCmnACiAA81AESIECUSSWSKVD2JJyL9lqsZPA4ABZQmnX5uI5gcqjUgGWwFSZEXAcbgkCBU4pfEjA4oLelMg5HXlCUgMdiIGREcZsNLM334bAlbA5CCYdLkLJEZJEQLHXqnOThtJaGCyABi5HQJEwk0BUA6Dqd3ABRw9wE26js5EFYgkYhLEHd1c7HPoFzBj2elIAnMP0Z3O8D0KDquZ7hxyH8IMlNHAZOYq2OMVkFnroPHE8nu3GxxA5MkYwVBQYBGJVDCOABpcgcfZto6H3vVfsvdCTYeD0cbtynZyJIaj+kExbHkcZa5BW65QRAvJ1moDZNi2r7QCyOz4Iy7YYZ2BToJIYi8B2CHHu+lyfk836-gADHRACMAHkWOE5TuCHQkAGkGseR5gAKpgQG3zTgu+F8VhJRjCCR58Z2LF8RiO4IZux7bmAWJuEAA#post-ts/MoUQMiDCAqAEBUsBiAlA8gWVgWwJ7QEMAjAGwFMBuIA) + +----- + +However, you may force the library to allow it, +```ts +import * as sql from "@squill/squill"; + +const myTable = sql.table("myTable") + .addColumns({ + myTableId : sql.dtBigIntSigned(), + title : sql.dtVarChar(255), + }) + .setAutoIncrement(columns => columns.myTableId) + .enableExplicitAutoIncrementValue() + //This allows all columns to be modified with UPDATE statements + .addAllMutable(); +``` + +[Code Sample](https://anyhowstep.github.io/tsql-sqlite3-browser/test-playground/public/#pre-ts/CIJQ8gCgBAKgggIQDIFEoEkBiUUA10DKMBUAtgJ4wCGARgDYCmA3AFADCIKcMa8yaFavQZQAFCyhQAkINqN0AEwwA5HgHEUIKBBDoAsnBABNKAGkUJuAFUYYdMo4o9KVVGVgYbq0iQAaCdIALgCWgYxQAGqGbAAShqIATACsSQCUbh5ePiyprCwADgBOVADmpFRQgXIMAPoAHsEAdgBmAPaissK5LCz2BJqe9rZQLDKU1WIhYQzpLFFIVigko6IA5DEMdHStvlAA7q2FdAqruUA#ts/PQKgUABFEIIDZwgewGYQC4AsCWBnCeEAhgMYkCmuu2ARnORAOZxI1EICeBAdhjvgAU4RDowBOSAK7cAJgDowkaNgC2AByRj0EEMXy4AjohQSVEAEQABQ5OwJgNu3HMBuJVFUatOvRENxsdHIAZggTJDMrR3t-QJCAWhoJAHdccjFXdwgZchJhMQYSJG5cbQ0kRAAuPwM44LkBJAq3EGBFIpLtFQ4AFSI6BgBeGrg5dH76AApzbr6B8wBKLLkiGRkAYQrJFRLJgG8s6AhZifIASRkIav85GXQAIWxGM+50AGUn7nIZSYWAGkO0HQgXoVxGt3QADUiGJ1pgYZMAEwAVmR-yyAF8lkc5Gl0DBJOgkC8SAUVORXpMinBtiUIIMAHwQam03ByE4DC7Y6ByCmnACiAA81AESIECUSSWSKVD2JJyL9lqsZPA4ABZQmnX5uI5gcqjUgGWwFSZEXAcbgkCBU4pfEjA4oLelMg5HYDAISkBjsRAyIjjNhpZk+-DYErYHIQTDpchZIjJIiBY69U5yMNpLQwWQAMXI6BImEmgKgHTtDu4AKObuAAHkANLFiCuqstjn0C5gx7PSkATj76JbLeB6FB1XM9w45D+EGSmjgMnMlcHGKyCx10DjCaTbdjg4gcmS0YK-IMAjEqhhHDr5A4+0bRx3HeqXZe6EmfZ7A+X3Jbckkaj9IIiz3I5S1ycslxAiB3Xre9oBZHZ8EZJs4JbAp0EkMReGbKC90fS5nyeV93wABhIgBGL9cMHYdR3BDoSH9YDqNw8wAFUAP9b4x2nVCWIQkoxhBXcWJbKiWIxdcoJXPc1zALE3CAA#post-ts/MoUQMiDCAqAEBUsBiAlA8gWVgWwJ7QEMAjAGwFMBuIA) diff --git a/squill-doc/table-declaration/table-constructor.md b/squill-doc/table-declaration/table-constructor.md new file mode 100644 index 00000000..38becee8 --- /dev/null +++ b/squill-doc/table-declaration/table-constructor.md @@ -0,0 +1,24 @@ +### Table constructor + +To declare a table, + +```ts +import * as sql from "@squill/squill"; + +/** + * `"myTable"` is the alias of the table in our schema. + */ +const myTable = tsql.table("myTable"); +``` + +A `@squill/squill` table is an immutable data structure. + +A method that appears to modify properties of the table actually returns a new table instance, and does not modify the original table instance. + +----- + +We have a table now, but a table without columns is not very useful. + +----- + +We should [add columns](add-columns.md) to the table, next.