Session Storage Adapter for PostgreSQL

This package implements the SessionStorage interface that works with an instance of PostgreSQL. Tested using PostgreSQL v15

import {shopifyApp} from '@shopify/shopify-app-express';
import {PostgreSQLSessionStorage} from '@hashem-ramadan/shopify-app-session-storage-postgresql-cloudsql';

const shopify = shopifyApp({
  sessionStorage: new PostgreSQLSessionStorage(
    'postgres://username:password@host/database',
  ),
  // ...
});

// OR

const shopify = shopifyApp({
  sessionStorage: new PostgreSQLSessionStorage(
    new URL('postgres://username:password@host/database'),
  ),
  // ...
});

// OR

const shopify = shopifyApp({
  sessionStorage: PostgreSQLSessionStorage.withCredentials(
    'host.com',
    'thedatabase',
    'username',
    'password',
  ),
  // ...
});

Connecting via Unix Socket (e.g. Google Cloud SQL)

When deploying on Google Cloud (Cloud Run, App Engine, GKE), the Cloud SQL Auth Proxy provides database connections through Unix sockets. You can connect by specifying the socket path via the host query parameter:

const shopify = shopifyApp({
  sessionStorage: new PostgreSQLSessionStorage(
    'postgres://username:password@/database?host=/cloudsql/my-project:us-central1:my-instance',
  ),
  // ...
});

This also works for any other environment where PostgreSQL is accessed via a Unix domain socket.

About this fork

This package is a fork of @shopify/shopify-app-session-storage-postgresql (built on its v6.0.0 release) that adds Unix socket connection support (see Shopify/shopify-app-js#3114). Connection URLs are parsed with pg-connection-string, which preserves the host query parameter, SSL settings, and other connection options. It tracks the upstream package's peer requirements (@shopify/shopify-api@^13, @shopify/shopify-app-session-storage@^5); if/when the upstream PR is merged, prefer the official package.

Expiring Offline Access Tokens

This storage adapter supports expiring offline access tokens. When enabled, the adapter automatically stores and retrieves refresh tokens alongside your session data.

To enable this feature, set the expiringOfflineAccessTokens future flag in your app configuration:

const shopify = shopifyApp({
  sessionStorage: new PostgreSQLSessionStorage(
    'postgres://username:password@host/database',
  ),
  future: {
    expiringOfflineAccessTokens: true,
  },
  // ... other config
});

The required database columns (refreshToken and refreshTokenExpires) are added automatically via the built-in migration system. For details, see the migration guide.

If you prefer to use your own implementation of a session storage mechanism that is compatible with the @shopify/shopify-app-express package, see the implementing session storage guide.