@powersync/service-module-postgres 0.0.0-dev-20240918092408

package/src/replication/WalStreamReplicationJob.ts

@@ -0,0 +1,142 @@
+import { MissingReplicationSlotError, WalStream } from './WalStream.js';
+import { container } from '@powersync/lib-services-framework';
+import { PgManager } from './PgManager.js';
+
+import { replication } from '@powersync/service-core';
+import { ConnectionManagerFactory } from './ConnectionManagerFactory.js';
+
+export interface WalStreamReplicationJobOptions extends replication.AbstractReplicationJobOptions {
+  connectionFactory: ConnectionManagerFactory;
+}
+
+export class WalStreamReplicationJob extends replication.AbstractReplicationJob {
+  private connectionFactory: ConnectionManagerFactory;
+  private readonly connectionManager: PgManager;
+
+  constructor(options: WalStreamReplicationJobOptions) {
+    super(options);
+    this.connectionFactory = options.connectionFactory;
+    this.connectionManager = this.connectionFactory.create({
+      // Pool connections are only used intermittently.
+      idleTimeout: 30_000,
+      maxSize: 2
+    });
+  }
+
+  /**
+   * Postgres on RDS writes performs a WAL checkpoint every 5 minutes by default, which creates a new 64MB file.
+   *
+   * The old WAL files are only deleted once no replication slot still references it.
+   *
+   * Unfortunately, when there are no changes to the db, the database creates new WAL files without the replication slot
+   * advancing**.
+   *
+   * As a workaround, we write a new message every couple of minutes, to make sure that the replication slot advances.
+   *
+   * **This may be a bug in pgwire or how we're using it.
+   */
+  async keepAlive() {
+    try {
+      await this.connectionManager.pool.query(`SELECT * FROM pg_logical_emit_message(false, 'powersync', 'ping')`);
+    } catch (e) {
+      this.logger.warn(`KeepAlive failed, unable to post to WAL`, e);
+    }
+  }
+
+  get slotName() {
+    return this.options.storage.slot_name;
+  }
+
+  async replicate() {
+    try {
+      await this.replicateLoop();
+    } catch (e) {
+      // Fatal exception
+      container.reporter.captureException(e, {
+        metadata: {
+          replication_slot: this.slotName
+        }
+      });
+      this.logger.error(`Replication failed on ${this.slotName}`, e);
+
+      if (e instanceof MissingReplicationSlotError) {
+        // This stops replication on this slot, and creates a new slot
+        await this.options.storage.factory.slotRemoved(this.slotName);
+      }
+    } finally {
+      this.abortController.abort();
+    }
+  }
+
+  async replicateLoop() {
+    while (!this.isStopped) {
+      await this.replicateOnce();
+
+      if (!this.isStopped) {
+        await new Promise((resolve) => setTimeout(resolve, 5000));
+      }
+    }
+  }
+
+  async replicateOnce() {
+    // New connections on every iteration (every error with retry),
+    // otherwise we risk repeating errors related to the connection,
+    // such as caused by cached PG schemas.
+    const connectionManager = this.connectionFactory.create({
+      // Pool connections are only used intermittently.
+      idleTimeout: 30_000,
+      maxSize: 2
+    });
+    try {
+      await this.rateLimiter?.waitUntilAllowed({ signal: this.abortController.signal });
+      if (this.isStopped) {
+        return;
+      }
+      const stream = new WalStream({
+        abort_signal: this.abortController.signal,
+        storage: this.options.storage,
+        connections: connectionManager
+      });
+      await stream.replicate();
+    } catch (e) {
+      this.logger.error(`Replication error`, e);
+      if (e.cause != null) {
+        // Example:
+        // PgError.conn_ended: Unable to do postgres query on ended connection
+        //     at PgConnection.stream (file:///.../powersync/node_modules/.pnpm/github.com+kagis+pgwire@f1cb95f9a0f42a612bb5a6b67bb2eb793fc5fc87/node_modules/pgwire/mod.js:315:13)
+        //     at stream.next (<anonymous>)
+        //     at PgResult.fromStream (file:///.../powersync/node_modules/.pnpm/github.com+kagis+pgwire@f1cb95f9a0f42a612bb5a6b67bb2eb793fc5fc87/node_modules/pgwire/mod.js:1174:22)
+        //     at PgConnection.query (file:///.../powersync/node_modules/.pnpm/github.com+kagis+pgwire@f1cb95f9a0f42a612bb5a6b67bb2eb793fc5fc87/node_modules/pgwire/mod.js:311:21)
+        //     at WalStream.startInitialReplication (file:///.../powersync/powersync-service/lib/replication/WalStream.js:266:22)
+        //     ...
+        //   cause: TypeError: match is not iterable
+        //       at timestamptzToSqlite (file:///.../powersync/packages/jpgwire/dist/util.js:140:50)
+        //       at PgType.decode (file:///.../powersync/packages/jpgwire/dist/pgwire_types.js:25:24)
+        //       at PgConnection._recvDataRow (file:///.../powersync/packages/jpgwire/dist/util.js:88:22)
+        //       at PgConnection._recvMessages (file:///.../powersync/node_modules/.pnpm/github.com+kagis+pgwire@f1cb95f9a0f42a612bb5a6b67bb2eb793fc5fc87/node_modules/pgwire/mod.js:656:30)
+        //       at PgConnection._ioloopAttempt (file:///.../powersync/node_modules/.pnpm/github.com+kagis+pgwire@f1cb95f9a0f42a612bb5a6b67bb2eb793fc5fc87/node_modules/pgwire/mod.js:563:20)
+        //       at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
+        //       at async PgConnection._ioloop (file:///.../powersync/node_modules/.pnpm/github.com+kagis+pgwire@f1cb95f9a0f42a612bb5a6b67bb2eb793fc5fc87/node_modules/pgwire/mod.js:517:14),
+        //   [Symbol(pg.ErrorCode)]: 'conn_ended',
+        //   [Symbol(pg.ErrorResponse)]: undefined
+        // }
+        // Without this additional log, the cause would not be visible in the logs.
+        this.logger.error(`cause`, e.cause);
+      }
+      if (e instanceof MissingReplicationSlotError) {
+        throw e;
+      } else {
+        // Report the error if relevant, before retrying
+        container.reporter.captureException(e, {
+          metadata: {
+            replication_slot: this.slotName
+          }
+        });
+        // This sets the retry delay
+        this.rateLimiter?.reportError(e);
+      }
+    } finally {
+      await connectionManager.end();
+    }
+  }
+}

