mirror of https://github.com/AMT-Cheif/drift.git
Add documentation page on postgres
This commit is contained in:
parent
cfa33f9a02
commit
fae81d0456
|
@ -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();
|
||||
}
|
|
@ -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.
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -17,6 +17,7 @@ class _VersionsBuilder extends Builder {
|
|||
'build_runner',
|
||||
'drift',
|
||||
'drift_dev',
|
||||
'drift_postgres',
|
||||
];
|
||||
|
||||
final versions = <String, String>{};
|
||||
|
|
|
@ -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:
|
||||
git:
|
||||
url: https://github.com/simolus3/drift.git
|
||||
path: extras/drift_postgres
|
||||
drift_postgres: ^0.1.0
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
|
|
|
@ -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>;
|
||||
|
|
|
@ -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})
|
||||
: super(_PgDelegate(() => connection, false),
|
||||
PgDatabase.opened(
|
||||
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();
|
||||
|
||||
if (enableMigrations) {
|
||||
final pgVersionDelegate = _PgVersionDelegate(session);
|
||||
|
||||
await pgVersionDelegate.init();
|
||||
versionDelegate = pgVersionDelegate;
|
||||
} else {
|
||||
versionDelegate = NoVersionDelegate();
|
||||
}
|
||||
|
||||
_openedSession = session;
|
||||
versionDelegate = pgVersionDelegate;
|
||||
}
|
||||
|
||||
@override
|
||||
|
|
|
@ -1,6 +1,6 @@
|
|||
name: drift_postgres
|
||||
description: Postgres support for drift
|
||||
version: 1.0.0
|
||||
description: Postgres implementation and APIs for the drift database package.
|
||||
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
|
||||
|
|
Loading…
Reference in New Issue