Add documentation page on postgres

docs/lib/snippets/platforms/postgres.dart

@@ -0,0 +1,40 @@
+import 'package:drift/drift.dart';
+import 'package:drift_postgres/postgres.dart';
+import 'package:postgres/postgres_v3_experimental.dart';
+
+part 'postgres.g.dart';
+
+class Users extends Table {
+  UuidColumn get id => customType(PgTypes.uuid).withDefault(genRandomUuid())();
+  TextColumn get name => text()();
+  DateTimeColumn get birthDate => dateTime().nullable()();
+}
+
+@DriftDatabase(tables: [Users])
+class MyDatabase extends _$MyDatabase {
+  MyDatabase(super.e);
+
+  @override
+  int get schemaVersion => 1;
+}
+
+void main() async {
+  final pgDatabase = PgDatabase(
+    endpoint: PgEndpoint(
+      host: 'localhost',
+      database: 'postgres',
+      username: 'postgres',
+      password: 'postgres',
+    ),
+  );
+
+  final driftDatabase = MyDatabase(pgDatabase);
+
+  // Insert a new user
+  await driftDatabase.users.insertOne(UsersCompanion.insert(name: 'Simon'));
+
+  // Print all of them
+  print(await driftDatabase.users.all().get());
+
+  await driftDatabase.close();
+}

docs/pages/docs/Platforms/postgres.md

