PowerSync

https://docs.powersync.com
Admin
PowerSync is a sync engine that keeps backend databases in sync with on-device SQLite, enabling...
Tokens:880,484
Snippets:6,657
Trust Score:8.4
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Quickstart: Create Expo app and install PowerSync dependencies

Source: https://docs.powersync.com/client-sdks/frameworks/expo-go-support

These commands create a new Expo app, start the development server, and install the required PowerSync dependencies for the quickstart.

```bash
npx create-expo-app@latest my-app

```

```bash
cd my-app && npm run ios

```

```bash
npm install @powersync/react-native @powersync/adapter-sql-js

```

--------------------------------

### Quickstart: Create Expo App and Initialize PowerSync

Source: https://docs.powersync.com/llms-full.txt

Steps to create a new Expo app and set up PowerSync: create the app, start the dev server, install the required packages, and replace the default screen code with the provided initialization and version check.

```bash
npx create-expo-app@latest my-app
```

```bash
cd my-app && npm run ios
```

```bash
npm install @powersync/react-native @powersync/adapter-sql-js
```

```tsx
import { SQLJSOpenFactory } from "@powersync/adapter-sql-js";
import { PowerSyncDatabase, Schema } from "@powersync/react-native";
import { useEffect, useState } from "react";
import { Text } from "react-native";

export const powerSync = new PowerSyncDatabase({
  schema: new Schema({}), // todo: define the schema - see Next Steps below
  factory: new SQLJSOpenFactory({
    dbFilename: "example.db",
  }),
});

export default function HomeScreen() {
  const [version, setVersion] = useState<string | null>(null);

  useEffect(() => {
    powerSync.get("select powersync_rs_version();").then((r) => {setVersion(JSON.stringify(r))});
  }, []);

  return (
      <>{version && <Text style={{fontSize: 24, fontWeight: 'bold'}}>PowerSync Initialized - {version}</Text>}</>
  );
}
```

--------------------------------

### Set up PowerSync Self-Hosted with Docker CLI

Source: https://docs.powersync.com/intro/setup-guide

Install the PowerSync CLI, initialize a self-hosted setup, and configure Docker with Postgres for both the source database and bucket storage. Replace powersync/sync-config.yaml with the minimal Sync Config before starting the service with powersync docker start. Docker Postgres runs init scripts only on first start, so create your tables before the first start.

```bash
npm install -g powersync
powersync init self-hosted
powersync docker configure --database postgres --storage postgres

```

```yaml
config:
  edition: 3

streams:
  todos:
    # Streams without parameters sync the same data to all users
    auto_subscribe: true
    query: "SELECT * FROM todos"

```

```bash
powersync docker start

```

--------------------------------

### Start the stack with docker compose up

Source: https://docs.powersync.com/tools/local-development

Starts the Docker Compose stack defined in the example files.

```bash
docker compose up

```

--------------------------------

### Install attachments for .NET

Source: https://docs.powersync.com/client-sdks/advanced/attachments

Installation instructions for .NET. The attachments feature is built into PowerSync.Common (v0.1.2+), so no additional installation is needed.

```bash
# Built into PowerSync.Common (v0.1.2+). No additional installation needed.
```

--------------------------------

### Existing App: Install SQL.js Adapter and Set Up PowerSync

Source: https://docs.powersync.com/llms-full.txt

For an existing app, install the SQL.js adapter and set up PowerSync using the Sql.js factory. The provided code initializes the database and displays the PowerSync version.

```bash
npm install @powersync/adapter-sql-js
```

```tsx
import { SQLJSOpenFactory } from "@powersync/adapter-sql-js";
import { PowerSyncDatabase, Schema } from "@powersync/react-native";
import { useEffect, useState } from "react";
import { Text } from "react-native";

export const powerSync = new PowerSyncDatabase({
  schema: new Schema({}), // todo: define the schema - see Next Steps below
  factory: new SQLJSOpenFactory({
    dbFilename: "example.db",
  }),
});

export default function HomeScreen() {
  const [version, setVersion] = useState<string | null>(null);

  useEffect(() => {
    powerSync.get("select powersync_rs_version();").then((r) => {setVersion(JSON.stringify(r))});
  }, []);

  return (
      <>{version && <Text style={{fontSize: 24, fontWeight: 'bold'}}>PowerSync Initialized - {version}</Text>}</>
  );
}
```

--------------------------------

### Setup PowerSync with Kysely (JavaScript and TypeScript)

Source: https://docs.powersync.com/llms-full.txt

