Usage

Learn how to register your database and make API requests with Electric Cloud.

Register your Database

1. Go to Electric Cloud and log in.

2. Add a new database by clicking on New Source.

3. Pick a region, team, and fill in your PostgreSQL connection string. Click the connect source button to connect your database to Electric Cloud.

Once connected you should see your source details.

Making API Requests

To request a shape you need to make an API request to https://api.electric-sql.cloud/v1/shape. Don't forget to include the source credentials you obtained in the previous step.

Here is an example request using curl:

export SOURCE_ID="8ea4e5fb-9217-4ca6-80b7-0a97581c4c10"
export SECRET="<long secret value>"

export SHAPE_DEFINITION="table=items&offset=-1"

curl -i "https://api.electric-sql.cloud/v1/shape?$SHAPE_DEFINITION\
    &source_id=$SOURCE_ID\
    &secret=$SECRET"

Security Model

The source ID is a key that uniquely identifies your Postgres database. The source secret is a token that grants access to it.

Do not use your source secret in the client!

If you use the source secret from a client, then this exposes it to malicious users.

See the security guide for more context.

Proxy Auth

The recommended pattern is to add the source ID and secret parameter to the origin request made by your auth proxy or API.

See the Cloud overview for detailed examples.

Usage

Register your Database

1. Go to Electric Cloud and log in.

2. Add a new database by clicking on New Source.

3. Pick a region, team, and fill in your PostgreSQL connection string. Click the connect source button to connect your database to Electric Cloud.

Once connected you should see your source details akin to the screenshot below.

When the source state is active, you're ready to make your first API request.

Making API Requests

To request a shape you need to make an API request to https://api.electric-sql.cloud/v1/shape. Don't forget to include the source credentials you obtained in the previous step. If you don't recall them you can always find them in your user dashboard.

Here is an example request using curl:

export SOURCE_ID="8ea4e5fb-9217-4ca6-80b7-0a97581c4c10"
export SECRET="<long secret value>"

export SHAPE_DEFINITION="table=items&offset=-1"

curl -i "https://api.electric-sql.cloud/v1/shape?$SHAPE_DEFINITION\
    &source_id=$SOURCE_ID\
    &secret=$SECRET"

Security Model

The source ID is a key that uniquely identifies your Postgres database.

The source secret is a token that grants access to it. You should treat the source secret as securely as you would with your database password.

Do not use your source secret in the client!

If you use the source secret from a client, then this exposes it to malicious users, who can then use it to connect to your cloud API.

See the security guide for more context.

Proxy Auth

The recommended pattern for secure use of the Electric Cloud is to add the source ID and secret parameter to the origin request made by your auth proxy or API. (You can proxy requests to Electric using an edge worker, or an API. In many cases, this can be your existing backend API).

Example

In your client, request the shape as normal, without the source_id and secret parameters. For example here using the Typescript client:

import { ShapeStream } from '@electric-sql/client'

const stream = new ShapeStream({
  url: `https://your-api-or-proxy.example.com/v1/shape`,
  params: {
    table: `items`,
  },
})

Then add the source ID and secret to the origin request in your auth proxy. For example here using a Next.js Route Handler):

export async function GET(req: Request) {
  const proxyUrl = new URL(req.url)

  // ... validate and authorize the request ...

  // Construct the origin URL.
  const originUrl = new URL(`/v1/shape`, `https://api.electric-sql.cloud`)
  proxyUrl.searchParams.forEach((value, key) => {
    originUrl.searchParams.set(key, value)
  })

  // Add the source params.
  originUrl.searchParams.set(`source_id`, process.env.SOURCE_ID)
  originUrl.searchParams.set(`secret`, process.env.SOURCE_SECRET)

  // Proxy the authorised request on to the Electric Cloud.
  const response = await fetch(originUrl)

  // Fetch decompresses the body but doesn't remove the
  // content-encoding & content-length headers which would
  // break decoding in the browser.
  //
  // See https://github.com/whatwg/fetch/issues/1729
  const headers = new Headers(response.headers)
  headers.delete(`content-encoding`)
  headers.delete(`content-length`)

  return new Response(response.body, {
    status: response.status,
    statusText: response.statusText,
    headers,
  })
}

Pricing

Electric Cloud has a generous free tier and paid plans with usage limits and other features. See the Pricing page for more details.

Support

Let us know if you have any questions. We'll be very happy to help. You can ask questions on Discord or email us directly at sales@electric-sql.com.

Sign-up for Cloud