diff --git a/docs/api/ddlx.md b/docs/api/ddlx.md index 7286672b7b..6359331cfd 100644 --- a/docs/api/ddlx.md +++ b/docs/api/ddlx.md @@ -333,7 +333,7 @@ Basically, an assignment tells ElectricSQL where to read these roles from and wh #### Role definitions -A role can either be global, one that applies to any data, or be scoped by a row in a table so that it applies only to data that has a relationship to that row. This allows you to define roles tied to rows in tables, for example an `'admin'` of a project, or a `'member'` of a club. +A role can either be global, one that applies to any data, or be scoped by a row in a table so that it applies only to data that has a relationship to that row. This allows you to define roles tied to rows in tables. For example, an `'admin'` of a project, or a `'member'` of a club. The role can also either be static and explicitly given as a literal in the `ASSIGN` statement or dynamically read from a column in the `table_name`. diff --git a/docs/integrations/backend/prisma.md b/docs/integrations/backend/prisma.md index 2fc199913b..20dd013aec 100644 --- a/docs/integrations/backend/prisma.md +++ b/docs/integrations/backend/prisma.md @@ -18,7 +18,7 @@ datasource db { } ``` -You can then use [dotenv-cli](https://www.npmjs.com/package/dotenv-cli) to setup multiple `.env` files, for example create a `.env.proxy` with a database URL to connect to the proxy: +You can then use [dotenv-cli](https://www.npmjs.com/package/dotenv-cli) to setup multiple `.env` files. For example, create a `.env.proxy` with a database URL to connect to the proxy: ```shell DATABASE_URL=postgresql://postgres:${PG_PROXY_PASSWORD}@localhost:${PG_PROXY_PORT}/mydb diff --git a/docs/integrations/backend/sql.md b/docs/integrations/backend/sql.md index 670658f826..e8c569f708 100644 --- a/docs/integrations/backend/sql.md +++ b/docs/integrations/backend/sql.md @@ -9,7 +9,7 @@ sidebar_position: 60 You can execute DDLX statement using raw SQL. -Make sure you connect via the [migrations proxy](../../usage/data-modelling/migrations.md#migrations-proxy). For example using PSQL: +Make sure you connect via the [migrations proxy](../../usage/data-modelling/migrations.md#migrations-proxy). For example, using PSQL: ```console $ psql "postgresql://postgres:$PG_PROXY_PASSWORD@localhost:$PG_PROXY_PORT/mydb" diff --git a/docs/integrations/deployment/fly.md b/docs/integrations/deployment/fly.md index a72dab55b8..3412f86c65 100644 --- a/docs/integrations/deployment/fly.md +++ b/docs/integrations/deployment/fly.md @@ -141,10 +141,6 @@ $ fly secrets set --stage \ Secrets have been staged, but not set on VMs. Deploy or update machines in this app for the secrets to take effect. ``` -:::info -Double-check that your value for `DATABASE_URL` starts with `postgresql://` and ends with the database name, e.g. `/postgres`. -::: - ### Deploy! Now we're ready to deploy Electric to Fly! diff --git a/docs/integrations/frontend/svelte.md b/docs/integrations/frontend/svelte.md index a915717fff..d0ab5fd161 100644 --- a/docs/integrations/frontend/svelte.md +++ b/docs/integrations/frontend/svelte.md @@ -8,11 +8,11 @@ sidebar_position: 30 :::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. +[Let us know on Discord](https://discord.electric-sql/com) if you're interested in helping to develop Svelte support. ::: ### Implementation notes -The [svelte/store](https://svelte.dev/docs/svelte-store) interface should be useful, for example using [writable](https://svelte.dev/docs/svelte-store#writable) to store query results. There's a trivial example of a hook-like API [here](https://svelte.dev/repl/7580c4426c1947d8aa3d149a05bdc895?version=4.1.2). +The [svelte/store](https://svelte.dev/docs/svelte-store) interface should be useful, for example, using [writable](https://svelte.dev/docs/svelte-store#writable) to store query results. There's a trivial example of a hook-like API [here](https://svelte.dev/repl/7580c4426c1947d8aa3d149a05bdc895?version=4.1.2). See the [existing React integration](https://github.com/electric-sql/electric/tree/main/clients/typescript/src/frameworks/react) for reference / what needs to be ported. diff --git a/docs/reference/architecture.md b/docs/reference/architecture.md index 521ae2373a..a4e5363ca6 100644 --- a/docs/reference/architecture.md +++ b/docs/reference/architecture.md @@ -137,7 +137,7 @@ Satellite processes monitor the connectivity state of the network and their unde - `error`: there was an error when connecting - `syncing`: the connection is active but is currently catching up with the server prior to replicating local writes -If the connection is disconnected manually (for example using the `toggle` functionn returned by the [`useConnectivityState`](../integrations/frontend/react.md#toggleConnectivityState) hook) then it won't automatically reconnect. Otherwise if disconnected due to a transient error or network connectivity then the web socket connection will try to reconnect automatically using a backoff algorithm. +If the connection is disconnected manually (for example, using the `toggle` functionn returned by the [`useConnectivityState`](../integrations/frontend/react.md#toggleConnectivityState) hook) then it won't automatically reconnect. Otherwise if disconnected due to a transient error or network connectivity then the web socket connection will try to reconnect automatically using a backoff algorithm. ## More information diff --git a/docs/reference/integrity.md b/docs/reference/integrity.md index 1b10a12e8a..c8f85fd7a3 100644 --- a/docs/reference/integrity.md +++ b/docs/reference/integrity.md @@ -171,7 +171,7 @@ The following table summarises the anomalies that can occur with different datab **Problem**:
Cumulating the effects of individual operation might result in amplification of the intended changes. This is a particular case of failing to preserve user intention. -**Example**:
two users modify some object’s property concurrently, for example enlarging a shape, and the semantics of the merge is to sum the deltas. The shape size will end larger than each user intended. When trying to correct the issue, the reverse situation might happen again. +**Example**:
two users modify some object’s property concurrently, for example, enlarging a shape, and the semantics of the merge is to sum the deltas. The shape size will end larger than each user intended. When trying to correct the issue, the reverse situation might happen again. **Mitigation**:
Cumulative effects are acceptable when latency is low enough that users perceive that there are concurrent modifications to the same object. diff --git a/docs/reference/roadmap.md b/docs/reference/roadmap.md index 9187bf764d..3080512464 100644 --- a/docs/reference/roadmap.md +++ b/docs/reference/roadmap.md @@ -54,7 +54,7 @@ This is a very temporary workaround and will be removed soon! 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. -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. +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. 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'll need to manually drop the objects created by Electric: diff --git a/docs/usage/data-access/queries.md b/docs/usage/data-access/queries.md index eea4405958..eaa02fee92 100644 --- a/docs/usage/data-access/queries.md +++ b/docs/usage/data-access/queries.md @@ -17,7 +17,7 @@ See for more details on the functi Read data using the [`findUnique`](../../api/clients/typescript.md#findUnique), [`findFirst`](../../api/clients/typescript.md#findFirst) and [`findMany`](../../api/clients/typescript.md#findMany) functions. -For example to get a project by unique ID: +For example, to get a project by unique ID: ```ts const result = await db.projects.findUnique({ diff --git a/docs/usage/data-access/shapes.md b/docs/usage/data-access/shapes.md index 2a285ecf98..8e632d4e8d 100644 --- a/docs/usage/data-access/shapes.md +++ b/docs/usage/data-access/shapes.md @@ -149,7 +149,7 @@ If the shape subscription is invalid, the first promise will be rejected. If the Data synced onto the local device via a shape subscription appears atomically in the local database. I.e.: it all loads within a single transaction. -You can query the local database at any time, for example establishing a [Live query](./queries.md#live-queries) at the same time as initiating the shape sync. The query results will initially be empty (unless data is already in the local database) and then will update once with the full set of data loaded by the shape subscription. +You can query the local database at any time, for example, establishing a [Live query](./queries.md#live-queries) at the same time as initiating the shape sync. The query results will initially be empty (unless data is already in the local database) and then will update once with the full set of data loaded by the shape subscription. For example, this is OK: @@ -229,7 +229,7 @@ const MyComponent = () => { } ``` -For many applications you can simply define the data you want to sync up-front, for example at app load time and then just code against the local database once the data has synced in. For others, you can craft more dynamic partial replication, for example syncing data in as the user navigates through different routes or parts of the app. +For many applications you can simply define the data you want to sync up-front, for example, at app load time and then just code against the local database once the data has synced in. For others, you can craft more dynamic partial replication, for instance, syncing data in as the user navigates through different routes or parts of the app. ## Future capabilities @@ -245,7 +245,7 @@ This limits the expressiveness of shape filter clauses to the matching capabilit Currently all shapes are always live. However, in some cases, you may want to make ephemeral queries and keep results available for offline use without always keeping them live and up-to-date. Subscription semantics will allow you to configure whether a shape subscription is maintained to keep the data synced in a shape live or not. -Currently all synced data is retained forever until explicitly deleted. Retention semantics will provide a declarative API to control data retention and deterministic behaviour when there's contention for storage resources. +Currently all synced data is retained forever until explicitly deleted. Retention semantics will provide a declarative API to control data retention and deterministic behaviour when there's contention for storage resources. ### Discovered shapes diff --git a/docs/usage/data-access/writes.md b/docs/usage/data-access/writes.md index fd079bdbf6..c3410c2328 100644 --- a/docs/usage/data-access/writes.md +++ b/docs/usage/data-access/writes.md @@ -9,7 +9,7 @@ sidebar_position: 50 Insert, update and delete data using the [`create`](../../api/clients/typescript.md#create), [`createMany`](../../api/clients/typescript.md#createMany), [`update`](../../api/clients/typescript.md#update), [`updateMany`](../../api/clients/typescript.md#updateMany), [`delete`](../../api/clients/typescript.md#delete) and [`deleteMany`](../../api/clients/typescript.md#deleteMany) functions. -For example to insert a new project: +For example, to insert a new project: ```ts const project = await db.projects.create({ diff --git a/docs/usage/data-modelling/_segmentation.md b/docs/usage/data-modelling/_segmentation.md index bbed5665cc..68b0c3a335 100644 --- a/docs/usage/data-modelling/_segmentation.md +++ b/docs/usage/data-modelling/_segmentation.md @@ -26,7 +26,7 @@ If you can't naturally segment your data then you may find it difficult to optim ## Primary and foreign keys -You can implicitly segment on **primary keys** and **foreign keys**. For example in your shape query you can use clauses like the following without having to create any segmentation indexes in your DDLX: +You can implicitly segment on **primary keys** and **foreign keys**. For example, in your shape query you can use clauses like the following without having to create any segmentation indexes in your DDLX: ```tsx { diff --git a/docs/usage/data-modelling/migrations.md b/docs/usage/data-modelling/migrations.md index e2960c7b4f..be65bd85ac 100644 --- a/docs/usage/data-modelling/migrations.md +++ b/docs/usage/data-modelling/migrations.md @@ -252,7 +252,7 @@ Only tables in the default schema named [`public`](https://www.postgresql.org/do ### Table names -The client generator sanitises table names (because of an issue in an [external library](https://github.com/chrishoermann/zod-prisma-types/issues/121)) removing any prefix that is not a letter and treating the first letter as case insensitive. For example electrifying the tables `_myTable`, `123myTable`, `myTable`, and `MyTable` will all clash on table name, causing a generator error. +The client generator sanitises table names (because of an issue in an [external library](https://github.com/chrishoermann/zod-prisma-types/issues/121)) removing any prefix that is not a letter and treating the first letter as case insensitive. As an example, electrifying the tables `_myTable`, `123myTable`, `myTable`, and `MyTable` will all clash on table name, causing a generator error. ### Forward migrations