Setup examples for wrapping a PowerSyncDatabase with Kysely using the @powersync/kysely-driver. The JavaScript version uses a plain schema import, while the TypeScript version passes the Database type to wrapPowerSyncWithKysely for automatic table typing. Both require defining the client-side schema as referenced in the PowerSync setup guide.

```javascript
import { wrapPowerSyncWithKysely } from '@powersync/kysely-driver';
import { PowerSyncDatabase } from '@powersync/web';

// Define schema as in: https://docs.powersync.com/intro/setup-guide#define-your-client-side-schema
import { appSchema } from './schema';

export const powerSyncDb = new PowerSyncDatabase({
  database: {
    dbFilename: 'test.sqlite'
  },
  schema: appSchema
});

export const db = wrapPowerSyncWithKysely(powerSyncDb);
```

```typescript
import { wrapPowerSyncWithKysely } from '@powersync/kysely-driver';
import { PowerSyncDatabase } from "@powersync/web";

// Define schema as in: https://docs.powersync.com/intro/setup-guide#define-your-client-side-schema
import { appSchema, Database } from "./schema";

export const powerSyncDb = new PowerSyncDatabase({
  database: {
    dbFilename: "test.sqlite"
  },
  schema: appSchema,
});

// `db` now automatically contains types for defined tables
export const db = wrapPowerSyncWithKysely<Database>(powerSyncDb)
```

--------------------------------

### Clone and set up the demo repository

Source: https://docs.powersync.com/integrations/neon

Clones the demo repository and installs dependencies. Run these commands from the project root to set up the demo app.

```bash
git clone https://github.com/powersync-ja/powersync-js.git
cd powersync-js
pnpm install
pnpm build:packages
cd demos/react-neon-tanstack-query-notes

```

--------------------------------

### Set up PowerSync Cloud with CLI

Source: https://docs.powersync.com/intro/setup-guide

Install the PowerSync CLI, log in, and scaffold the config directory for a cloud-hosted PowerSync Service. Then create the instance and link the directory to it, replacing <project-id> with your project ID from the PowerSync Dashboard.

```bash
npm install -g powersync
powersync login
powersync init cloud

```

```bash
powersync link cloud --create --project-id=<project-id>

```

--------------------------------

### Example JSON data structure for tasks

Source: https://docs.powersync.com/client-sdks/advanced/query-json-in-sqlite

A sample JSON object representing a task with nested metadata, used as the example data structure throughout the guide.

```json
{
  "id": "task_123",
  "title": "Redesign homepage",
  "assignees": [
    {
      "user_id": "user_001",
      "role": "designer",
      "hours_allocated": 20
    },
    {
      "user_id": "user_002", 
      "role": "developer",
      "hours_allocated": 40
    }
  ],
  "tags": ["urgent", "frontend", "design"],
  "metadata": {
    "priority": 1,
    "sprint": "2024-Q1",
    "dependencies": ["task_100", "task_101"]
  }
}
```

--------------------------------

### Run the demo app with pnpm dev

Source: https://docs.powersync.com/integrations/neon

Starts the development server for the demo app. After running, open http://localhost:5173 in your browser.

```bash
pnpm dev

```

--------------------------------

### JavaScript Setup: wrapPowerSyncWithKysely

Source: https://docs.powersync.com/client-sdks/orms/js/kysely

Sets up a PowerSync database and wraps it with Kysely using the @powersync/kysely-driver package. Requires defining a client-side schema as referenced in the PowerSync setup guide.

```javascript
import { wrapPowerSyncWithKysely } from '@powersync/kysely-driver';
import { PowerSyncDatabase } from '@powersync/web';

// Define schema as in: https://docs.powersync.com/intro/setup-guide#define-your-client-side-schema
import { appSchema } from './schema';

export const powerSyncDb = new PowerSyncDatabase({
  database: {
    dbFilename: 'test.sqlite'
  },
  schema: appSchema
});

export const db = wrapPowerSyncWithKysely(powerSyncDb);

```

--------------------------------

### TypeScript Setup: wrapPowerSyncWithKysely with Database type

Source: https://docs.powersync.com/client-sdks/orms/js/kysely

TypeScript setup that wraps a PowerSync database with Kysely, automatically providing types for defined tables via the Database type parameter. Requires a schema definition as referenced in the PowerSync setup guide.

```typescript
import { wrapPowerSyncWithKysely } from '@powersync/kysely-driver';
import { PowerSyncDatabase } from "@powersync/web";

// Define schema as in: https://docs.powersync.com/intro/setup-guide#define-your-client-side-schema
import { appSchema, Database } from "./schema";

export const powerSyncDb = new PowerSyncDatabase({
  database: {
    dbFilename: "test.sqlite"
  },
  schema: appSchema,
});

// `db` now automatically contains types for defined tables
export const db = wrapPowerSyncWithKysely<Database>(powerSyncDb)

```

