Merge branch 'master' into readme

* master:
  ✨ Wait for docker-postgres to "truly" start and accept connections (#1)

Author: sebald

.eslintignore

@@ -1,3 +1,5 @@
 lib/
 coverage/
+example/
+
 jest.config.js

.travis.yml

@@ -1,18 +1,23 @@
-git:
-  depth: 1
+sudo: required
+services:
+  - docker
+
 os:
   - linux
 language: node_js
 node_js:
   - '8'
   - '10'
+
 notifications:
   email:
     on_success: never
+
 cache:
   yarn: true
   directories:
     - node_modules
+
 script:
   - yarn ci
   - yarn global add codecov

README.md

@@ -27,6 +27,17 @@ Using the Docker API (via `dockerode` or similar) will only tell you if the cont
 
 `docker-await-postgres` will read the server logs and long poll until the _postgres_ server is trulry ready. So that tests only run when
 the server is trurly ready to accept connections.
+Start `postgres` docker container and wait until it is truly ready.
+
+This module is based on on [`ava-fixture-docker-db`](https://github.com/cdaringe/ava-fixture-docker-db).
+However, it is
+
+- (test) runner agnostic
+- waits until `postgres` executed all SQL scripts and restarted
+
+## Why
+
+See https://github.com/docker-library/postgres/issues/146
 
 ## Usage
 

example/index.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+const { Client } = require('pg');
+const { startPostgresContainer } = require('../lib');
+
+(async () => {
+  const config = {
+    user: 'admin',
+    password: '12345',
+    database: 'database',
+    image: 'postgres',
+  };
+
+  const { stop, port } = await startPostgresContainer(config);
+  console.log(`Postgres running on port ${port} ...`);
+
+  const client = new Client({
+    host: 'localhost',
+    port,
+    ...config,
+  });
+
+  await client.connect();
+  console.log(`Client connected to Database.`);
+
+  const { rows } = await client.query('SELECT NOW()');
+  console.log(`Server time is: ${rows[0].now}`);
+
+  await client.end();
+  await stop();
+})();

package.json

@@ -24,10 +24,21 @@
       "pre-commit": "pretty-quick --staged"
     }
   },
