WIP; complete PostgreSQL integration migration

tests/Integration/PostgreSQL/DocumentTest.php

@@ -8,8 +8,8 @@ declare(strict_types=1);
 
 use BitBadger\PDODocument\{AutoId, Configuration, Custom, Document, DocumentException, Field, Find, Query};
 use BitBadger\PDODocument\Mapper\ArrayMapper;
-use Test\Integration\PostgreSQL\ThrowawayDb;
 use Test\Integration\{NumDocument, SubDocument, TestDocument};
+use Test\Integration\PostgreSQL\ThrowawayDb;
 
 pest()->group('integration', 'postgresql');
 

tests/Integration/PostgreSQL/ExistsTest.php

@@ -0,0 +1,48 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Exists, Field};
+use Test\Integration\PostgreSQL\ThrowawayDb;
+
+pest()->group('integration', 'postgresql');
+
+describe('::byId()', function () {
+    test('returns true when a document exists', function () {
+        expect(Exists::byId(ThrowawayDb::TABLE, 'three'))->toBeTrue();
+    });
+    test('returns false when a document does not exist', function () {
+        expect(Exists::byId(ThrowawayDb::TABLE, 'seven'))->toBeFalse();
+    });
+});
+
+describe('::byFields()', function () {
+    test('returns true when matching documents exist', function () {
+        expect(Exists::byFields(ThrowawayDb::TABLE, [Field::equal('num_value', 10)]))->toBeTrue();
+    });
+    test('returns false when no matching documents exist', function () {
+        expect(Exists::byFields(ThrowawayDb::TABLE, [Field::less('nothing', 'none')]))->toBeFalse();
+    });
+});
+
+describe('::byContains()', function () {
+    test('returns true when matching documents exist', function () {
+        expect(Exists::byContains(ThrowawayDb::TABLE, ['value' => 'purple']))->toBeTrue();
+    });
+    test('returns false when no matching documents exist', function () {
+        expect(Exists::byContains(ThrowawayDb::TABLE, ['value' => 'violet']))->toBeFalse();
+    });
+});
+
+describe('::byJsonPath()', function () {
+    test('returns true when matching documents exist', function () {
+        expect(Exists::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ == 10)'))->toBeTrue();
+    });
+    test('returns false when no matching documents exist', function () {
+        expect(Exists::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ == 10.1)'))->toBeFalse();
+    });
+});

tests/Integration/PostgreSQL/FindTest.php