package/src/replication/WalStreamReplicator.ts

@@ -0,0 +1,45 @@
+import { storage, replication } from '@powersync/service-core';
+import { WalStreamReplicationJob } from './WalStreamReplicationJob.js';
+import { ConnectionManagerFactory } from './ConnectionManagerFactory.js';
+import { cleanUpReplicationSlot } from './replication-utils.js';
+
+export interface WalStreamReplicatorOptions extends replication.AbstractReplicatorOptions {
+  connectionFactory: ConnectionManagerFactory;
+}
+
+export class WalStreamReplicator extends replication.AbstractReplicator<WalStreamReplicationJob> {
+  private readonly connectionFactory: ConnectionManagerFactory;
+
+  constructor(options: WalStreamReplicatorOptions) {
+    super(options);
+    this.connectionFactory = options.connectionFactory;
+  }
+
+  createJob(options: replication.CreateJobOptions): WalStreamReplicationJob {
+    return new WalStreamReplicationJob({
+      id: this.createJobId(options.storage.group_id),
+      storage: options.storage,
+      connectionFactory: this.connectionFactory,
+      lock: options.lock,
+      rateLimiter: this.rateLimiter
+    });
+  }
+
+  async cleanUp(syncRulesStorage: storage.SyncRulesBucketStorage): Promise<void> {
+    const connectionManager = this.connectionFactory.create({
+      idleTimeout: 30_000,
+      maxSize: 1
+    });
+    try {
+      // TODO: Slot_name will likely have to come from a different source in the future
+      await cleanUpReplicationSlot(syncRulesStorage.slot_name, connectionManager.pool);
+    } finally {
+      await connectionManager.end();
+    }
+  }
+
+  async stop(): Promise<void> {
+    await super.stop();
+    await this.connectionFactory.shutdown();
+  }
+}

package/src/replication/replication-index.ts

@@ -0,0 +1,5 @@
+export * from './PgRelation.js';
+export * from './replication-utils.js';
+export * from './WalStream.js';
+export * from './WalStreamReplicator.js';
+export * from './WalStreamReplicationJob.js';

package/src/replication/replication-utils.ts

