Ensure example works as a standalone script (#236)

Author: simolus3

.github/workflows/dart.yml

@@ -45,6 +45,12 @@ jobs:
       - name: Run tests
         run: dart test --coverage=coverage
 
+      - name: Test example
+        run: |
+          docker run --detach --name postgres_for_dart_test -p 127.0.0.1:5432:5432 -e POSTGRES_USER=user -e POSTGRES_DATABASE=database -e POSTGRES_PASSWORD=pass postgres
+          dart run example/example.dart
+          docker container rm --force postgres_for_dart_test
+
       # https://www.bradcypert.com/how-to-upload-coverage-to-codecov-for-dart/
       - name: Install coverage tools
         run: dart pub global activate coverage

example/example.dart

@@ -1,28 +1,63 @@
+/// Example for the `postgres` package.
+///
+/// Running the example requires access to a postgres server. If you have docker
+/// installed, you can start a postgres server to run this example with
+///
+/// ```
+/// docker run --detach --name postgres_for_dart_test -p 127.0.0.1:5432:5432 -e POSTGRES_USER=user -e POSTGRES_DATABASE=database -e POSTGRES_PASSWORD=pass postgres
+/// ```
+///
+/// To stop and clear the database server once you're done testing, run
+///
+/// ```
+/// docker container rm --force postgres_for_dart_test
+/// ```
+library;
+
 import 'package:postgres/postgres.dart';
 
 void main() async {
-  final conn = await Connection.open(Endpoint(
-    host: 'localhost',
-    database: 'postgres',
-    username: 'user',
-    password: 'pass',
-  ));
+  final conn = await Connection.open(
+    Endpoint(
+      host: 'localhost',
+      database: 'postgres',
+      username: 'user',
+      password: 'pass',
+    ),
+    // The postgres server hosted locally doesn't have SSL by default. If you're
+    // accessing a postgres server over the Internet, the server should support
+    // SSL and you should swap out the mode with `SslMode.verifyFull`.
+    settings: ConnectionSettings(sslMode: SslMode.disable),
+  );
   print('has connection!');
 
+  // Simple query without results
+  await conn.execute('CREATE TABLE IF NOT EXISTS a_table ('
+      '  id TEXT NOT NULL, '
+      '  totals INTEGER NOT NULL DEFAULT 0'
+      ')');
+
   // simple query
   final result0 = await conn.execute("SELECT 'foo'");
   print(result0[0][0]); // first row, first column
 
-  // name parameter query
+  // Using prepared statements to supply values
   final result1 = await conn.execute(
+    r'INSERT INTO a_table (id) VALUES ($1)',
+    parameters: ['example row'],
+  );
+  print('Inserted ${result1.affectedRows} rows');
+
+  // name parameter query
+  final result2 = await conn.execute(
     Sql.named('SELECT * FROM a_table WHERE id=@id'),
-    parameters: {'id': 'xyz'},
+    parameters: {'id': 'example row'},
   );
-  print(result1.first.toColumnMap());
+  print(result2.first.toColumnMap());
 
   // transaction
   await conn.runTx((s) async {
-    final rs = await s.execute('SELECT count(*) FROM foo');
+    final rs = await s.execute('SELECT count(*) FROM a_table');
     await s.execute(
       r'UPDATE a_table SET totals=$1 WHERE id=$2',
       parameters: [rs[0][0], 'xyz'],
@@ -31,8 +66,8 @@ void main() async {
 
   // prepared statement
   final statement = await conn.prepare(Sql("SELECT 'foo';"));
-  final result2 = await statement.run([]);
-  print(result2);
+  final result3 = await statement.run([]);
+  print(result3);
   await statement.dispose();
 
   // preared statement with types