PowerSync Go Backend

A production-ready Go server application that provides HTTP endpoints for PowerSync-enabled applications to sync data between client devices and PostgreSQL, MySQL, MongoDB, or Microsoft SQL Server databases.

PowerSync API Endpoints

Method	Endpoint	Description
GET	/api/auth/token	PowerSync uses this endpoint to retrieve a JWT access token which is used for authentication.
GET	/api/auth/keys	PowerSync uses this endpoint to validate the JWT returned from the endpoint above.
POST	/api/data	PowerSync uses this endpoint to sync batch operations (PUT/PATCH/DELETE) that occurred on the client application.
PUT	/api/data	PowerSync uses this endpoint to sync single upsert events that occurred on the client application.
PATCH	/api/data	PowerSync uses this endpoint to sync single update events that occurred on the client application.
DELETE	/api/data	PowerSync uses this endpoint to sync single delete events that occurred on the client application.
PUT	/api/data/checkpoint	PowerSync uses this endpoint to create checkpoints for sync operations.

Dependencies

• gin-gonic/gin: HTTP web framework
• jackc/pgx/v5: PostgreSQL driver
• go-sql-driver/mysql: MySQL driver
• mongo-go-driver: MongoDB driver
• go-mssqldb: Microsoft SQL Server driver
• go-jose: JWT signing and validation

Requirements

• Go 1.25.4 or later
• One of the following databases:
  • PostgreSQL 12+
  • MySQL 8.0+
  • MongoDB 4.4+
  • Microsoft SQL Server 2017+

For local development, Docker containers are recommended. For production, use managed database services or your own database infrastructure.

Running the app

1. Clone the repository

2. Generate RSA key pairs for JWT signing. Follow the PowerSync authentication guide or use your own keys.

   Important: The application will generate temporary keys for development if POWERSYNC_PRIVATE_KEY and POWERSYNC_PUBLIC_KEY are not set. Never use auto-generated keys in production.

3. Configure environment variables. Create a .env file or set them in your environment:

PORT=6060
DATABASE_TYPE=postgres
DATABASE_URI=postgres://user:pass@localhost:5432/mydb?sslmode=disable
POWERSYNC_URL=https://your-instance.powersync.com
POWERSYNC_PRIVATE_KEY=your_base64_encoded_private_key_jwk
POWERSYNC_PUBLIC_KEY=your_base64_encoded_public_key_jwk
JWT_ISSUER=your_issuer

Required variables:

• DATABASE_TYPE: One of postgres, mysql, mongodb, or mssql
• DATABASE_URI: Connection string for your database
• POWERSYNC_URL: Your PowerSync instance URL
• POWERSYNC_PRIVATE_KEY: Base64-encoded private key JWK (required for production)
• POWERSYNC_PUBLIC_KEY: Base64-encoded public key JWK (required for production)
• JWT_ISSUER: JWT issuer identifier

Optional variables:

• PORT: Server port (default: 6060)

4. Install dependencies:

go mod download

5. Run the application:

go run cmd/api/main.go

The server will start on http://127.0.0.1:PORT (default port: 6060).

Verify the server is running:

curl http://127.0.0.1:6060/api/auth/token

Production Deployment

Security Considerations

1. Never use auto-generated keys in production - Always provide POWERSYNC_PRIVATE_KEY and POWERSYNC_PUBLIC_KEY environment variables
2. Use HTTPS - Ensure your production server uses TLS/SSL
3. Secure database connections - Use SSL/TLS for database connections in production
4. Environment variables - Store sensitive credentials securely (use secret management services)
5. CORS configuration - Update CORS settings to restrict origins in production

Deployment Options

• Docker: Use the provided Dockerfile for containerized deployment
• Cloud platforms: Deploy to AWS, GCP, Azure, or other cloud providers
• Traditional hosting: Run as a systemd service or similar

PowerSync Configuration

In the PowerSync Dashboard, configure the JWKS URI:

https://your-production-domain.com/api/auth/keys

Ensure the endpoint is publicly accessible and returns valid JWKS format.

Development/Testing with ngrok

For local development and testing, you can use ngrok to expose your local server:

1. Install ngrok
2. Run: ngrok http 6060
3. Use the HTTPS URL in PowerSync Dashboard: https://your_id.ngrok-free.app/api/auth/keys

Running Tests

Tests use a mock persistence layer and don't require a database connection:

go test -v ./test/...

Docker

Build the Docker image:

docker build -t powersync-go-backend .

Run the container:

docker run -p 6060:6060 \
  -e DATABASE_TYPE=postgres \
  -e DATABASE_URI="postgres://user:pass@host:5432/db" \
  -e POWERSYNC_URL="https://your-instance.powersync.com" \
  -e POWERSYNC_PRIVATE_KEY="your_base64_encoded_private_key" \
  -e POWERSYNC_PUBLIC_KEY="your_base64_encoded_public_key" \
  -e JWT_ISSUER="your_issuer" \
  powersync-go-backend

Or use Docker Compose for easier management of multiple services.