-  "dependencies": {},
+  "dependencies": {
+    "dockerode": "2.5.8",
+    "execa": "1.0.0",
+    "get-port": "4.1.0",
+    "p-retry": "3.0.1",
+    "pg": "7.8.1"
+  },
   "devDependencies": {
-    "@types/jest": "24.0.6",
-    "@typescript-eslint/eslint-plugin": "1.4.0",
+    "@types/dockerode": "2.5.12",
+    "@types/execa": "0.9.0",
+    "@types/get-port": "4.0.1",
+    "@types/jest": "24.0.9",
+    "@types/p-retry": "3.0.0",
+    "@types/pg": "7.4.13",
+    "@typescript-eslint/eslint-plugin": "1.4.2",
     "conventional-changelog-cli": "2.0.12",
     "conventional-changelog-emojis": "3.0.1",
     "eslint": "5.14.1",
@@ -41,10 +52,11 @@
     "prettier": "1.16.4",
     "pretty-quick": "1.10.0",
     "ts-jest": "24.0.0",
-    "typescript": "3.3.3"
+    "typescript": "3.3.3333"
   },
   "scripts": {
     "start": "tsc",
+    "example": "tsc && node example",
     "test": "jest --config jest.config.js",
     "clean": "rm -rf lib coverage",
     "typecheck": "tsc --noEmit",

src/index.test.ts

@@ -0,0 +1,35 @@
+import { Client } from 'pg';
+import { startPostgresContainer } from '.';
+
+jest.setTimeout(1000 * 60 * 5); // 5 Min timeout, so the image cann be pulled.
+
+test('wait until postgres is ready', async () => {
+  const config = {
+    user: 'admin',
+    password: '12345',
+    database: 'database',
+    image: 'postgres',
+  };
+  const { stop, port } = await startPostgresContainer(config);
+
+  const client = new Client({
+    host: 'localhost',
+    port,
+    ...config,
+  });
+  await client.connect();
+  const { rows } = await client.query('SELECT NOW()');
+  await client.end();
+
+  expect(rows[0].now).toEqual(expect.any(Date));
+
+  await stop();
+
+  // Should fail, since container was stopped.
+  const c = new Client({
+    host: 'localhost',
+    port,
+    ...config,
+  });
+  await expect(c.connect()).rejects.toThrow(/ECONNREFUSED/);
+});

src/index.ts

@@ -0,0 +1,199 @@
+import Docker, { Container } from 'dockerode';
+import execa from 'execa';
+import getPort from 'get-port';
+import { ClientConfig, Client } from 'pg';
+import retry from 'p-retry';
+import { PassThrough } from 'stream';
+
+const docker = new Docker();
+
+/**
+ * Ensure that the image is available on the machine.
+ * Will pull the image if it doesn't exist yet.
+ *
+ * @param name image name including version
+ */
+const ensureImage = async (name: string): Promise<void> => {
+  try {
+    const image = await docker.getImage(name);
+    await image.inspect();
+  } catch {
+    try {
+      // `dockerode`'s pull method doesn't work ... fallback to CLI
+      await execa('docker', ['pull', name]);
+    } catch (e) {
+      throw new Error(`Image "${name}" can not be pulled.\n\n${e.message}`);
+    }
+  }
+};
+
+/**
+ * Meh ...
+ */
+export const THE_MAGIC_WORD =
+  'PostgreSQL init process complete; ready for start up.';
+
+/**
+ * Wait until `postgres` was initialized.
+ * The docker container will execute SQL script files first.
+ * Afterwards the `postgres` server is rebootet.
+ *
+ * @param container
+ */
+const isInitialized = async (
+  container: Container,
+  waitForMessage: string
+): Promise<void> =>
+  new Promise((resolve, reject) => {
+    const logger = new PassThrough();
+
+    logger.on('data', (chunk: Buffer | string) => {
+      const line = chunk.toString('utf8').trim();
+      if (line.includes(waitForMessage)) {
+        resolve();
+      }
+    });
+
+    logger.on('error', err => reject(err));
+    logger.on('end', () => resolve());
+
+    container.logs(
+      {
+        follow: true,
+        stdout: true,
+        stderr: true,
+      },
+      (err, stream) => {
+        if (err) {
+          return reject(err);
+        }
+
+        if (!stream) {
+          return reject(new Error('No stream to read available!'));
+        }
+
+        stream.pipe(logger);
+      }
+    );
+  });
+
+/**
+ * Ping a `postgres` server (10 times max) until it accepts connections.
+ *
+ * @param config client configuration to reach the `postgres` server
+ */
+const isReady = async (config: ClientConfig): Promise<void> =>
+  retry(async () => {
+    const client = new Client(config);
+
+    await client.connect();
+    await client.query('SELECT NOW()');
+    await client.end();
+  });
+
+/**
+ * Kill and remove a docker container.
+ *
+ * @param container the container to kill
+ */
+const kill = async (container: Container): Promise<void> => {
+  try {
+    await container.kill();
+  } finally {
+    try {
+      await container.remove({ force: true });
+    } catch (err) {
+      // If 404, we probably used the --rm flag on container launch. it's all good.
+      if (err.statusCode !== 404 && err.statusCode !== 409) {
+        // eslint-disable-next-line no-unsafe-finally
+        throw err;
+      }
+    }
+  }
+};
+
+/**
+ * Configuration for `postgres` container.
+ */
+export type Config = {
+  /**
+   * Image name of the container.
+   */
+  image?: string;
+
+  /**
+   * Database user.
+   */
+  user: string;
+
+  /**
+   * Password for the database user.
+   */
+  password: string;
+
+  /**
+   * Database name.
+   */
+  database: string;
+
+  /**
+   * Sub-string that represents the successul initialization of the `postgres` server.
+   * Not to confused with "ready". This only means that the server read all scripts
+   * files and created tables etc.
+   */
+  theMagicWord?: string;
+};
+
+export type Result = {
+  /**
+   * Port on which `postgres` is running.
+   */
+  port: number;
+
+  /**
+   * Stop `postgres` container.
+   */
+  stop: () => Promise<void>;
+};
+
+/**
+ * Start a `postgres` container and wait until it is ready
+ * to process queries.
+ *
+ * @param config
+ * @returns object with `port` number and a `stop` method
+ */
+export const startPostgresContainer = async (
+  config: Config
+): Promise<Result> => {
+  const port = await getPort();
+  const image = config.image || 'postgres:latest';
+
+  await ensureImage(image);
+
+  const container = await docker.createContainer({
+    Image: image,
+    ExposedPorts: {
+      '5432/tcp': {},
+    },
+    HostConfig: {
+      AutoRemove: true,
+      PortBindings: { '5432/tcp': [{ HostPort: String(port) }] },
+    },
+    Env: [
+      `POSTGRES_USER=${config.user}`,
+      `POSTGRES_PASSWORD=${config.password}`,
+      `POSTGRES_DB=${config.database}`,
+    ],
+  });
+
+  await container.start();
+
+  await isInitialized(container, config.theMagicWord || THE_MAGIC_WORD);
+  await isReady({ ...config, host: 'localhost', port });
+
+  return {
+    port,
+    stop: async () => kill(container),
+  };
+};