@@ -0,0 +1,216 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Custom, Delete, Document, Field, FieldMatch, Find};
+use Test\Integration\{ArrayDocument, NumDocument, TestDocument};
+use Test\Integration\PostgreSQL\ThrowawayDb;
+
+pest()->group('integration', 'postgresql');
+
+describe('::all()', function () {
+    test('retrieves data', function () {
+        $docs = Find::all(ThrowawayDb::TABLE, TestDocument::class);
+        expect($docs)->not->toBeNull();
+        $count = 0;
+        foreach ($docs->items() as $ignored) $count++;
+        expect($count)->toBe(5);
+    });
+    test('sorts data ascending', function () {
+        $docs = Find::all(ThrowawayDb::TABLE, TestDocument::class, [Field::named('id')]);
+        expect($docs)->not->toBeNull()
+            ->and(iterator_to_array($docs->map(fn ($it) => $it->id), false))
+            ->toBe(['five', 'four', 'one', 'three', 'two']);
+    });
+    test('sorts data descending', function () {
+        $docs = Find::all(ThrowawayDb::TABLE, TestDocument::class, [Field::named('id DESC')]);
+        expect($docs)->not->toBeNull()
+            ->and(iterator_to_array($docs->map(fn ($it) => $it->id), false))
+            ->toBe(['two', 'three', 'one', 'four', 'five']);
+    });
+    test('sorts data numerically', function () {
+        $docs = Find::all(ThrowawayDb::TABLE, TestDocument::class,
+            [Field::named('sub.foo NULLS LAST'), Field::named('n:num_value')]);
+        expect($docs)->not->toBeNull()
+            ->and(iterator_to_array($docs->map(fn ($it) => $it->id), false))
+            ->toBe(['two', 'four', 'one', 'three', 'five']);
+    });
+    test('retrieves empty results', function () {
+        Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+        expect(Find::all(ThrowawayDb::TABLE, TestDocument::class))
+            ->not->toBeNull()
+            ->hasItems()->toBeFalse();
+    });
+});
+
+describe('::byId()', function () {
+    test('retrieves a document via string ID', function () {
+        expect(Find::byId(ThrowawayDb::TABLE, 'two', TestDocument::class))
+            ->isSome()->toBeTrue()
+            ->get()->id->toBe('two');
+    });
+    test('retrieves a document via numeric ID', function () {
+        Delete::byFields(ThrowawayDb::TABLE, [Field::notExists('absent')]);
+        Document::insert(ThrowawayDb::TABLE, ['id' => 18, 'value' => 'howdy']);
+        expect(Find::byId(ThrowawayDb::TABLE, 18, NumDocument::class))
+            ->isSome()->toBeTrue()
+            ->get()->id->toBe(18);
+    });
+    test('returns None when a document is not found', function () {
+        expect(Find::byId(ThrowawayDb::TABLE, 'seventy-five', TestDocument::class))->isNone()->toBeTrue();
+    });
+});
+
+describe('::byFields()', function () {
+    test('retrieves matching documents', function () {
+        $docs = Find::byFields(ThrowawayDb::TABLE, [Field::in('value', ['blue', 'purple']), Field::exists('sub')],
+            TestDocument::class, FieldMatch::All);
+        expect($docs)->not->toBeNull();
+        $count = 0;
+        foreach ($docs->items() as $ignored) $count++;
+        expect($count)->toBe(1);
+    });
+    test('retrieves ordered matching documents', function () {
+        $docs = Find::byFields(ThrowawayDb::TABLE, [Field::equal('value', 'purple')], TestDocument::class,
+            FieldMatch::All, [Field::named('id')]);
+        expect($docs)->not->toBeNull()
+            ->and(iterator_to_array($docs->map(fn ($it) => $it->id), false))->toBe(['five', 'four']);
+    });
+    test('retrieves documents matching a numeric IN clause', function () {
+        $docs = Find::byFields(ThrowawayDb::TABLE, [Field::in('num_value', [2, 4, 6, 8])], TestDocument::class);
+        expect($docs)->not->toBeNull();
+        $count = 0;
+        foreach ($docs->items() as $ignored) $count++;
+        expect($count)->toBe(1);
+    });
+    test('returns an empty list when no matching documents are found', function () {
+        expect(Find::byFields(ThrowawayDb::TABLE, [Field::greater('num_value', 100)], TestDocument::class))
+            ->not->toBeNull()
+            ->hasItems()->toBeFalse();
+    });
+    test('retrieves documents matching an inArray condition', function () {
+        Delete::byFields(ThrowawayDb::TABLE, [Field::notExists('absentField')]);
+        foreach (ArrayDocument::testDocuments() as $doc) Document::insert(ThrowawayDb::TABLE, $doc);
+        $docs = Find::byFields(ThrowawayDb::TABLE, [Field::inArray('values', ThrowawayDb::TABLE, ['c'])],
+            ArrayDocument::class);
+        expect($docs)->not->toBeNull();
+        $count = 0;
+        foreach ($docs->items() as $ignored) $count++;
+        expect($count)->toBe(2);
+    });
+    test('returns an empty list when no documents match an inArray condition', function () {
+        Delete::byFields(ThrowawayDb::TABLE, [Field::notExists('absentField')]);
+        foreach (ArrayDocument::testDocuments() as $doc) Document::insert(ThrowawayDb::TABLE, $doc);
+        expect(Find::byFields(ThrowawayDb::TABLE, [Field::inArray('values', ThrowawayDb::TABLE, ['j'])],
+                ArrayDocument::class))
+            ->not->toBeNull()
+            ->hasItems()->toBeFalse();
+    });
+});
+
+describe('::byContains()', function () {
+    test('retrieves matching documents', function () {
+        $docs = Find::byContains(ThrowawayDb::TABLE, ['value' => 'purple'], TestDocument::class);
+        expect($docs)->not->toBeNull();
+        $count = 0;
+        foreach ($docs->items() as $ignored) $count++;
+        expect($count)->toBe(2);
+    });
+    test('retrieves ordered matching documents', function () {
+        $docs = Find::byContains(ThrowawayDb::TABLE, ['sub' => ['foo' => 'green']], TestDocument::class,
+            [Field::named('value')]);
+        expect($docs)
+            ->not->toBeNull()
+            ->and(iterator_to_array($docs->map(fn ($it) => $it->id), false))->toBe(['two', 'four']);
+    });
+    test('returns an empty list when no documents match', function () {
+        expect(Find::byContains(ThrowawayDb::TABLE, ['value' => 'indigo'], TestDocument::class))
+            ->not->toBeNull()
+            ->hasItems()->toBeFalse();
+    });
+});
+
+describe('::byJsonPath()', function () {
+    test('retrieves matching documents', function () {
+        $docs = Find::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 10)', TestDocument::class);
+        expect($docs)->not->toBeNull();
+        $count = 0;
+        foreach ($docs->items() as $ignored) $count++;
+        expect($count)->toBe(2);
+    });
+    test('retrieves ordered matching documents', function () {
+        $docs = Find::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 10)', TestDocument::class,
+            [Field::named('id')]);
+        expect($docs)->not->toBeNull()
+            ->and(iterator_to_array($docs->map(fn ($it) => $it->id), false))->toBe(['five', 'four']);
+    });
+    test('returns an empty list when no documents match', function () {
+        expect(Find::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 100)', TestDocument::class))
+            ->not->toBeNull()
+            ->hasItems()->toBeFalse();
+    });
+});
+
+describe('::firstByFields()', function () {
+    test('retrieves a matching document', function () {
+        expect(Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('value', 'another')], TestDocument::class))
+            ->isSome()->toBeTrue()->get()->id->toBe('two');
+    });
+    test('retrieves a document for multiple results', function () {
+        $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('sub.foo', 'green')], TestDocument::class);
+        expect($doc)->isSome()->toBeTrue()->and(['two', 'four'])->toContain($doc->get()->id);
+    });
+    test('retrieves a document for multiple ordered results', function () {
+        expect(Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('sub.foo', 'green')], TestDocument::class,
+                orderBy: [Field::named('n:num_value DESC')]))
+            ->isSome()->toBeTrue()->get()->id->toBe('four');
+    });
+    test('returns None when no documents match', function () {
+        expect(Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('value', 'absent')], TestDocument::class))
+            ->isNone()->toBeTrue();
+    });
+});
+
+describe('::firstByContains()', function () {
+    test('retrieves a matching document', function () {
+        expect(Find::firstByContains(ThrowawayDb::TABLE, ['value' => 'FIRST!'], TestDocument::class))
+            ->isSome()->toBeTrue()->get()->id->toBe('one');
+    });
+    test('retrieves a document for multiple results', function () {
+        $doc = Find::firstByContains(ThrowawayDb::TABLE, ['value' => 'purple'], TestDocument::class);
+        expect($doc)->isSome()->toBeTrue()->and(['four', 'five'])->toContain($doc->get()->id);
+    });
+    test('retrieves a document for multiple ordered results', function () {
+        expect(Find::firstByContains(ThrowawayDb::TABLE, ['value' => 'purple'], TestDocument::class,
+                [Field::named('sub.bar NULLS FIRST')]))
+            ->isSome()->toBeTrue()->get()->id->toBe('five');
+    });
+    test('returns None when no documents match', function () {
+        expect(Find::firstByContains(ThrowawayDb::TABLE, ['value' => 'indigo'], TestDocument::class))
+            ->isNone()->toBeTrue();
+    });
+});
+
+describe('::firstByJsonPath()', function () {
+    test('retrieves a matching document', function () {
+        expect(Find::firstByJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ == 10)', TestDocument::class))
+            ->isSome()->toBeTrue()->get()->id->toBe('two');
+    });
+    test('retrieves a document for multiple results', function () {
+        $doc = Find::firstByJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 10)', TestDocument::class);
+        expect($doc)->isSome()->toBeTrue()->and(['four', 'five'])->toContain($doc->get()->id);
+    });
+    test('retrieves a document for multiple ordered results', function () {
+        expect(Find::firstByJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 10)', TestDocument::class,
+                [Field::named('id DESC')]))
+            ->isSome()->toBeTrue()->get()->id->toBe('four');
+    });
+    test('returns None when no documents match', function () {
+        expect(Find::firstByJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 100)', TestDocument::class))
+            ->isNone()->toBeTrue();
+    });
+});