@@ -0,0 +1,329 @@
+import * as pgwire from '@powersync/service-jpgwire';
+
+import { PatternResult, storage } from '@powersync/service-core';
+import * as pgwire_utils from '../utils/pgwire_utils.js';
+import { ReplicationIdentity } from './PgRelation.js';
+import * as sync_rules from '@powersync/service-sync-rules';
+import * as service_types from '@powersync/service-types';
+import * as pg_utils from '../utils/pgwire_utils.js';
+import * as util from '../utils/pgwire_utils.js';
+import { logger } from '@powersync/lib-services-framework';
+
+export interface ReplicaIdentityResult {
+  replicationColumns: storage.ColumnDescriptor[];
+  replicationIdentity: ReplicationIdentity;
+}
+
+export async function getPrimaryKeyColumns(
+  db: pgwire.PgClient,
+  relationId: number,
+  mode: 'primary' | 'replident'
+): Promise<storage.ColumnDescriptor[]> {
+  const indexFlag = mode == 'primary' ? `i.indisprimary` : `i.indisreplident`;
+  const attrRows = await pgwire_utils.retriedQuery(db, {
+    statement: `SELECT a.attname as name, a.atttypid as typeid, t.typname as type, a.attnum as attnum
+                                    FROM pg_index i
+                                    JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = ANY (i.indkey)
+                                    JOIN pg_type t ON a.atttypid = t.oid
+                                    WHERE i.indrelid = $1::oid
+                                      AND ${indexFlag}
+                                      AND a.attnum > 0
+                                      ORDER BY a.attnum`,
+    params: [{ value: relationId, type: 'int4' }]
+  });
+
+  return attrRows.rows.map((row) => {
+    return {
+      name: row[0] as string,
+      typeId: row[1] as number
+    } satisfies storage.ColumnDescriptor;
+  });
+}
+
+export async function getAllColumns(db: pgwire.PgClient, relationId: number): Promise<storage.ColumnDescriptor[]> {
+  const attrRows = await pgwire_utils.retriedQuery(db, {
+    statement: `SELECT a.attname as name, a.atttypid as typeid, t.typname as type, a.attnum as attnum
+                                    FROM pg_attribute a
+                                    JOIN pg_type t ON a.atttypid = t.oid
+                                    WHERE a.attrelid = $1::oid
+                                      AND attnum > 0
+                                    ORDER BY a.attnum`,
+    params: [{ type: 'varchar', value: relationId }]
+  });
+  return attrRows.rows.map((row) => {
+    return {
+      name: row[0] as string,
+      typeId: row[1] as number
+    } satisfies storage.ColumnDescriptor;
+  });
+}
+
+export async function getReplicationIdentityColumns(
+  db: pgwire.PgClient,
+  relationId: number
+): Promise<ReplicaIdentityResult> {
+  const rows = await pgwire_utils.retriedQuery(db, {
+    statement: `SELECT CASE relreplident
+        WHEN 'd' THEN 'default'
+        WHEN 'n' THEN 'nothing'
+        WHEN 'f' THEN 'full'
+        WHEN 'i' THEN 'index'
+     END AS replica_identity
+FROM pg_class
+WHERE oid = $1::oid LIMIT 1`,
+    params: [{ type: 'int8', value: relationId }]
+  });
+  const idType: string = rows.rows[0]?.[0];
+  if (idType == 'nothing' || idType == null) {
+    return { replicationIdentity: 'nothing', replicationColumns: [] };
+  } else if (idType == 'full') {
+    return { replicationIdentity: 'full', replicationColumns: await getAllColumns(db, relationId) };
+  } else if (idType == 'default') {
+    return {
+      replicationIdentity: 'default',
+      replicationColumns: await getPrimaryKeyColumns(db, relationId, 'primary')
+    };
+  } else if (idType == 'index') {
+    return {
+      replicationIdentity: 'index',
+      replicationColumns: await getPrimaryKeyColumns(db, relationId, 'replident')
+    };
+  } else {
+    return { replicationIdentity: 'nothing', replicationColumns: [] };
+  }
+}
+
+export async function checkSourceConfiguration(db: pgwire.PgClient, publicationName: string) {
+  // Check basic config
+  await pgwire_utils.retriedQuery(
+    db,
+    `DO $$
+BEGIN
+if current_setting('wal_level') is distinct from 'logical' then
+raise exception 'wal_level must be set to ''logical'', your database has it set to ''%''. Please edit your config file and restart PostgreSQL.', current_setting('wal_level');
+end if;
+if (current_setting('max_replication_slots')::int >= 1) is not true then
+raise exception 'Your max_replication_slots setting is too low, it must be greater than 1. Please edit your config file and restart PostgreSQL.';
+end if;
+if (current_setting('max_wal_senders')::int >= 1) is not true then
+raise exception 'Your max_wal_senders setting is too low, it must be greater than 1. Please edit your config file and restart PostgreSQL.';
+end if;
+end;
+$$ LANGUAGE plpgsql;`
+  );
+
+  // Check that publication exists
+  const rs = await pgwire_utils.retriedQuery(db, {
+    statement: `SELECT * FROM pg_publication WHERE pubname = $1`,
+    params: [{ type: 'varchar', value: publicationName }]
+  });
+  const row = pgwire.pgwireRows(rs)[0];
+  if (row == null) {
+    throw new Error(
+      `Publication '${publicationName}' does not exist. Run: \`CREATE PUBLICATION ${publicationName} FOR ALL TABLES\`, or read the documentation for details.`
+    );
+  }
+  if (row.pubinsert == false || row.pubupdate == false || row.pubdelete == false || row.pubtruncate == false) {
+    throw new Error(
+      `Publication '${publicationName}' does not publish all changes. Create a publication using \`WITH (publish = "insert, update, delete, truncate")\` (the default).`
+    );
+  }
+  if (row.pubviaroot) {
+    throw new Error(`'${publicationName}' uses publish_via_partition_root, which is not supported.`);
+  }
+}
+
+export interface GetDebugTablesInfoOptions {
+  db: pgwire.PgClient;
+  publicationName: string;
+  connectionTag: string;
+  tablePatterns: sync_rules.TablePattern[];
+  syncRules: sync_rules.SqlSyncRules;
+}
+
+export async function getDebugTablesInfo(options: GetDebugTablesInfoOptions): Promise<PatternResult[]> {
+  const { db, publicationName, connectionTag, tablePatterns, syncRules } = options;
+  let result: PatternResult[] = [];
+
+  for (let tablePattern of tablePatterns) {
+    const schema = tablePattern.schema;
+
+    let patternResult: PatternResult = {
+      schema: schema,
+      pattern: tablePattern.tablePattern,
+      wildcard: tablePattern.isWildcard
+    };
+    result.push(patternResult);
+
+    if (tablePattern.isWildcard) {
+      patternResult.tables = [];
+      const prefix = tablePattern.tablePrefix;
+      const results = await util.retriedQuery(db, {
+        statement: `SELECT c.oid AS relid, c.relname AS table_name
+        FROM pg_class c
+        JOIN pg_namespace n ON n.oid = c.relnamespace
+        WHERE n.nspname = $1
+        AND c.relkind = 'r'
+        AND c.relname LIKE $2`,
+        params: [
+          { type: 'varchar', value: schema },
+          { type: 'varchar', value: tablePattern.tablePattern }
+        ]
+      });
+
+      for (let row of pgwire.pgwireRows(results)) {
+        const name = row.table_name as string;
+        const relationId = row.relid as number;
+        if (!name.startsWith(prefix)) {
+          continue;
+        }
+        const details = await getDebugTableInfo({
+          db,
+          name,
+          publicationName,
+          connectionTag,
+          tablePattern,
+          relationId,
+          syncRules: syncRules
+        });
+        patternResult.tables.push(details);
+      }
+    } else {
+      const results = await util.retriedQuery(db, {
+        statement: `SELECT c.oid AS relid, c.relname AS table_name
+        FROM pg_class c
+        JOIN pg_namespace n ON n.oid = c.relnamespace
+        WHERE n.nspname = $1
+        AND c.relkind = 'r'
+        AND c.relname = $2`,
+        params: [
+          { type: 'varchar', value: schema },
+          { type: 'varchar', value: tablePattern.tablePattern }
+        ]
+      });
+      if (results.rows.length == 0) {
+        // Table not found
+        patternResult.table = await getDebugTableInfo({
+          db,
+          name: tablePattern.name,
+          publicationName,
+          connectionTag,
+          tablePattern,
+          relationId: null,
+          syncRules: syncRules
+        });
+      } else {
+        const row = pgwire.pgwireRows(results)[0];
+        const name = row.table_name as string;
+        const relationId = row.relid as number;
+        patternResult.table = await getDebugTableInfo({
+          db,
+          name,
+          publicationName,
+          connectionTag,
+          tablePattern,
+          relationId,
+          syncRules: syncRules
+        });
+      }
+    }
+  }
+  return result;
+}
+
+export interface GetDebugTableInfoOptions {
+  db: pgwire.PgClient;
+  name: string;
+  publicationName: string;
+  connectionTag: string;
+  tablePattern: sync_rules.TablePattern;
+  relationId: number | null;
+  syncRules: sync_rules.SqlSyncRules;
+}
+
+export async function getDebugTableInfo(options: GetDebugTableInfoOptions): Promise<service_types.TableInfo> {
+  const { db, name, publicationName, connectionTag, tablePattern, relationId, syncRules } = options;
+  const schema = tablePattern.schema;
+  let id_columns_result: ReplicaIdentityResult | undefined = undefined;
+  let id_columns_error = null;
+
+  if (relationId != null) {
+    try {
+      id_columns_result = await getReplicationIdentityColumns(db, relationId);
+    } catch (e) {
+      id_columns_error = { level: 'fatal', message: e.message };
+    }
+  }
+
+  const id_columns = id_columns_result?.replicationColumns ?? [];
+
+  const sourceTable = new storage.SourceTable(0, connectionTag, relationId ?? 0, schema, name, id_columns, true);
+
+  const syncData = syncRules.tableSyncsData(sourceTable);
+  const syncParameters = syncRules.tableSyncsParameters(sourceTable);
+
+  if (relationId == null) {
+    return {
+      schema: schema,
+      name: name,
+      pattern: tablePattern.isWildcard ? tablePattern.tablePattern : undefined,
+      replication_id: [],
+      data_queries: syncData,
+      parameter_queries: syncParameters,
+      // Also
+      errors: [{ level: 'warning', message: `Table ${sourceTable.qualifiedName} not found.` }]
+    };
+  }
+  if (id_columns.length == 0 && id_columns_error == null) {
+    let message = `No replication id found for ${sourceTable.qualifiedName}. Replica identity: ${id_columns_result?.replicationIdentity}.`;
+    if (id_columns_result?.replicationIdentity == 'default') {
+      message += ' Configure a primary key on the table.';
+    }
+    id_columns_error = { level: 'fatal', message };
+  }
+
+  let selectError = null;
+  try {
+    await pg_utils.retriedQuery(db, `SELECT * FROM ${sourceTable.escapedIdentifier} LIMIT 1`);
+  } catch (e) {
+    selectError = { level: 'fatal', message: e.message };
+  }
+
+  let replicateError = null;
+
+  const publications = await pg_utils.retriedQuery(db, {
+    statement: `SELECT tablename FROM pg_publication_tables WHERE pubname = $1 AND schemaname = $2 AND tablename = $3`,
+    params: [
+      { type: 'varchar', value: publicationName },
+      { type: 'varchar', value: tablePattern.schema },
+      { type: 'varchar', value: name }
+    ]
+  });
+  if (publications.rows.length == 0) {
+    replicateError = {
+      level: 'fatal',
+      message: `Table ${sourceTable.qualifiedName} is not part of publication '${publicationName}'. Run: \`ALTER PUBLICATION ${publicationName} ADD TABLE ${sourceTable.qualifiedName}\`.`
+    };
+  }
+
+  return {
+    schema: schema,
+    name: name,
+    pattern: tablePattern.isWildcard ? tablePattern.tablePattern : undefined,
+    replication_id: id_columns.map((c) => c.name),
+    data_queries: syncData,
+    parameter_queries: syncParameters,
+    errors: [id_columns_error, selectError, replicateError].filter(
+      (error) => error != null
+    ) as service_types.ReplicationError[]
+  };
+}
+
+export async function cleanUpReplicationSlot(slotName: string, db: pgwire.PgClient): Promise<void> {
+  logger.info(`Cleaning up Postgres replication slot: ${slotName}...`);
+
+  await db.query({
+    statement: 'SELECT pg_drop_replication_slot(slot_name) FROM pg_replication_slots WHERE slot_name = $1',
+    params: [{ type: 'varchar', value: slotName }]
+  });
+}