--------------------------------

### Install and initialize PowerSync CLI

Source: https://docs.powersync.com/configuration/powersync-service/cloud-instances

Install the PowerSync CLI globally, log in, and scaffold the config directory. Requires Node.js/npm. Creates a powersync/ directory with service.yaml and sync-config.yaml.

```bash
npm install -g powersync
powersync login
powersync init cloud

```

--------------------------------

### Install PowerSync TanStack DB collection

Source: https://docs.powersync.com/client-sdks/orms/js/tanstack-db

Installs the PowerSync TanStack DB collection package along with the Web SDK and the wa-sqlite driver. Required before using the examples on this page.

```shell
npm install @tanstack/powersync-db-collection @powersync/web @journeyapps/wa-sqlite
```

--------------------------------

### Install PowerSync Agent Skills

Source: https://docs.powersync.com/tools/ai-tools

Run this command in your terminal to install PowerSync Agent Skills, which provide AI agents with PowerSync-specific context and capabilities. Follow the prompts to complete the setup.

```bash
npx skills add powersync-ja/agent-skills

```

--------------------------------

### Quickstart: Initialize PowerSync in app/(tabs)/index.tsx

Source: https://docs.powersync.com/client-sdks/frameworks/expo-go-support

Replace the contents of app/(tabs)/index.tsx with this code to initialize PowerSync using the SQL.js adapter and display the PowerSync version.

```tsx
import { SQLJSOpenFactory } from "@powersync/adapter-sql-js";
import { PowerSyncDatabase, Schema } from "@powersync/react-native";
import { useEffect, useState } from "react";
import { Text } from "react-native";

export const powerSync = new PowerSyncDatabase({
  schema: new Schema({}), // todo: define the schema - see Next Steps below
  factory: new SQLJSOpenFactory({
    dbFilename: "example.db",
  }),
});

export default function HomeScreen() {
  const [version, setVersion] = useState<string | null>(null);

  useEffect(() => {
    powerSync.get("select powersync_rs_version();").then((r) => {setVersion(JSON.stringify(r))});
  }, []);

  return (
      <>{version && <Text style={{fontSize: 24, fontWeight: 'bold'}}>PowerSync Initialized - {version}</Text>}</>
  );
}

```

--------------------------------

### Start ngrok TCP tunnel

Source: https://docs.powersync.com/integrations/supabase/local-development

Starts ngrok to expose the local Supabase database port (54322) over TCP. The output shows the forwarding address; note the hostname and port for later configuration. Requires ngrok installed.

```bash
# look for the PORTS value of the supabase-db_supabase-test container
docker ps -f name=supabase-db --format '{{.Ports}}'

# should see something like 0.0.0.0:54322->5432/tcp
# use the first port
ngrok tcp 54322

# should then see something like this:
Forwarding  tcp://4.tcp.us-cal-1.ngrok.io:19263 -> localhost:54322

```

--------------------------------

### Configure the Demo App - Kotlin

Source: https://docs.powersync.com/integrations/supabase/guide

Creates a local.properties file with SDK path, PowerSync URL, and Supabase credentials.

```properties
# Make a `local.properties` file in the root and fill in the relevant variables (see points below for further details):

# local.properties
sdk.dir=/path/to/android/sdk

# Enter your PowerSync instance URL
POWERSYNC_URL=https://foo.powersync.journeyapps.com
# Enter your Supabase project's URL and public anon key
SUPABASE_URL=https://foo.supabase.co # from https://supabase.com/dashboard/project/_/settings/api
SUPABASE_ANON_KEY=foo # from https://supabase.com/dashboard/project/_/settings/api-keys

```

--------------------------------

### Setup web assets

Source: https://docs.powersync.com/client-sdks/frameworks/flutter-web-support

Downloads the required web assets (sqlite3.wasm, powersync_db.worker.js, powersync_sync.worker.js) to the web directory. Run from the application's root folder.

```bash
dart run powersync:setup_web

```

--------------------------------

### Create powersync publication (Supabase)

Source: https://docs.powersync.com/configuration/source-db/setup

SQL to create a publication named 'powersync' for all tables. This is the simplest way to get started in a dev environment.

```sql
-- Create a publication to replicate tables. The publication must be named "powersync"
CREATE PUBLICATION powersync FOR ALL TABLES;

```