tests/Integration/PostgreSQL/PatchTest.php

@@ -0,0 +1,72 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Count, Exists, Field, Find, Patch};
+use Test\Integration\PostgreSQL\ThrowawayDb;
+use Test\Integration\TestDocument;
+
+pest()->group('integration', 'postgresql');
+
+describe('::byId()', function () {
+    test('updates an existing document', function () {
+        Patch::byId(ThrowawayDb::TABLE, 'one', ['num_value' => 44]);
+        expect(Find::byId(ThrowawayDb::TABLE, 'one', TestDocument::class))
+            ->isSome()->toBeTrue()
+            ->get()->num_value->toBe(44);
+    });
+    test('does nothing when a document does not exist', function () {
+        $id = 'forty-seven';
+        expect(Exists::byId(ThrowawayDb::TABLE, $id))->toBeFalse();
+        Patch::byId(ThrowawayDb::TABLE, $id, ['foo' => 'green']); // no exception = pass
+    });
+});
+
+describe('::byFields()', function () {
+    test('updates existing documents', function () {
+        Patch::byFields(ThrowawayDb::TABLE, [Field::equal('value', 'purple')], ['num_value' => 77]);
+        expect(Count::byFields(ThrowawayDb::TABLE, [Field::equal('num_value', 77)]))->toBe(2);
+    });
+    test('does nothing when no matching documents exist', function () {
+        $fields = [Field::equal('value', 'burgundy')];
+        expect(Count::byFields(ThrowawayDb::TABLE, $fields))->toBe(0);
+        Patch::byFields(ThrowawayDb::TABLE, $fields, ['foo' => 'green']); // no exception = pass
+    });
+});
+
+describe('::byContains()', function () {
+    test('updates existing documents', function () {
+        Patch::byContains(ThrowawayDb::TABLE, ['value' => 'another'], ['num_value' => 12]);
+        $tryDoc = Find::firstByContains(ThrowawayDb::TABLE, ['value' => 'another'], TestDocument::class);
+        expect($tryDoc)->isSome()->toBeTrue()
+            ->and($tryDoc->get())
+            ->id->toBe('two')
+            ->num_value->toBe(12);
+    });
+    test('does nothing when no matching documents exist', function () {
+        $criteria = ['value' => 'updated'];
+        expect(Count::byContains(ThrowawayDb::TABLE, $criteria))->toBe(0);
+        Patch::byContains(ThrowawayDb::TABLE, $criteria, ['sub.foo' => 'green']); // no exception = pass
+    });
+});
+
+describe('::byJsonPath()', function () {
+    test('updates existing documents', function () {
+        Patch::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 10)', ['value' => 'blue']);
+        $docs = Find::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 10)', TestDocument::class);
+        expect($docs)->not->toBeNull()->hasItems()->toBeTrue();
+        foreach ($docs->items() as $item) {
+            expect(['four', 'five'])->toContain($item->id)
+                ->and($item->value)->toBe('blue');
+        }
+    });
+    test('does nothing when no matching documents exist', function () {
+        $path = '$.num_value ? (@ > 100)';
+        expect(Count::byJsonPath(ThrowawayDb::TABLE, $path))->toBe(0);
+        Patch::byJsonPath(ThrowawayDb::TABLE, $path, ['value' => 'blue']); // no exception = pass
+    });
+});

