Document how to use postgres with a conn pool

#3236

docs/docs/Platforms/postgres.md

@@ -51,11 +51,24 @@ targets:
 
 Then, perhaps this example database is helpful as a starting point:
 
-{{ load_snippet('(full)','lib/snippets/platforms/postgres.dart.excerpt.json') }}
+{{ load_snippet('setup','lib/snippets/platforms/postgres.dart.excerpt.json') }}
 
 After starting a database server, for example by running `docker run -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres`,
 you can run the example to see drift talking to Postgres.
 
+## Custom connections and connection pools
+
+The unnamed `PgDatabase` constructor mirrors the options found on the `Endpoint` class in
+`package:postgres`, as it uses that class to establish a connection to PostgreSQL.
+In some cases, for instance because you already have an existing Postgres connection or because
+you need something different from the existing `Endpoint`, you can use `PgDatabase.opened`
+with your existing `Session` from `package:postgres`.
+
+This technique is also useful for pooling connections to Postgres, as the `Pool` implementation
+from `package:postgres` implements the `Session` interface:
+
+{{ load_snippet('pool','lib/snippets/platforms/postgres.dart.excerpt.json') }}
+
 ## API extensions
 
 The postgres library provides a few [custom types](../sql_api/types.md) enabling you to use

docs/lib/snippets/platforms/postgres.dart

@@ -1,3 +1,4 @@
+// #docregion setup
 import 'package:drift/drift.dart';
 import 'package:drift_postgres/drift_postgres.dart';
 import 'package:postgres/postgres.dart';
@@ -43,3 +44,20 @@ void main() async {
 
   await driftDatabase.close();
 }
+// #enddocregion setup
+
+List<Endpoint> get yourListOfEndpoints => throw 'stub';
+
+// #docregion pool
+Future<void> openWithPool() async {
+  final pool = Pool.withEndpoints(yourListOfEndpoints);
+
+  final driftDatabase = MyDatabase(PgDatabase.opened(pool));
+  await driftDatabase.users.select().get();
+
+  // Note that PgDatabase.opened() doesn't close the underlying connection when
+  // the drift database is closed.
+  await driftDatabase.close();
+  await pool.close();
+}
+// #enddocregion pool