@@ -0,0 +1,78 @@
+---
+data:
+  title: PostgreSQL support (Alpha)
+  description: Use drift with PostgreSQL database servers.
+  weight: 10
+template: layouts/docs/single
+---
+
+{% block "blocks/pageinfo" %}
+Postgres support is still in development. In particular, drift is waiting for [version 3](https://github.com/isoos/postgresql-dart/issues/105)
+of the postgres package to stabilize. Minor breaking changes or remaining issues are not unlikely.
+{% endblock %}
+
+Thanks to contributions from the community, drift currently has alpha support for postgres with the `drift_postgres` package.
+Without having to change your query code, drift can generate Postgres-compatible SQL for most queries,
+allowing you to use your drift databases with a Postgres database server.
+
+## Setup
+
+Begin by adding both `drift` and `drift_postgres` to your pubspec:
+
+{% assign versions = 'package:drift_docs/versions.json' | readString | json_decode %}
+
+```yaml
+dependencies:
+  drift: ^{{ versions.drift }}
+  drift_postgres: ^{{ versions.drift_postgres }}
+
+dev_dependencies:
+  drift_dev: ^{{ versions.drift_dev }}
+  build_runner: ^{{ versions.build_runner }}
+```
+
+Defining a database with Postgres is no different than defining it for sqlite3 - the
+pages on [Dart]({{ '../setup.md' | pageUrl }}) and [SQL]({{ '../SQL API/index.md' | pageUrl }})
+explain how to define tables picked up by drift.
+
+{% assign snippets = "package:drift_docs/snippets/platforms/postgres.dart.excerpt.json" | readString | json_decode %}
+
+Perhaps this example database is helpful as a starting point:
+
+{% include "blocks/snippet" snippets = snippets name = "(full)" %}
+
+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.
+
+## API extensions
+
+The postgres library provides a few [custom types]({{ '../SQL API/types.md' | pageUrl }}) enabling you to use
+postgres-specific types when writing queries in drift.
+For instance, the `PgTypes.uuid` type used in the example maps to a native UUID column type in Postgres. The
+`gen_random_uuid()` function in postgres is also exposed.
+
+PostgreSQL provides a much larger set of functions, of which currently only a few are exported in the
+`drift_postgres` package. You can call others with a `FunctionCallExpression` - if you do, contributions extending
+`drift_postgres` are always welcome!
+
+## Migrations
+
+In sqlite3, the current schema version is stored in the database file. To support drift's migration API
+being built ontop of this mechanism in Postgres as well, drift creates a `__schema` table storing
+the current schema version.
+
+This migration mechanism works for simple deployments, but is unsuitable for large database setups
+with many application servers connecting to postgres. For those, an existing migration management
+tool is a more reliable alternative. If you chose to manage migrations with another tool, you can
+disable migrations in postgres by passing `enableMigrations: false` to the `PgDatabase` constructor.
+
+## Current state
+
+Drift's support for Postgres is still in development, and the integration tests we have for Postgres are
+less extensive than the tests for sqlite3 databases.
+Also, some parts of the core APIs (like the datetime expressions API) are direct wrappers around SQL
+functions only available in sqlite3 and won't work in Postgres.
+However, you can already create tables (or use an existing schema) and most queries should work already.
+
+If you're running into problems or bugs with the postgres database, please let us know by creating an issue
+or a discussion.

docs/pages/docs/Platforms/vm.md

@@ -1,6 +1,6 @@
 ---
 data:
-  title: Native Drift (Desktop support)
+  title: Native Drift (cross-platform)
   description: Run drift on both mobile and desktop
   weight: 1
 template: layouts/docs/single

docs/pubspec.yaml

@@ -7,6 +7,7 @@ environment:
 
 dependencies:
   drift:
+  drift_postgres:
   path: ^1.8.2
   json_annotation: ^4.8.1
   docsy:
@@ -30,6 +31,7 @@ dependencies:
     hosted: https://simonbinder.eu
     version: ^1.5.10
   test: ^1.18.0
+  postgres: ^2.6.3
 
 dev_dependencies:
   lints: ^2.0.0

docs/tool/write_versions.dart

@@ -17,6 +17,7 @@ class _VersionsBuilder extends Builder {
       'build_runner',
       'drift',
       'drift_dev',
+      'drift_postgres',
     ];
 
     final versions = <String, String>{};

extras/drift_postgres/README.md

@@ -1,4 +1,7 @@
-An experimental postgres backend for Drift.
+`package:drift_postgres` extends [drift](https://drift.simonbinder.eu/) to support
+talking to PostgreSQL databases by using the `postgres` package.
+
+This package is currently in beta.
 
 ## Using this
 
@@ -8,15 +11,23 @@ To use drift_postgres, add this to your `pubspec.yaml`
 ```yaml
 dependencies:
   drift: "$latest version"
-  drift_postgres:
+  drift_postgres: ^0.1.0
-   git:
-    url: https://github.com/simolus3/drift.git
-    path: extras/drift_postgres
 ```
 
-To connect your drift database class to postgres, use a `PgDatabase` from `package:drift_postgres/postgres.dart`.
+To connect your drift database class to postgres, use a `PgDatabase` from `package:drift_postgres/postgres.dart`:
 
-## Testing
+```dart
+final database = AppDatabase(PgDatabase(
+  endpoint: PgEndpoint(
+    host: 'localhost',
+    database: 'postgres',
+    username: 'postgres',
+    password: 'postgres',
+  ),
+));
+```
+
+## Running tests
 
 To test this package, first run
 

extras/drift_postgres/lib/postgres.dart

@@ -10,6 +10,7 @@ import 'package:uuid/uuid.dart';
 import 'src/types.dart';
 
 export 'src/pg_database.dart';
+export 'package:uuid/uuid_value.dart' show UuidValue;
 
 typedef UuidColumn = Column<UuidValue>;
 typedef IntervalColumn = Column<Duration>;

extras/drift_postgres/lib/src/pg_database.dart

@@ -10,10 +10,12 @@ class PgDatabase extends DelegatedDatabase {
     required PgEndpoint endpoint,
     PgSessionSettings? sessionSettings,
     bool logStatements = false,
+    bool enableMigrations = true,
   }) : super(
           _PgDelegate(
             () => PgConnection.open(endpoint, sessionSettings: sessionSettings),
             true,
+            enableMigrations,
           ),
           isSequential: true,
           logStatements: logStatements,
@@ -21,8 +23,11 @@ class PgDatabase extends DelegatedDatabase {
 
   /// Creates a drift database implementation from a postgres database
   /// [connection].
-  PgDatabase.opened(PgSession connection, {bool logStatements = false})
+  PgDatabase.opened(
-      : super(_PgDelegate(() => connection, false),
+    PgSession connection, {
+    bool logStatements = false,
+    bool enableMigrations = true,
+  }) : super(_PgDelegate(() => connection, false, enableMigrations),
             isSequential: true, logStatements: logStatements);
 
   @override
@@ -30,9 +35,14 @@ class PgDatabase extends DelegatedDatabase {
 }
 
 class _PgDelegate extends DatabaseDelegate {
-  _PgDelegate(this._open, this.closeUnderlyingWhenClosed);
+  _PgDelegate(
+    this._open,
+    this.closeUnderlyingWhenClosed,
+    this.enableMigrations,
+  );
 
   final bool closeUnderlyingWhenClosed;
+  final bool enableMigrations;
   final FutureOr<PgSession> Function() _open;
 
   PgSession? _openedSession;
@@ -49,12 +59,17 @@ class _PgDelegate extends DatabaseDelegate {
   @override
   Future<void> open(QueryExecutorUser user) async {
     final session = await _open();
-    final pgVersionDelegate = _PgVersionDelegate(session);
 
-    await pgVersionDelegate.init();
+    if (enableMigrations) {
+      final pgVersionDelegate = _PgVersionDelegate(session);
+
+      await pgVersionDelegate.init();
+      versionDelegate = pgVersionDelegate;
+    } else {
+      versionDelegate = NoVersionDelegate();
+    }
 
     _openedSession = session;
-    versionDelegate = pgVersionDelegate;
   }
 
   @override

extras/drift_postgres/pubspec.yaml

@@ -1,6 +1,6 @@
 name: drift_postgres
-description: Postgres support for drift
+description: Postgres implementation and APIs for the drift database package.
-version: 1.0.0
+version: 0.1.0
 
 environment:
   sdk: '>=3.0.0 <4.0.0'
@@ -8,7 +8,7 @@ environment:
 dependencies:
   collection: ^1.16.0
   drift: ^2.0.0
-  postgres:
+  postgres: ^2.6.3
   meta: ^1.8.0
   uuid: ^4.1.0
 
@@ -23,6 +23,3 @@ dev_dependencies:
 dependency_overrides:
   drift:
     path: ../../drift
-  postgres:
-    git:
-      url: https://github.com/isoos/postgresql-dart.git