platform/README.md

115 lines
3.3 KiB
Markdown
Raw Normal View History

2017-06-17 16:45:31 +00:00
# orm
[![Pub](https://img.shields.io/pub/v/angel_orm.svg)](https://pub.dartlang.org/packages/angel_orm)
[![build status](https://travis-ci.org/angel-dart/orm.svg)](https://travis-ci.org/angel-dart/orm)
**This project is currently in the early stages, and may change at any given
time without warning.**
2017-07-09 16:53:35 +00:00
Source-generated PostgreSQL ORM for use with the
[Angel framework](https://angel-dart.github.io).
Now you can combine the power and flexibility of Angel with a strongly-typed ORM.
2017-06-17 16:45:31 +00:00
2017-06-17 16:53:32 +00:00
Currently supported:
* PostgreSQL
2017-07-09 16:53:35 +00:00
# Models
2017-06-17 16:51:01 +00:00
Your model, courtesy of `package:angel_serialize`:
2017-06-17 16:45:31 +00:00
```dart
library angel_orm.test.models.car;
import 'package:angel_framework/common.dart';
2017-06-18 04:19:05 +00:00
import 'package:angel_orm/angel_orm.dart';
2017-06-17 16:45:31 +00:00
import 'package:angel_serialize/angel_serialize.dart';
part 'car.g.dart';
@serializable
2017-06-18 04:19:05 +00:00
@orm
2017-06-17 16:45:31 +00:00
class _Car extends Model {
2017-06-18 04:19:05 +00:00
String make;
String description;
bool familyFriendly;
DateTime recalledAt;
2017-06-17 16:45:31 +00:00
}
```
2017-07-09 16:53:35 +00:00
Models can use the `@Alias()` annotation; `package:angel_orm` obeys it.
2017-06-18 04:19:05 +00:00
After building, you'll have access to a `Query` class with strongly-typed methods that
2017-06-17 16:45:31 +00:00
allow to run asynchronous queries without a headache.
2017-07-09 16:53:35 +00:00
MVC just got a whole lot easier:
2017-06-17 16:45:31 +00:00
```dart
import 'package:angel_framework/angel_framework.dart';
import 'package:postgres/postgres.dart';
import 'car.dart';
import 'car.orm.g.dart';
/// Returns an Angel plug-in that connects to a PostgreSQL database, and sets up a controller connected to it...
2017-06-17 16:48:18 +00:00
AngelConfigurer connectToCarsTable(PostgreSQLConnection connection) {
2017-06-17 16:45:31 +00:00
return (Angel app) async {
2017-06-18 04:19:05 +00:00
// Register the connection with Angel's dependency injection system.
2017-06-17 16:45:31 +00:00
//
// This means that we can use it as a parameter in routes and controllers.
2017-06-18 04:19:05 +00:00
app.container.singleton(connection);
2017-06-17 16:45:31 +00:00
// Attach the controller we create below
2017-06-18 04:19:05 +00:00
await app.configure(new CarService(connection));
2017-06-17 16:45:31 +00:00
};
}
@Expose('/cars')
class CarService extends Controller {
2017-06-18 04:19:05 +00:00
// The `connection` will be injected.
@Expose('/recalled_since_2008')
carsRecalledSince2008(PostgreSQLConnection connection) {
// Instantiate a Car query, which is auto-generated. This class helps us build fluent queries easily.
var cars = new CarQuery(connection);
cars.where
..familyFriendly.equals(false)
..recalledAt.year.greaterThanOrEqualTo(2008);
// Shorter syntax we could use instead...
cars.where.recalledAt.year <= 2008;
// `get()` returns a Stream.
// `get().toList()` returns a Future.
return cars.get().toList();
2017-06-17 16:45:31 +00:00
}
2017-06-18 04:19:05 +00:00
@Expose('/create', method: 'POST')
createCar(PostgreSQLConnection connection) async {
// `package:angel_orm` generates a strongly-typed `insert` function on the query class.
// Say goodbye to typos!!!
var car = await CarQuery.insert(connection, familyFriendly: true, make: 'Honda');
// Auto-serialized using code generated by `package:angel_serialize`
return car;
}
}
```
# Relations
**NOTE**: This is not yet implemented.
* `@HasOne()`
* `@HasMany()`
* `@BelongsTo()`
```dart
@serializable
@orm
abstract class _Author extends Model {
@hasMany // Use the defaults, and auto-compute `foreignKey`
List<Book> books;
// Also supports parameters...
@HasMany(localKey: 'id', foreignKey: 'author_id', cascadeOnDelete: true)
List<Book> books;
@Alias('writing_utensil')
@hasOne
Pen pen;
2017-06-17 16:45:31 +00:00
}
```