tests/Integration/PostgreSQL/RemoveFieldsTest.php

@@ -0,0 +1,91 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Exists, Field, Find, RemoveFields};
+use Test\Integration\PostgreSQL\ThrowawayDb;
+use Test\Integration\TestDocument;
+
+pest()->group('integration', 'postgresql');
+
+describe('::byId()', function () {
+    test('removes fields', function () {
+        RemoveFields::byId(ThrowawayDb::TABLE, 'two', ['sub', 'value']);
+        $tryDoc = Find::byId(ThrowawayDb::TABLE, 'two', TestDocument::class);
+        expect($tryDoc)->isSome()->toBeTrue();
+        $doc = $tryDoc->get();
+        expect($doc)->sub->toBeNull()
+            ->and($doc->value)->toBeEmpty();
+    });
+    test('does nothing when the field to remove does not exist', function () {
+        expect(Exists::byFields(ThrowawayDb::TABLE, [Field::exists('a_field_that_does_not_exist')]))->toBeFalse();
+        RemoveFields::byId(ThrowawayDb::TABLE, 'one', ['a_field_that_does_not_exist']); // no exception = pass
+    });
+    test('does nothing when the document does not exist', function () {
+        expect(Exists::byId(ThrowawayDb::TABLE, 'fifty'))->toBeFalse();
+        RemoveFields::byId(ThrowawayDb::TABLE, 'fifty', ['sub']); // no exception = pass
+    });
+});
+
+describe('::byFields()', function () {
+    test('removes fields from matching documents', function () {
+        RemoveFields::byFields(ThrowawayDb::TABLE, [Field::equal('num_value', 17)], ['sub']);
+        expect(Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('num_value', 17)], TestDocument::class))
+            ->isSome()->toBeTrue()
+            ->get()->sub->toBeNull();
+    });
+    test('does nothing when the field to remove does not exist', function () {
+        expect(Exists::byFields(ThrowawayDb::TABLE, [Field::exists('nada')]))->toBeFalse();
+        RemoveFields::byFields(ThrowawayDb::TABLE, [Field::equal('num_value', 17)], ['nada']); // no exception = pass
+    });
+    test('does nothing when no documents match', function () {
+        expect(Exists::byFields(ThrowawayDb::TABLE, [Field::notEqual('missing', 'nope')]))->toBeFalse();
+        RemoveFields::byFields(ThrowawayDb::TABLE, [Field::notEqual('missing', 'nope')], ['value']); // no exn = pass
+    });
+});
+
+describe('::byContains()', function () {
+    test('removes fields from matching documents', function () {
+        $criteria = ['sub' => ['foo' => 'green']];
+        RemoveFields::byContains(ThrowawayDb::TABLE, $criteria, ['value']);
+        $docs = Find::byContains(ThrowawayDb::TABLE, $criteria, TestDocument::class);
+        expect($docs)->not->toBeNull()->hasItems()->toBeTrue();
+        foreach ($docs->items() as $item) {
+            expect(['two', 'four'])->toContain($item->id)
+                ->and($item->value)->toBeEmpty();
+        }
+    });
+    test('does nothing when the field to remove does not exist', function () {
+        expect(Exists::byFields(ThrowawayDb::TABLE, [Field::exists('invalid_field')]))->toBeFalse();
+        RemoveFields::byContains(ThrowawayDb::TABLE, ['sub' => ['foo' => 'green']], ['invalid_field']); // no exn = pass
+    });
+    test('does nothing when no documents match', function () {
+        expect(Exists::byContains(ThrowawayDb::TABLE, ['value' => 'substantial']))->toBeFalse();
+        RemoveFields::byContains(ThrowawayDb::TABLE, ['value' => 'substantial'], ['num_value']); // no exception = pass
+    });
+});
+
+describe('::byJsonPath()', function () {
+    test('removes fields from matching documents', function () {
+        $path = '$.value ? (@ == "purple")';
+        RemoveFields::byJsonPath(ThrowawayDb::TABLE, $path, ['sub']);
+        $docs = Find::byJsonPath(ThrowawayDb::TABLE, $path, TestDocument::class);
+        expect($docs)->not->toBeNull()->hasItems()->toBeTrue();
+        foreach ($docs->items() as $item) {
+            expect(['four', 'five'])->toContain($item->id)
+                ->and($item->sub)->toBeNull();
+        }
+    });
+    test('does nothing when the field to remove does not exist', function () {
+        expect(Exists::byFields(ThrowawayDb::TABLE, [Field::exists('submarine')]))->toBeFalse();
+        RemoveFields::byJsonPath(ThrowawayDb::TABLE, '$.value ? (@ == "purple")', ['submarine']); // no exception = pass
+    });
+    test('does nothing when no documents match', function () {
+        expect(Exists::byJsonPath(ThrowawayDb::TABLE, '$.value ? (@ == "mauve")'))->toBeFalse();
+        RemoveFields::byJsonPath(ThrowawayDb::TABLE, '$.value ? (@ == "mauve")', ['value']); // no exception = pass
+    });
+});

