diff --git a/docs/api/service.md b/docs/api/service.md index c871c84f04..3fcba8e309 100644 --- a/docs/api/service.md +++ b/docs/api/service.md @@ -16,7 +16,7 @@ Configuration options are passed as environment variables, e.g.: ```shell docker run \ -e "DATABASE_URL=postgresql://..." \ - -e "LOGICAL_PUBLISHER_HOST=..." \ + -e "ELECTRIC_WRITE_TO_PG_MODE=direct_writes" \ -e "PG_PROXY_PASSWORD=..." \ -e "AUTH_JWT_ALG=HS512" \ -e "AUTH_JWT_KEY=..." \ diff --git a/docs/deployment/_render.md b/docs/deployment/_render.md index 76b3af6198..250c83e5ce 100644 --- a/docs/deployment/_render.md +++ b/docs/deployment/_render.md @@ -51,16 +51,8 @@ services: value: "..." - key: DATABASE_URL value: "postgresql://..." - - key: LOGICAL_PUBLISHER_HOST - fromService: - type: web - name: tcp-proxy - property: host - - key: LOGICAL_PUBLISHER_PORT - fromService: - type: web - name: tcp-proxy - property: port + - key: ELECTRIC_WRITE_TO_PG_MODE + value: "direct_writes" - type: web name: http-proxy runtime: image diff --git a/docs/deployment/docker.md b/docs/deployment/docker.md index babc08cdca..25f0375037 100644 --- a/docs/deployment/docker.md +++ b/docs/deployment/docker.md @@ -12,7 +12,7 @@ See to get familiar with confi ```shell docker run \ -e "DATABASE_URL=postgresql://..." \ - -e "LOGICAL_PUBLISHER_HOST=..." \ + -e "ELECTRIC_WRITE_TO_PG_MODE=direct_writes" \ -e "PG_PROXY_PASSWORD=..." \ -e "AUTH_JWT_ALG=HS512" \ -e "AUTH_JWT_KEY=..." \ diff --git a/docs/deployment/k8s.md b/docs/deployment/k8s.md index e93f8588c5..8cd0b289a9 100644 --- a/docs/deployment/k8s.md +++ b/docs/deployment/k8s.md @@ -35,8 +35,8 @@ spec: env: - name: DATABASE_URL value: "postgresql://..." - - name: LOGICAL_PUBLISHER_HOST - value: "..." + - name: ELECTRIC_WRITE_TO_PG_MODE + value: "direct_writes" - name: PG_PROXY_PASSWORD value: "..." - name: AUTH_JWT_ALG diff --git a/docs/examples/notes/running.md b/docs/examples/notes/running.md index b36ce73f0b..2a96dac91b 100644 --- a/docs/examples/notes/running.md +++ b/docs/examples/notes/running.md @@ -47,9 +47,9 @@ npm run dev ### Connecting Electric to Postgres -The Electric sync service connects to Postgres using the `DATABASE_URL` environment variable. Depending on your choice of write mode, Postgres may also need to connect to Electric to consume a logical replication publication. +The Electric sync service connects to Postgres using the `DATABASE_URL` environment variable. Depending on your [choice of write mode](../../api/service#write-to-pg-mode), Postgres may also need to connect to Electric to consume a logical replication publication. -This is configured using the `LOGICAL_PUBLISHER_HOST` (and `LOGICAL_PUBLISHER_PORT`) environment variables: +If so, this is configured using the `LOGICAL_PUBLISHER_HOST` (and `LOGICAL_PUBLISHER_PORT`) environment variables: ``` |<--------DATABASE_URL----------| diff --git a/docs/quickstart/_setup_manual.md b/docs/quickstart/_setup_manual.md index 22df4df41b..ec8b931b16 100644 --- a/docs/quickstart/_setup_manual.md +++ b/docs/quickstart/_setup_manual.md @@ -23,7 +23,7 @@ docker pull electricsql/electric:latest docker run \ -e "DATABASE_URL=postgresql://..." \ -e "DATABASE_REQUIRE_SSL=false \ - -e "LOGICAL_PUBLISHER_HOST=..." \ + -e "ELECTRIC_WRITE_TO_PG_MODE=direct_writes" \ -e "PG_PROXY_PASSWORD=..." \ -e "AUTH_MODE=insecure" \ -p 5133:5133 \ diff --git a/docs/reference/architecture.md b/docs/reference/architecture.md index 20475a70f4..dd7649b896 100644 --- a/docs/reference/architecture.md +++ b/docs/reference/architecture.md @@ -92,18 +92,15 @@ ElectricSQL aims to provide **finality** of local writes. That is to say: valid Whilst local writes are final, they are still subject to concurrent merge semantics. One way to understand this is that writes are always *factored in* to the history, even if their operations are actually overridden by the semantics of the conflict resolution logic. - ### Streaming into Electric -When the local database migrations are generated from the Postgres DDL changes, triggers are added that automatically copy insert, update and delete operations on the tables to the "oplog" table. The satellite process then processes these operations by sending them to the Electric server over the Satellite protocol. Electric then applies server-side validation and authorisation before sending on to Postgres over the incoming logical-replication stream. +When the local database migrations are generated from the Postgres DDL changes, triggers are added that automatically copy insert, update and delete operations on the tables to the "oplog" table. The satellite process then processes these operations by sending them to the Electric server over the Satellite protocol. -:::note -Electric acts as a [logical replication publisher](https://www.postgresql.org/docs/current/logical-replication.html). This is why you configure a `LOGICAL_PUBLISHER_HOST` when deploying the Electric sync service -- so that Postgres can connect to consume inbound logical replication. -::: +Electric then applies server-side validation and authorisation before writing into Postgres using the [`ELECTRIC_WRITE_TO_PG_MODE`](../api/service#write-to-pg-mode). ### Streaming into Postgres -When you electrify a table in the Postgres DDL schema, this installs triggers that handle insert, update and delete operations. When Postgres applies the operations from the inbound logical replication stream, these triggers fire and run database-side merge logic. +When you electrify a table in the Postgres DDL schema, this installs triggers that handle insert, update and delete operations. When Postgres applies writes from the Electric sync service, these triggers fire and run database-side merge logic. ### Direct writes to Postgres diff --git a/docs/usage/installation/service.md b/docs/usage/installation/service.md index eec7887777..74435236a0 100644 --- a/docs/usage/installation/service.md +++ b/docs/usage/installation/service.md @@ -11,15 +11,21 @@ You can run the [pre-packaged Docker images](#images) published on Docker Hub, o ## Configuration -The Electric sync service is configured using environment variables. The three required variables are: +The Electric sync service is configured using environment variables. The required variables are: - `DATABASE_URL` in the format of a Postgres [Connection URI](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS) -- `LOGICAL_PUBLISHER_HOST` that the sync service is running on (must be accessible from the Postgres instance to establish an inbound replication subscription) - `PG_PROXY_PASSWORD` to safe-guard access to the [Migrations proxy](../data-modelling/migrations.md#migrations-proxy) +Plus depending on your [Write to PG mode](../../api/service#write-to-pg-mode) you must either: + +- set `ELECTRIC_WRITE_TO_PG_MODE=direct_writes`; or +- set `LOGICAL_PUBLISHER_HOST` to a hostname that the Postgres can connect to the sync service on + +For example: + ```shell DATABASE_URL="postgresql://user:password@localhost:5432/electric" -LOGICAL_PUBLISHER_HOST="localhost" +ELECTRIC_WRITE_TO_PG_MODE="direct_writes" PG_PROXY_PASSWORD="..." ``` @@ -34,7 +40,7 @@ Pre-packaged images are available on Docker Hub at [electricsql/electric](https: ```shell docker run \ -e "DATABASE_URL=postgresql://..." \ - -e "LOGICAL_PUBLISHER_HOST=..." \ + -e "ELECTRIC_WRITE_TO_PG_MODE=direct_writes" \ -e "PG_PROXY_PASSWORD=..." \ -e "AUTH_MODE=insecure" \ -p 5133:5133 \ @@ -75,7 +81,7 @@ services: environment: DATABASE_URL: postgresql://postgres:pg_password@pg/postgres DATABASE_REQUIRE_SSL: false - LOGICAL_PUBLISHER_HOST: electric + ELECTRIC_WRITE_TO_PG_MODE: direct_writes PG_PROXY_PASSWORD: proxy_password AUTH_MODE: insecure ports: @@ -103,7 +109,7 @@ Then run: ```shell docker run \ -e "DATABASE_URL=postgresql://..." \ - -e "LOGICAL_PUBLISHER_HOST=..." \ + -e "ELECTRIC_WRITE_TO_PG_MODE=direct_writes" \ -e "PG_PROXY_PASSWORD=..." \ -e "AUTH_MODE=insecure" \ -p 5133:5133 \