--------------------------------

### Setup PowerSync with Drizzle

Source: https://docs.powersync.com/client-sdks/orms/js/drizzle

Setup for using Drizzle with PowerSync: define SQLite tables and relations, create a Drizzle schema, instantiate a PowerSyncDatabase, and wrap it with wrapPowerSyncWithDrizzle to get the queryable db. Includes commented alternative to generate the PowerSync schema via DrizzleAppSchema.

```javascript
import { wrapPowerSyncWithDrizzle } from '@powersync/drizzle-driver';
import { PowerSyncDatabase } from '@powersync/web';
import { relations } from 'drizzle-orm';
import { index, integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
import { AppSchema } from './schema';

export const lists = sqliteTable('lists', {
  id: text('id'),
  name: text('name')
});

export const todos = sqliteTable('todos', {
  id: text('id'),
  description: text('description'),
  list_id: text('list_id'),
  created_at: text('created_at')
});

export const listsRelations = relations(lists, ({ one, many }) => ({
  todos: many(todos)
}));

export const todosRelations = relations(todos, ({ one, many }) => ({
  list: one(lists, {
    fields: [todos.list_id],
    references: [lists.id]
  })
}));

export const drizzleSchema = {
  lists,
  todos,
  listsRelations,
  todosRelations
};

// As an alternative to manually defining a PowerSync schema, generate the local PowerSync schema from the Drizzle schema with the `DrizzleAppSchema` constructor:
// import { DrizzleAppSchema } from '@powersync/drizzle-driver';
// export const AppSchema = new DrizzleAppSchema(drizzleSchema);
//
// This is optional, but recommended, since you will only need to maintain one schema on the client-side
// Read on to learn more.

export const powerSyncDb = new PowerSyncDatabase({
  database: {
    dbFilename: 'test.sqlite'
  },
  schema: AppSchema
});

// This is the DB you will use in queries
export const db = wrapPowerSyncWithDrizzle(powerSyncDb, {
  schema: drizzleSchema
});
```

--------------------------------

### Set up web assets with dart run powersync:setup_web

Source: https://docs.powersync.com/llms-full.txt

Downloads the required web assets (sqlite3.wasm, powersync_db.worker.js, powersync_sync.worker.js) to the web directory. Run this command in your application's root folder.

```bash
dart run powersync:setup_web
```

--------------------------------

### Configure the Demo App - JavaScript Web

Source: https://docs.powersync.com/integrations/supabase/guide

Copies the .env.local template and instructs to edit it with the necessary credentials.

```bash
cp .env.local.template .env.local

# Edit `.env.local` and insert the necessary credentials as detailed below.

```

--------------------------------

### Quotes in JSON strings

Source: https://docs.powersync.com/client-sdks/advanced/query-json-in-sqlite

Use ->> to get unquoted text instead of -> which returns JSON with quotes. The example shows the difference when comparing sprint values.

```sql
-- ❌ Returns: "2024-Q1" (with quotes)
WHERE metadata -> '$.sprint' = '2024-Q1' 

-- ✅ Returns: 2024-Q1 (without quotes)  
WHERE metadata ->> '$.sprint' = '2024-Q1'
```

--------------------------------

### Log in and scaffold a new Cloud instance

Source: https://docs.powersync.com/tools/cli

Logs in and scaffolds a new Cloud instance. Run these commands first when creating a new instance.

```bash
powersync login
powersync init cloud

```

--------------------------------

### Install PowerSync SDK with dart pub add

Source: https://docs.powersync.com/llms-full.txt

Adds the PowerSync Dart/Flutter SDK to your project. Use the latest version from pub.dev; the example shows version ^2.0.0.

```bash
dart pub add powersync:'^2.0.0'
```

--------------------------------

### Observe PowerSync status as a Flow in Kotlin

Source: https://docs.powersync.com/client-sdks/usage-examples

Initialize a PowerSyncDatabase and collect its current status as a Kotlin Flow to observe connection state. The example shows how to get a Compose state from the flow and check the connected property.

```kotlin
// Intialize the DB
val db = remember { PowerSyncDatabase(factory, schema) }
// Get the status as a flow
val status = db.currentStatus.asFlow().collectAsState(initial = null)
// Use the emitted values from the flow e.g. to check if connected
val isConnected = status.value?.connected

```

--------------------------------

### Install @powersync/web

Source: https://docs.powersync.com/client-sdks/reference/javascript-web-api

Install the PowerSync Web SDK package using npm.

```bash
npm install @powersync/web  
```
Tokens:
Raw