From 4a656a6ad9361f5669c1a60eb97d864661a74d1d Mon Sep 17 00:00:00 2001 From: James Arthur Date: Mon, 4 Sep 2023 11:39:41 +0200 Subject: [PATCH] docs: clearer docs on data types, constraints and limitations. (#396) Firstly this adds explicit pages in usage/data-modelling on: - data type support - constraints Then it goes around and tidies up the various copy around limitations. --- README.md | 2 +- clients/typescript/src/migrators/bundle.ts | 2 +- docs/api/ddlx.md | 12 +-- docs/examples/linear-lite.md | 2 +- docs/integrations/backend/index.md | 6 -- docs/integrations/frontend/index.md | 2 +- docs/integrations/frontend/solid.md | 4 +- docs/integrations/frontend/svelte.md | 4 +- docs/integrations/frontend/vue.md | 4 +- docs/reference/{limitations.md => roadmap.md} | 68 ++++++--------- docs/top-level-listings/usage.md | 2 +- docs/usage/auth/index.md | 12 ++- docs/usage/data-access/shapes.md | 8 +- docs/usage/data-modelling/_validation.md | 14 --- docs/usage/data-modelling/constraints.md | 87 +++++++++++++++++++ docs/usage/data-modelling/electrification.md | 14 +-- docs/usage/data-modelling/index.md | 14 ++- docs/usage/data-modelling/migrations.md | 22 ++--- docs/usage/data-modelling/permissions.md | 10 +-- docs/usage/data-modelling/types.md | 42 +++++++++ docs/usage/data-modelling/validation.md | 16 ++++ 21 files changed, 224 insertions(+), 123 deletions(-) rename docs/reference/{limitations.md => roadmap.md} (68%) delete mode 100644 docs/usage/data-modelling/_validation.md create mode 100644 docs/usage/data-modelling/constraints.md create mode 100644 docs/usage/data-modelling/types.md create mode 100644 docs/usage/data-modelling/validation.md diff --git a/README.md b/README.md index 2282284e..eab9f30f 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ CI License - Apache 2.0 - Status - Alpha + Status - Alpha Chat - Discord diff --git a/clients/typescript/src/migrators/bundle.ts b/clients/typescript/src/migrators/bundle.ts index c29dc0bb..ae1a129a 100644 --- a/clients/typescript/src/migrators/bundle.ts +++ b/clients/typescript/src/migrators/bundle.ts @@ -12,7 +12,7 @@ import { data as baseMigration } from './schema' import Log from 'loglevel' import { SatelliteError, SatelliteErrorCode } from '../util' -export const SCHEMA_VSN_ERROR_MSG = `Local schema doesn't match server's. Clear local state through developer tools and retry connection manually. If error persists, re-generate the client. Check documentation (https://electric-sql.com/docs/reference/limitations) to learn more.` +export const SCHEMA_VSN_ERROR_MSG = `Local schema doesn't match server's. Clear local state through developer tools and retry connection manually. If error persists, re-generate the client. Check documentation (https://electric-sql.com/docs/reference/roadmap) to learn more.` const DEFAULTS: MigratorOptions = { tableName: '_electric_migrations', diff --git a/docs/api/ddlx.md b/docs/api/ddlx.md index 8acb1d67..8780f49c 100644 --- a/docs/api/ddlx.md +++ b/docs/api/ddlx.md @@ -5,16 +5,16 @@ description: >- sidebar_position: 10 --- -:::caution Limitations -The syntax and features described in this page are **not yet implemented**. - -Currently, DDLX rules are limited to [electrification by SQL procedure call syntax](../reference/limitations#ddlx-rules). See the [Limitations](../reference/limitations.md) page for more context. -::: - ElectricSQL extends the PostgreSQL language with the following DDLX statements. Use these in your [migrations](../usage/data-modelling/migrations.md) to [electrify tables](../usage/data-modelling/electrification.md) and expose data by granting [permissions](../usage/data-modelling/permissions.md) to roles and assigning roles to [authenticated](../usage/auth/index.md) users. +:::caution Work in progress +The syntax and features described in this page are not fully implemented. + +Currently, DDLX rules are limited to [electrification by SQL procedure call syntax](../reference/roadmap#ddlx-rules). See [Roadmap -> DDLX rules](../reference/roadmap.md#ddlx-rules) for more context. +::: + ## Electrification Tables must be [electrified](../usage/data-modelling/electrification.md) to include them in the replication machinery. diff --git a/docs/examples/linear-lite.md b/docs/examples/linear-lite.md index 10aca0be..5a8a0ddb 100644 --- a/docs/examples/linear-lite.md +++ b/docs/examples/linear-lite.md @@ -3,7 +3,7 @@ title: LinearLite description: Local-first project management app, based on a simplified Linear clone. --- -:::caution Limitations +:::caution Work in progress We haven't published this example yet. Check back soon for an online demo. ::: diff --git a/docs/integrations/backend/index.md b/docs/integrations/backend/index.md index 34461149..8f21f41c 100644 --- a/docs/integrations/backend/index.md +++ b/docs/integrations/backend/index.md @@ -5,16 +5,10 @@ sidebar_position: 30 import DocCardList from '@theme/DocCardList' -:::caution Limitations -See for current limitations on data modelling and migrations. -::: - ElectricSQL is designed to work with [any Postgres-backed system](../../usage/installation/postgres.md). You don't need a specific ([or, in fact, any](./other.md)) backend framework to use Electric. However, it's common to manage the Postgres data model using a migrations system. These are often provided by your web framework. Because ElectricSQL's [DDLX Rules](../../api/ddlx.md) are applied using DDL migrations, this section shows you how to do this using some popular frameworks. -:::note Some frameworks also provide or work with Postgres change data capture tooling, such as logical replication consumers. This can be useful for [Event sourcing](../event-sourcing/index.md). -::: diff --git a/docs/integrations/frontend/index.md b/docs/integrations/frontend/index.md index ba7f0b56..a0068e88 100644 --- a/docs/integrations/frontend/index.md +++ b/docs/integrations/frontend/index.md @@ -9,7 +9,7 @@ ElectricSQL is designed to integrate with existing reactivity and component fram This allows you to bind [live queries](../../usage/data-access/queries.md) to component state and hook into data and connectivity change events. -:::caution Limitations +:::caution Work in progress ElectricSQL currently only has official support for React (both ReactJS and React Native). If you're interested in helping to develop Solid, Svelte, Vue or any other frontend framework integrations [let us know on Discord](https://discord.electric-sql/com). diff --git a/docs/integrations/frontend/solid.md b/docs/integrations/frontend/solid.md index 444816a0..700635b5 100644 --- a/docs/integrations/frontend/solid.md +++ b/docs/integrations/frontend/solid.md @@ -5,8 +5,8 @@ description: >- sidebar_position: 20 --- -:::caution Limitations -SolidJS support is not yet implemented. See for context. +:::caution Work in progress +SolidJS support is not yet implemented. [Let us know on Discord](https://discord.electric-sql/com) if you're interested in helping to develop SolidJS support. ::: diff --git a/docs/integrations/frontend/svelte.md b/docs/integrations/frontend/svelte.md index b5a26598..a915717f 100644 --- a/docs/integrations/frontend/svelte.md +++ b/docs/integrations/frontend/svelte.md @@ -5,8 +5,8 @@ description: >- sidebar_position: 30 --- -:::caution Limitations -Svelte support is not yet implemented. See for context. +:::caution Work in progress +Svelte support is not yet implemented. [Let us know on Discord](https://discord.electric-sql/com) if you're interested in helping to develop Svelte support. ::: diff --git a/docs/integrations/frontend/vue.md b/docs/integrations/frontend/vue.md index 64fdd693..7d849897 100644 --- a/docs/integrations/frontend/vue.md +++ b/docs/integrations/frontend/vue.md @@ -5,8 +5,8 @@ description: >- sidebar_position: 40 --- -:::caution Limitations -Vue.js support is not yet implemented. See for context. +:::caution Work in progress +Vue.js support is not yet implemented. [Let us know on Discord](https://discord.electric-sql/com) if you're interested in helping to develop Vue.js support. ::: diff --git a/docs/reference/limitations.md b/docs/reference/roadmap.md similarity index 68% rename from docs/reference/limitations.md rename to docs/reference/roadmap.md index 41c0d360..78e8b5be 100644 --- a/docs/reference/limitations.md +++ b/docs/reference/roadmap.md @@ -1,31 +1,40 @@ --- -title: Limitations +title: Roadmap description: >- Summary of the maturity stage of the project and known limitations. --- ElectricSQL is in public alpha phase. -:::caution APIs are not guaranteed to be stable. Backwards incompatible changes may (and will) be introduced in both minor and major version releases. -Key aspects of the system *as currently documented* are not fully implemented yet, as outlined on this page. -::: - ## Practical limitations -Key aspects of the system are not yet implemented, including: +Key aspects of the system are not fully implemented yet: -1. [DDLX rules](#ddlx-rules) — SQL syntax, permissions and validation are not supported -2. [Shapes](#shapes) — currently limited to whole table sync -3. [Data modelling](../usage/data-modelling/index.md) — limited data types and constraint support -4. [Failure modes](#failure-modes) — you may need to workaround in development +1. [Data modelling](#data-modelling) — limited data types and constraints +2. [DDLX rules](#ddlx-rules) — limited to electrification with proceedure call syntax +3. [Shapes](#shapes) — currently limited to whole table sync -### DDLX rules +Plus you may encounter [failure modes](#failure-modes) that you need to work around in development + +### Data modelling + +There are a number of [fundamental limitations](#fundamental-limitations) of the local-first model you should be aware of. These have a practical impact on data model support, for example: -The SQL syntax you see documented on is not yet implemented. Neither are permissions, roles, validation or local SQLite commands. +- **primary keys**: sequential IDs are not supported; you [must use binary UUIDs](../usage/data-modelling/types.md#primary-keys) + +In addition, there are a number of limitations of the current implementation that impact data model support: + +- **data types**: see the list of [supported data types](../usage/data-modelling/types.md#supported-data-types) +- **constraints**: you must remove [unique and check constraints](../usage/data-modelling/constraints.md#unsupported) +- **migrations**: you must use [additive, forward migrations](../usage/data-modelling/migrations.md#limitations) + +See for more information. + +### DDLX rules -DDLX support is currently limited to electrifying tables using an SQL procedure call syntax: +The SQL syntax you see documented on is not yet implemented. Neither are permissions, roles, validation or local SQLite commands. DDLX support is currently limited to electrifying tables using an SQL procedure call syntax: ```sql CALL electric.electrify('items') @@ -35,9 +44,7 @@ You can track progress on DDLX support here [electric-sql/pg_proxy/pulls](https: ### Shapes -[Shape-based sync](../usage/data-access/shapes.md) using the [`sync()` function API](../api/clients/typescript.md#sync) currently only supports whole table sync. - -There is no support for `where` clauses to filter the initial target rows or `select` clauses to filter the include tree. As a result, current calls to `db.tablename.sync({...})` will "over sync" additional data onto the device. +[Shape-based sync](../usage/data-access/shapes.md) using the [`sync()` function](../api/clients/typescript.md#sync) currently supports whole table sync. There is no support for `where` clauses to filter the initial target rows or `select` clauses to filter the include tree. As a result, current calls to `db.tablename.sync({...})` will "over sync" additional data onto the device. :::note There is one temporary feature to filter data onto the local device: set an `electric_user_id` field on your table. If you do, then rows will only be synced if the value of that column matches the value of the authenticated user_id provided in your [auth token](../usage/auth/index.md). @@ -45,32 +52,13 @@ There is one temporary feature to filter data onto the local device: set an `ele This is a very temporary workaround and will be removed soon! ::: -### Data modelling - -We don't currently support any constraints except primary keys. You must remove all unique and check constraints from your Postgres data model. - -We have limited data type support. Currently, we only support strings (`text` and non-length-limited `varchar`) and numbers (`smallint`, `integer`, `bigint`, `double precision`). The authoritative list of supported data types is maintained in the [`supported_pg_types/0` function][1]. - -We also only support forward and additive migrations. Migrations that remove columns or make them more restrictive will fail when applied to electrified tables. - -[1]: https://github.com/search?q=repo%3Aelectric-sql%2Felectric+symbol%3Asupported_pg_types&type=code - ### Failure modes -Currently, you are likely to experience bugs or behaviour that leads to an inconsistent data state. This is **not** related to the core [consistency model](./consistency.md). It's a consequence of the maturity of the implementation. - -If you experience errors like: - -- `Migrations cannot be altered once applied` -- `Cannot catch up to the server's current state` -- `FOREIGN KEY CONSTRAINT failed` - -You may need to reset your databases. This involves: +Currently, you may experience bugs or behaviour that leads to an inconsistent data state. This is **not** related to the core [consistency model](./consistency.md). It's a consequence of the lack of validation and some recovery modes still pending implementation. -- wiping your client databases by clearing IndexedDB in the browser -- resetting your Potsgres database +In development, you can usually recover from these bugs by resetting your database(s). In the browser, if you clear localStorage and IndexedDB (for example in Chrome, "Inspect" to open the developer tools -> Application -> Storage -> Clear site data) that will reset the client and your local app will re-sync from the server. -To reset your Postgres database, you may need to drop the replication publication. This requires: +If you need to re-set your Postgres database, if you're using Docker Compose (such as with the starter template or examples) you can usually use something like `yarn backend:down` or `docker compose -f backend/compose.yaml down --volumes`. Alternatively, if you can't just nuke your whole database folder, you may need to drop the replication publication manually: ```sql ALTER SUBSCRIPTION postgres_1 DISABLE; @@ -82,7 +70,7 @@ You can then recreate your database, e.g.: ```shell dropdb -f intro -createdb -T template0 -E UTF-8 intro +createdb -T template0 -E UTF-8 electric ``` Then: @@ -93,7 +81,7 @@ Then: Keep an eye on [electric-sql/electric/pulls](https://github.com/electric-sql/electric) for the latest bugfixes. -## Integrity limitations +## Fundamental limitations ElectricSQL uses a [rich-CRDT data model](./consistency.md#rich-crdts) that allows building local-first applications without falling into common pitfalls of working with eventually consistent databases. However, you still need to follow certain constraints that can’t be verified or enforced automatically by ElectricSQL. The purpose of this section is to document these constraints and why they are required. diff --git a/docs/top-level-listings/usage.md b/docs/top-level-listings/usage.md index a91d1d98..69876a06 100644 --- a/docs/top-level-listings/usage.md +++ b/docs/top-level-listings/usage.md @@ -12,7 +12,7 @@ This guide explains how to use ElectricSQL. It's broken down into four main sect ## See also See the [Integrations](./integrations.md) guide and the [API docs](./api.md). -You might also be interested in some of the [Reference](./reference.md) docs, such as the [Limitations](../reference/limitations.md) and [Architecture](../reference/architecture.md) pages. +You might also be interested in some of the [Reference](./reference.md) docs, such as the [Architecture](../reference/architecture.md) and [Roadmap](../reference/roadmap.md) pages.
diff --git a/docs/usage/auth/index.md b/docs/usage/auth/index.md index f7ee5502..13d19c79 100644 --- a/docs/usage/auth/index.md +++ b/docs/usage/auth/index.md @@ -40,12 +40,10 @@ Insecure mode is designed for development or testing. It supports unsigned JWTs If you have a backend for your app with a cookie-based login session mechanism already in place, we recommend creating an HTTP endpoint to generate one-off tokens for signed-in users and using that to obtain a fresh token before initializing the client. -## Limitations +
-We don't currently support unauthenticated use. +:::caution Work in progress +We don't currently support unauthenticated use, or changing the authentication state on an active replication connection. -We don't currently support changing the authentication state on an active replication connection. To work around this, you can either defer instantiating your client until the user authenticates, or you can [stop][1] and [start][2] the [satellite process][3] manually yourself. - -[1]: https://github.com/electric-sql/electric/blob/2e8bfdf4992d355d0b1928a097fe406d283303bf/clients/typescript/src/satellite/process.ts#L293 -[2]: https://github.com/electric-sql/electric/blob/2e8bfdf4992d355d0b1928a097fe406d283303bf/clients/typescript/src/satellite/process.ts#L167-L170 -[3]: https://github.com/electric-sql/electric/blob/2e8bfdf4992d355d0b1928a097fe406d283303bf/clients/typescript/src/satellite/process.ts +[Get in touch](https://discord.electric-sql.com) if this is a blocker or you need help with a workaround. +::: diff --git a/docs/usage/data-access/shapes.md b/docs/usage/data-access/shapes.md index 4afb3441..2a285ecf 100644 --- a/docs/usage/data-access/shapes.md +++ b/docs/usage/data-access/shapes.md @@ -5,16 +5,16 @@ description: >- sidebar_position: 30 --- -:::caution Limitations -Shapes are currently limited to whole-table sync. See the [limitations page](../../reference/limitations.md) for context. -::: - Shapes are the core primitive for controlling sync in the ElectricSQL system. Local apps establish shape subscriptions. This syncs data from the cloud onto the local device using the [Satellite replication protocol](../../api/satellite.md), into the local embedded SQLite database. Once the initial data has synced, [queries](./queries.md) can run against it. The [Electric sync service](../installation/service.md) maintains shape subscriptions and streams any new data and data changes onto the local device. In this way, local devices can sync a sub-set of a larger database for interactive offline use. +:::caution Work in progress +Shapes are currently limited to whole-table sync. See [Roadmap -> Shapes](../../reference/roadmap.md#shapes) for more information. +::: + ## What is a shape? A shape is a set of related data that's synced onto the local device. It is defined by: diff --git a/docs/usage/data-modelling/_validation.md b/docs/usage/data-modelling/_validation.md deleted file mode 100644 index 5c0531ba..00000000 --- a/docs/usage/data-modelling/_validation.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Validation -description: >- - How to validate user input (not currently supported). -sidebar_position: 60 ---- - -:::caution Limitations -User input validation is not currently supported. See for context. -::: - -## Notes - -Validation rules will be defined database side [using DDLX](../../api/ddlx.md). Logic will then be compiled to run both in the [Client](../data-access/client.md) and as part of the write authorisation step on the server. diff --git a/docs/usage/data-modelling/constraints.md b/docs/usage/data-modelling/constraints.md new file mode 100644 index 00000000..3452af74 --- /dev/null +++ b/docs/usage/data-modelling/constraints.md @@ -0,0 +1,87 @@ +--- +title: Constraints +description: >- + Constraints and invariants supported by the ElectricSQL system. +sidebar_position: 50 +--- + +Invariant support is currently limited to referential integrity and not-null constraints. Unique and check constraints are not yet supported. + +## Supported + +### Referential integrity + +ElectricSQL maintains referential integrity of foreign key references. So you can use foreign key relationships in your data model and rely on referential integrity: + +```sql +CREATE TABLE posts ( + id UUID PRIMARY KEY +); + +CREATE TABLE comments ( + id UUID PRIMARY KEY + + post_id UUID REFERENCES(posts.id) ON DELETE CASCADE +); +``` + +This works even when making writes locally in an offline database. See [Introduction -> Conflict-free offline -> Preserving data integrity](../../intro/offline.md#preserving-data-integrity) and the Rich-CRDT post on [Compensations](/blog/2022/05/03/introducing-rich-crdts#compensations) for more information. + +### Not-null constraints + +ElectricSQL supports [not-null constraints](https://www.postgresql.org/docs/current/ddl-constraints.html#id-1.5.4.6.6) as long as the constraint is defined when creating the column. + +I.e.: the not-null constraint must be defined in an [additive migration](./migrations.md#limitations). So the following is supported because creating the table with new columns is *additive*: + +```sql +CREATE TABLE items ( + -- implicit non null constraint + id UUID PRIMARY KEY + + -- explicit non null constraint + foo TEXT NOT NULL + + -- can be null + bar TEXT +) +``` + +Adding a column with a not-null constraint is supported because it's *additive*: + +```sql +ALTER TABLE items + ADD COLUMN baz TEXT NOT NULL; +``` + +Constraining an existing column by adding a not-null constraint to it is **not supported**: + +```sql +-- Not supported +ALTER TABLE items + ALTER COLUMN bar TEXT NOT NULL; +``` + +This is not supported because it may invalidate concurrent, in-flight operations. Specifically, writes that were accepted locally with null values would need to be rejected, which would violate the [finality of local writes](../../reference/architecture.md#local-writes). + +## Unsupported + +Unsupported constraints must be removed from a table before [electrifying](./electrification.md) it. + +### Check constraints + +ElectricSQL does not currently support [check constraints](https://www.postgresql.org/docs/current/ddl-constraints.html#DDL-CONSTRAINTS-CHECK-CONSTRAINTS). + +### Unique constraints + +ElectricSQL does not currently support [unique constraints](https://www.postgresql.org/docs/current/ddl-constraints.html#DDL-CONSTRAINTS-UNIQUE-CONSTRAINTS). + +
+ +:::caution Work in progress +We're working to support: + +- unique constraints [using Reservations](/blog/2022/05/03/introducing-rich-crdts#reservations) +- *single column* and then *multi-column* check constraints using validation + +See [Rich-CRDTs](/blog/2022/05/03/introducing-rich-crdts) for more information. +::: \ No newline at end of file diff --git a/docs/usage/data-modelling/electrification.md b/docs/usage/data-modelling/electrification.md index a1b80345..e566ef38 100644 --- a/docs/usage/data-modelling/electrification.md +++ b/docs/usage/data-modelling/electrification.md @@ -5,11 +5,15 @@ description: >- sidebar_position: 30 --- -:::caution Limitations -See the [limitations page](../../reference/limitations.md) for context. -::: +By default, ElectricSQL does not expose or replicate any data. + +In order to sync data between Postgres and local-devices, you have to first "electrify" tables to add them to the replication machinery. You can then [assign permissions](./permissions.md) to expose read and write access to the data. -By default, ElectricSQL does not expose or replicate any data. In order to sync data between Postgres and local-devices, you have to first electrify tables to add them to the replication machinery. Then you can [assign permissions](./permissions.md) to expose read and write access to the data. +You can only electrify tables with supported data types and constrainsts. See [Types](./types.md) and [Constraints](./constraints.md) for more information. + +:::caution Work in progress +Currently, electrification is supported by an [SQL procedure call syntax](../../reference/roadmap.md#ddlx-rules). +::: ## Enable @@ -40,7 +44,7 @@ Note that this will fail if you have any roles, permissions or other rules defin
-:::note +:::info Electrification on its own does not expose any data. It's like an extra security measure to make sure you only ever replicate data from tables you've explicitly enabled. In addition, tables that are not electrified are not included in the database schema that the client has access to. So sensitive information in the DDL schema itself (such as private dynamic table names) is not exposed unless explicitly enabled. diff --git a/docs/usage/data-modelling/index.md b/docs/usage/data-modelling/index.md index f1a34b8c..3dfc8443 100644 --- a/docs/usage/data-modelling/index.md +++ b/docs/usage/data-modelling/index.md @@ -5,17 +5,13 @@ sidebar_position: 20 import DocCardList from '@theme/DocCardList'; -:::caution Limitations -ElectricSQL is still in [early stage development](../../reference/limitations.md). Known limitations include: - -- [additive migrations](./migrations.md#additive-migrations) only -- limited [data types](./migrations.md#data-types) -- limited [constraints](./migrations.md#constraints) -- [DDLX rules](../../api/ddlx.md) limited to [electrification with function call syntax](../../reference/limitations.md#ddlx-rules) -::: - ElectricSQL syncs data between a [central Postgres and local-first apps](../../intro/active-active.md). The Postgres data model is used as the shared schema and the source of authorisation for what data is *allowed* to sync where. +:::caution Work in progress +We're currently working on permissions, validation and support for additional types and constraints. See the pages below and the [Roadmap](../../reference/roadmap.md) for more information. +::: + + diff --git a/docs/usage/data-modelling/migrations.md b/docs/usage/data-modelling/migrations.md index 22e06aab..9c37ad50 100644 --- a/docs/usage/data-modelling/migrations.md +++ b/docs/usage/data-modelling/migrations.md @@ -11,10 +11,6 @@ import CodeBlock from '@theme/CodeBlock'; import ExampleSchema from '!!raw-loader!./example.prisma'; import ExampleSQL from '!!raw-loader!./example.sql'; -:::caution Limitations -See the [limitations page](../../reference/limitations.md) for context. -::: - ElectricSQL is designed to work with and on top of a Postgres data model. If you don't have a data model you can create one using your preferred migrations tooling. You then use the same migrations tooling to extend your data model with [DDLX statements](./electrification.md) to expose data to the replication machinery. @@ -37,6 +33,10 @@ ELECTRIC GRANT SELECT TO ANYONE; ``` +:::caution Work in progress +See the [Limitations](#limitations) section below and the [Roadmap](../../reference/roadmap.md) page for more context. +::: + ## Creating a data model If you have your own Postgres-backed application, use the data model from that and continue using whatever method you're currently using to define the database schema. @@ -198,16 +198,6 @@ We only currently support forward migrations. Rollbacks must be implemented as f We only currently support additive migrations. This means you can't remove or restrict a field. Instead, you need to create new fields and tables (that are pre-constrained on creation) and switch / mirror data to them. -### Data types - -ElectricSQL maps between Postgres data types on the server and SQLite data types in the local app. This is not a perfect match. In many cases, SQLite does not have native support for a Postgres data type. However, our client libraries bridge the gap for the majority of Postgres types, providing a native JavaScript/TypeScript experience for any data type supported in electrified tables. - -We're actively working on expanding the range of Postgres data types ElectricSQL supports out of the box. - -### Primary keys - -We do not support sequential autoincrementing integer IDs. You must use binary UUIDs. - -### Constraints +### Data types and constraints -We support referential integrity. We do not currently support unique or check constraints. We plan to do so [using Rich-CRDTs](/blog/2022/05/03/introducing-rich-crdts). +See the pages on [Types](./types.md) and [Constraints](./constraints.md). diff --git a/docs/usage/data-modelling/permissions.md b/docs/usage/data-modelling/permissions.md index d2ebf267..fd53b50d 100644 --- a/docs/usage/data-modelling/permissions.md +++ b/docs/usage/data-modelling/permissions.md @@ -2,17 +2,17 @@ title: Permissions description: >- How to authorise data access by authenticated clients. -sidebar_position: 40 +sidebar_position: 60 --- import useBaseUrl from '@docusaurus/useBaseUrl' -:::caution Limitations -See the [limitations page](../../reference/limitations.md) for context. -::: - Once you've [electrified](./electrification.md) a table, you can grant and assign permissions to read and write the data in it using the [`GRANT`](../../api/ddlx.md#grant) and [`ASSIGN`](../../api/ddlx.md#assign) DDLX statements. +:::caution Work in progress +Permissions are not yet implemented. See the [Roadmap](../../reference/roadmap.md#ddlx-rules) for more information. +::: + ## 1. Grant permissions to roles Grant **permissions** to **roles** using the [`GRANT`](../../api/ddlx.md#grant) statement. diff --git a/docs/usage/data-modelling/types.md b/docs/usage/data-modelling/types.md new file mode 100644 index 00000000..7714702b --- /dev/null +++ b/docs/usage/data-modelling/types.md @@ -0,0 +1,42 @@ +--- +title: Types +description: >- + Data types supported by the ElectricSQL system. +sidebar_position: 40 +--- + +ElectricSQL syncs data between Postgres and SQLite. + +To do this, we map between [Postgres data types](https://www.postgresql.org/docs/current/datatype.html) and [SQLite data types](https://www.sqlite.org/datatype3.html). In addition, we validate [local writes](../../reference/architecture.md#local-writes) to ensure that the values written into the local database will successfully replicate into Postgres. + +As a result, we support a limited set of validated Postgres data types. If you try to [electrify a table](./electrification.md) which contains unsupported types or [constraints](./constraints.md), this will fail. The same applies to altering an electrified table. + +## Primary keys + +Primary keys must be unique and immutable. + +ElectricSQL does not support sequential autoincrementing integer IDs. You must use globally unique primary key identifiers. Typically this means binary UUIDs. + +You are responsible for ensuring the uniqueness of your primary keys. If you somehow concurrently create two rows with the same primary key this will cause an integrity violation when the rows are synced. + +## Supported data types + +**Strings**: + +- `text` +- non-length-limited `varchar` + +**Numbers**: + +- `smallint` +- `integer` +- `bigint` +- `double precision` + +The authoritative list of supported data types is maintained in the [`supported_pg_types/0` function](https://github.com/search?q=repo%3Aelectric-sql%2Felectric+symbol%3Asupported_pg_types&type=code). + +
+ +:::caution Work in progress +We are actively working on building out data type support. If you need a type we don't yet support, please [let us know on Discord](https://discord.electric-sql.com). +::: diff --git a/docs/usage/data-modelling/validation.md b/docs/usage/data-modelling/validation.md new file mode 100644 index 00000000..95cdecf0 --- /dev/null +++ b/docs/usage/data-modelling/validation.md @@ -0,0 +1,16 @@ +--- +title: Validation +description: >- + How to validate user input (not currently supported). +sidebar_position: 60 +--- + +:::caution Work in progress +User input validation is not currently supported. +::: + +## Roadmap + +Validation will be defined using [check constraints](./constraints.md#check-constraints) and [DDLX rules](../../api/ddlx.md). Validation logic will then be compiled to run both in the [Client](../data-access/client.md) and on the server. + +See and for more information \ No newline at end of file