package/src/types/types.ts

@@ -0,0 +1,159 @@
+import * as service_types from '@powersync/service-types';
+import * as t from 'ts-codec';
+import * as urijs from 'uri-js';
+
+export const POSTGRES_CONNECTION_TYPE = 'postgresql' as const;
+
+export interface NormalizedPostgresConnectionConfig {
+  id: string;
+  tag: string;
+
+  hostname: string;
+  port: number;
+  database: string;
+
+  username: string;
+  password: string;
+
+  sslmode: 'verify-full' | 'verify-ca' | 'disable';
+  cacert: string | undefined;
+
+  client_certificate: string | undefined;
+  client_private_key: string | undefined;
+}
+
+export const PostgresConnectionConfig = service_types.configFile.dataSourceConfig.and(
+  t.object({
+    type: t.literal(POSTGRES_CONNECTION_TYPE),
+    /** Unique identifier for the connection - optional when a single connection is present. */
+    id: t.string.optional(),
+    /** Tag used as reference in sync rules. Defaults to "default". Does not have to be unique. */
+    tag: t.string.optional(),
+    uri: t.string.optional(),
+    hostname: t.string.optional(),
+    port: service_types.configFile.portCodec.optional(),
+    username: t.string.optional(),
+    password: t.string.optional(),
+    database: t.string.optional(),
+
+    /** Defaults to verify-full */
+    sslmode: t.literal('verify-full').or(t.literal('verify-ca')).or(t.literal('disable')).optional(),
+    /** Required for verify-ca, optional for verify-full */
+    cacert: t.string.optional(),
+
+    client_certificate: t.string.optional(),
+    client_private_key: t.string.optional(),
+
+    /** Expose database credentials */
+    demo_database: t.boolean.optional(),
+
+    /**
+     * Prefix for the slot name. Defaults to "powersync_"
+     */
+    slot_name_prefix: t.string.optional()
+  })
+);
+
+/**
+ * Config input specified when starting services
+ */
+export type PostgresConnectionConfig = t.Decoded<typeof PostgresConnectionConfig>;
+
+/**
+ * Resolved version of {@link PostgresConnectionConfig}
+ */
+export type ResolvedConnectionConfig = PostgresConnectionConfig & NormalizedPostgresConnectionConfig;
+
+/**
+ * Validate and normalize connection options.
+ *
+ * Returns destructured options.
+ */
+export function normalizeConnectionConfig(options: PostgresConnectionConfig): NormalizedPostgresConnectionConfig {
+  let uri: urijs.URIComponents;
+  if (options.uri) {
+    uri = urijs.parse(options.uri);
+    if (uri.scheme != 'postgresql' && uri.scheme != 'postgres') {
+      `Invalid URI - protocol must be postgresql, got ${uri.scheme}`;
+    } else if (uri.scheme != 'postgresql') {
+      uri.scheme = 'postgresql';
+    }
+  } else {
+    uri = urijs.parse('postgresql:///');
+  }
+
+  const hostname = options.hostname ?? uri.host ?? '';
+  const port = validatePort(options.port ?? uri.port ?? 5432);
+
+  const database = options.database ?? uri.path?.substring(1) ?? '';
+
+  const [uri_username, uri_password] = (uri.userinfo ?? '').split(':');
+
+  const username = options.username ?? uri_username ?? '';
+  const password = options.password ?? uri_password ?? '';
+
+  const sslmode = options.sslmode ?? 'verify-full'; // Configuration not supported via URI
+  const cacert = options.cacert;
+
+  if (sslmode == 'verify-ca' && cacert == null) {
+    throw new Error('Explicit cacert is required for sslmode=verify-ca');
+  }
+
+  if (hostname == '') {
+    throw new Error(`hostname required`);
+  }
+
+  if (username == '') {
+    throw new Error(`username required`);
+  }
+
+  if (password == '') {
+    throw new Error(`password required`);
+  }
+
+  if (database == '') {
+    throw new Error(`database required`);
+  }
+
+  return {
+    id: options.id ?? 'default',
+    tag: options.tag ?? 'default',
+
+    hostname,
+    port,
+    database,
+
+    username,
+    password,
+    sslmode,
+    cacert,
+
+    client_certificate: options.client_certificate ?? undefined,
+    client_private_key: options.client_private_key ?? undefined
+  };
+}
+
+/**
+ * Check whether the port is in a "safe" range.
+ *
+ * We do not support connecting to "privileged" ports.
+ */
+export function validatePort(port: string | number): number {
+  if (typeof port == 'string') {
+    port = parseInt(port);
+  }
+  if (port >= 1024 && port <= 49151) {
+    return port;
+  } else {
+    throw new Error(`Port ${port} not supported`);
+  }
+}
+
+/**
+ * Construct a postgres URI, without username, password or ssl options.
+ *
+ * Only contains hostname, port, database.
+ */
+export function baseUri(options: NormalizedPostgresConnectionConfig) {
+  return `postgresql://${options.hostname}:${options.port}/${options.database}`;
+}