tests/Integration/PostgreSQL/ThrowawayDb.php

@@ -0,0 +1,92 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ * @see https://github.com/Zaid-Ajaj/ThrowawayDb The origin concept
+ */
+
+declare(strict_types=1);
+
+namespace Test\Integration\PostgreSQL;
+
+use BitBadger\PDODocument\{AutoId, Configuration, Custom, Definition, Document, DocumentException};
+use Random\RandomException;
+use Test\Integration\{SubDocument, TestDocument};
+
+/**
+ * Utilities to create and destroy a throwaway PostgreSQL database to use for testing
+ */
+class ThrowawayDb
+{
+    /** @var string The table used for document manipulation */
+    public const TABLE = 'test_table';
+
+    /**
+     * Configure the document library for the given database (or the main PostgreSQL connection, if the database name
+     * is not provided; this is used for creating and dropping databases)
+     *
+     * @param string|null $dbName The name of the database to configure (optional, defaults to env or "postgres")
+     * @throws DocumentException If any is encountered
+     */
+    private static function configure(?string $dbName = null): void
+    {
+        Configuration::useDSN(sprintf("pgsql:host=%s;dbname=%s", $_ENV['PDO_DOC_PGSQL_HOST'] ?? 'localhost',
+            $dbName ?? $_ENV['PDO_DOC_PGSQL_DB'] ?? 'postgres'));
+        Configuration::$username = $_ENV['PDO_DOC_PGSQL_USER'] ?? 'postgres';
+        Configuration::$password = $_ENV['PDO_DOC_PGSQL_PASS'] ?? 'postgres';
+        Configuration::resetPDO();
+    }
+
+    /**
+     * Load data into the test table
+     *
+     * @throws DocumentException If any is encountered
+     */
+    public static function loadData(): void
+    {
+        Document::insert(self::TABLE, new TestDocument('one', 'FIRST!', 0));
+        Document::insert(self::TABLE, new TestDocument('two', 'another', 10, new SubDocument('green', 'blue')));
+        Document::insert(self::TABLE, new TestDocument('three', '', 4));
+        Document::insert(self::TABLE, new TestDocument('four', 'purple', 17, new SubDocument('green', 'red')));
+        Document::insert(self::TABLE, new TestDocument('five', 'purple', 18));
+    }
+
+    /**
+     * Create a throwaway PostgreSQL database
+     *
+     * @param bool $withData Whether to initialize this database with data (optional; defaults to `true`)
+     * @return string The name of the database (use to pass to `destroy` function at end of test)
+     * @throws DocumentException|RandomException If any is encountered
+     */
+    public static function create(bool $withData = true): string
+    {
+        $dbName = 'throwaway_' . AutoId::generateRandom(10);
+        self::configure();
+        Custom::nonQuery("CREATE DATABASE $dbName WITH OWNER " . Configuration::$username, []);
+        self::configure($dbName);
+
+        Definition::ensureTable(self::TABLE);
+
+        if ($withData) {
+            self::loadData();
+        }
+
+        return $dbName;
+    }
+
+    /**
+     * Destroy a throwaway PostgreSQL database
+     *
+     * @param string $dbName The name of the PostgreSQL database to be dropped
+     * @throws DocumentException If any is encountered
+     */
+    public static function destroy(string $dbName): void
+    {
+        self::configure();
+        Custom::nonQuery("DROP DATABASE IF EXISTS $dbName WITH (FORCE)", []);
+        Configuration::useDSN('');
+        Configuration::$username = null;
+        Configuration::$password = null;
+        Configuration::resetPDO();
+    }
+}