feat: abstract away pg (#555)

BREAKING CHANGE: The primary goal of this refactor is to remove hard dependency on `pg`. My intention is to move Slonik away from being a `pg` wrapper, to make it a universal client. The work in this PR abstracts all interactions with the database behind a pool and drivers (e.g. `createPgDriver`). This makes it very easy to implement drivers for `pg-native`, `postgres` and other drivers. * Drops dependency on `pg.Pool` * Implements a more efficient internal pooling mechanism. * For context, test execution time dropped from ~50 seconds down to ~6 seconds. * Renames `getPoolState()` to `state()` * Removes `createMockPool` * It was at best not useful, and at worst misleading. Even Slonik itself didn't use it. There are better ways to mock/spy connections. Refer to `createPoolWithSpy` as one of the possible ways. * Refactors all tests to use database connection instead of mocking.
gajus · Mar 27, 2024 · bba41af · bba41af
1 parent 8c53efb
commit bba41af
Show file tree

Hide file tree

Showing 68 changed files with 1,984 additions and 2,359 deletions.
diff --git a/.README/USAGE.md b/.README/USAGE.md
@@ -102,7 +102,7 @@ Note: `pool.end()` does not terminate active connections/ transactions.
 
 ### Describing the current state of the connection pool
 
-Use `pool.getPoolState()` to find out if pool is alive and how many connections are active and idle, and how many clients are waiting for a connection.
+Use `pool.state()` to find out if pool is alive and how many connections are active and idle, and how many clients are waiting for a connection.
 
 ```ts
 import {
@@ -113,44 +113,44 @@ import {
 const pool = await createPool('postgres://');
 
 const main = async () => {
-  pool.getPoolState();
+  pool.state();
 
   // {
-  //   activeConnectionCount: 0,
+  //   activeConnections: 0,
   //   ended: false,
-  //   idleConnectionCount: 0,
-  //   waitingClientCount: 0,
+  //   idleConnections: 0,
+  //   waitingClients: 0,
   // }
 
   await pool.connect(() => {
-    pool.getPoolState();
+    pool.state();
 
     // {
-    //   activeConnectionCount: 1,
+    //   activeConnections: 1,
     //   ended: false,
-    //   idleConnectionCount: 0,
-    //   waitingClientCount: 0,
+    //   idleConnections: 0,
+    //   waitingClients: 0,
     // }
   });
 
-  pool.getPoolState();
+  pool.state();
 
   // {
-  //   activeConnectionCount: 0,
+  //   activeConnections: 0,
   //   ended: false,
-  //   idleConnectionCount: 1,
-  //   waitingClientCount: 0,
+  //   idleConnections: 1,
+  //   waitingClients: 0,
   // }
 
   await pool.end();
 
-  pool.getPoolState();
+  pool.state();
 
   // {
-  //   activeConnectionCount: 0,
+  //   activeConnections: 0,
   //   ended: true,
-  //   idleConnectionCount: 0,
-  //   waitingClientCount: 0,
+  //   idleConnections: 0,
+  //   waitingClients: 0,
   // }
 };
 
@@ -299,50 +299,4 @@ result;
 
 Connection is released back to the pool after the promise produced by the function supplied to `connect()` method is either resolved or rejected.
 
-Read: [Protecting against unsafe connection handling](#protecting-against-unsafe-connection-handling)
-
-### Mocking Slonik
-
-Slonik provides a way to mock queries against the database.
-
-* Use `createMockPool` to create a mock connection.
-* Use `createMockQueryResult` to create a mock query result.
-
-```ts
-import {
-  createMockPool,
-  createMockQueryResult,
-} from 'slonik';
-
-type OverridesType =
-  query: (sql: string, values: PrimitiveValueExpression[],) => Promise<QueryResult<QueryResultRow>>,
-};
-
-createMockPool(overrides: OverridesType): DatabasePool;
-createMockQueryResult(rows: QueryResultRow[]): QueryResult<QueryResultRow>;
-```
-
-Example:
-
-```ts
-import {
-  createMockPool,
-  createMockQueryResult,
-} from 'slonik';
-
-const pool = createMockPool({
-  query: async () => {
-    return createMockQueryResult([
-      {
-        foo: 'bar',
-      },
-    ]);
-  },
-});
-
-await pool.connect(async (connection) => {
-  const results = await connection.query(sql.typeAlias('foo')`
-    SELECT ${'foo'} AS foo
-  `);
-});
-```
+Read: [Protecting against unsafe connection handling](#protecting-against-unsafe-connection-handling).
diff --git a/.eslintrc b/.eslintrc
@@ -13,7 +13,7 @@
       }
     },
     {
-      "files": "*.test.ts",
+      "files": ["*.test.ts", "**/*.test/*"],
       "extends": "canonical/ava",
       "rules": {
         "@typescript-eslint/no-explicit-any": 0,

diff --git a/.github/workflows/feature.yaml b/.github/workflows/feature.yaml
@@ -86,7 +86,6 @@ jobs:
         test_only:
           - utilities
           - pg-integration
-          - postgres-integration
         node_version:
           - 20
       max-parallel: 3

diff --git a/README.md b/README.md
@@ -76,7 +76,6 @@ Note: Using this project does not require TypeScript. It is a regular ES6 module
         * [API](#user-content-slonik-usage-api)
         * [Default configuration](#user-content-slonik-usage-default-configuration)
         * [Checking out a client from the connection pool](#user-content-slonik-usage-checking-out-a-client-from-the-connection-pool)
-        * [Mocking Slonik](#user-content-slonik-usage-mocking-slonik)
     * [How are they different?](#user-content-slonik-how-are-they-different)
         * [`pg` vs `slonik`](#user-content-slonik-how-are-they-different-pg-vs-slonik)
         * [`pg-promise` vs `slonik`](#user-content-slonik-how-are-they-different-pg-promise-vs-slonik)
@@ -532,7 +531,7 @@ Note: `pool.end()` does not terminate active connections/ transactions.
 <a name="slonik-usage-describing-the-current-state-of-the-connection-pool"></a>
 ### Describing the current state of the connection pool
 
-Use `pool.getPoolState()` to find out if pool is alive and how many connections are active and idle, and how many clients are waiting for a connection.
+Use `pool.state()` to find out if pool is alive and how many connections are active and idle, and how many clients are waiting for a connection.
 
 ```ts
 import {
@@ -543,44 +542,44 @@ import {
 const pool = await createPool('postgres://');
 
 const main = async () => {
-  pool.getPoolState();
+  pool.state();
 
   // {
-  //   activeConnectionCount: 0,
+  //   activeConnections: 0,
   //   ended: false,
-  //   idleConnectionCount: 0,
-  //   waitingClientCount: 0,
+  //   idleConnections: 0,
+  //   waitingClients: 0,
   // }
 
   await pool.connect(() => {
-    pool.getPoolState();
+    pool.state();
 
     // {
-    //   activeConnectionCount: 1,
+    //   activeConnections: 1,
     //   ended: false,
-    //   idleConnectionCount: 0,
-    //   waitingClientCount: 0,
+    //   idleConnections: 0,
+    //   waitingClients: 0,
     // }
   });
 
-  pool.getPoolState();
+  pool.state();
 
   // {
-  //   activeConnectionCount: 0,
+  //   activeConnections: 0,
   //   ended: false,
-  //   idleConnectionCount: 1,
-  //   waitingClientCount: 0,
+  //   idleConnections: 1,
+  //   waitingClients: 0,
   // }
 
   await pool.end();
 
-  pool.getPoolState();
+  pool.state();
 
   // {
-  //   activeConnectionCount: 0,
+  //   activeConnections: 0,
   //   ended: true,
-  //   idleConnectionCount: 0,
-  //   waitingClientCount: 0,
+  //   idleConnections: 0,
+  //   waitingClients: 0,
   // }
 };
 
@@ -743,56 +742,7 @@ result;
 
 Connection is released back to the pool after the promise produced by the function supplied to `connect()` method is either resolved or rejected.
 
-Read: [Protecting against unsafe connection handling](#user-content-protecting-against-unsafe-connection-handling)
-
-<a name="user-content-slonik-usage-mocking-slonik"></a>
-<a name="slonik-usage-mocking-slonik"></a>
-### Mocking Slonik
-
-Slonik provides a way to mock queries against the database.
-
-* Use `createMockPool` to create a mock connection.
-* Use `createMockQueryResult` to create a mock query result.
-
-```ts
-import {
-  createMockPool,
-  createMockQueryResult,
-} from 'slonik';
-
-type OverridesType =
-  query: (sql: string, values: PrimitiveValueExpression[],) => Promise<QueryResult<QueryResultRow>>,
-};
-
-createMockPool(overrides: OverridesType): DatabasePool;
-createMockQueryResult(rows: QueryResultRow[]): QueryResult<QueryResultRow>;
-```
-
-Example:
-
-```ts
-import {
-  createMockPool,
-  createMockQueryResult,
-} from 'slonik';
-
-const pool = createMockPool({
-  query: async () => {
-    return createMockQueryResult([
-      {
-        foo: 'bar',
-      },
-    ]);
-  },
-});
-
-await pool.connect(async (connection) => {
-  const results = await connection.query(sql.typeAlias('foo')`
-    SELECT ${'foo'} AS foo
-  `);
-});
-```
-
+Read: [Protecting against unsafe connection handling](#user-content-protecting-against-unsafe-connection-handling).
 
 <a name="user-content-slonik-how-are-they-different"></a>
 <a name="slonik-how-are-they-different"></a>

diff --git a/ava.config.js b/ava.config.js
@@ -14,10 +14,6 @@ module.exports = () => {
     files = ['src/integration.test/pg.test.ts'];
   }
 
-  if (TEST_ONLY === 'postgres-integration') {
-    files = ['src/integration.test/postgres.test.ts'];
-  }
-
   return {
     extensions: ['ts'],
     files,

diff --git a/package-lock.json b/package-lock.json