jaguar_orm_gen 2.2.30

  • Readme
  • Changelog
  • Installing
  • 67

jaguar_orm_gen #

Source-generated ORM with relations (one-to-one, one-to-many, many-to-many), preloading, cascading, polymorphic relations, etc

Features #

  • Relationships
  • Preloads
  • Cascading
    • Cascaded inserts
    • Cascaded updates
    • Cascaded removals
  • Migration
  • Polymorphic relations
  • Composite primary keys
  • Composite foreign keys

Getting started #

Declaring the Model #

class User {
  @PrimaryKey()
  String id;

  String name;

  static const String tableName = '_user';

  String toString() => "User($id, $name)";
}

Declaring the Bean #

A Bean performs database actions on behalf of the model. In this case, UserBean performs actions for User model. Much of the Bean's functionality will be source generated.

@GenBean()
class UserBean extends Bean<User> with _UserBean {
  UserBean(Adapter adapter) : super(adapter);
}

Generating Bean logic #

jaguar_orm use source_gen and jaguar_orm_gen to generate bean logic from bean specification.

Add the following dependencies to dev_dependencies.

  build_runner:
  jaguar_orm_gen:

Run the following command to generate Bean logic:

pub run build_runner build

Connecting to database #

We will use PostgreSQL for this tutorial. PgAdapter is found in the package jaguar_query_postgres.

final PgAdapter _adapter =
    new PgAdapter('example', username: 'postgres', password: 'dart_jaguar');
await _adapter.connect();

Creating instance of bean #

Beans internally use jaguar_query's Adapter interface to talk to database. Lets create an instance of UserBean.

final userBean = new UserBean(_adapter);

Dropping the table #

await userBean.drop();

Creating a table #

await userBean.createTable();

Inserting a new record #

await userBean.insert(new User()
    ..id = '1'
    ..name = 'teja');

Fetching record by primary key #

User user = await userBean.find('1');

Fetching all records #

List<User> users = await userBean.getAll();

Updating a record #

User user = await userBean.find('1');
user.name = 'teja hackborn';
await userBean.update(user);

Remove by id #

await userBean.remove('1');

Remove all #

await userBean.removeAll();

Examples #

One-To-One example #

class User {
  @PrimaryKey()
  String id;

  String name;

  @HasOne(AddressBean)
  Address address;

  static const String tableName = '_user';

  String toString() => "User($id, $name, $address)";
}

class Address {
  @PrimaryKey()
  String id;

  @BelongsTo(UserBean)
  String userId;

  String street;

  static String tableName = 'address';

  String toString() => "Post($id, $userId, $street)";
}

@GenBean()
class UserBean extends Bean<User> with _UserBean {
  UserBean(Adapter adapter)
      : addressBean = new AddressBean(adapter),
        super(adapter);

  final AddressBean addressBean;

  Future createTable() {
    final st = Sql
        .create(tableName)
        .addStr('id', primary: true, length: 50)
        .addStr('name', length: 50);
    return execCreateTable(st);
  }
}

@GenBean()
class AddressBean extends Bean<Address> with _AddressBean {
  AddressBean(Adapter adapter) : super(adapter);

  Future createTable() {
    final st = Sql
        .create(tableName)
        .addStr('id', primary: true, length: 50)
        .addStr('street', length: 150)
        .addStr('user_id', length: 50, foreignTable: '_user', foreignCol: 'id');
    return execCreateTable(st);
  }
}

/// The adapter
PgAdapter _adapter =
    new PgAdapter('postgres://postgres:dart_jaguar@localhost/example');

main() async {
  // Connect to database
  await _adapter.connect();

  // Create beans
  final userBean = new UserBean(_adapter);
  final addressBean = new AddressBean(_adapter);

  // Drop old tables
  await addressBean.drop();
  await userBean.drop();

  // Create new tables
  await userBean.createTable();
  await addressBean.createTable();

  // Cascaded One-To-One insert
  {
    final user = new User()
      ..id = '1'
      ..name = 'Teja'
      ..address = (new Address()
        ..id = '1'
        ..street = 'Stockholm');
    await userBean.insert(user, cascade: true);
  }

  // Fetch One-To-One preloaded
  {
    final user = await userBean.find('1', preload: true);
    print(user);
  }

  // Manual One-To-One insert
  {
    User user = new User()
      ..id = '2'
      ..name = 'Kleak';
    await userBean.insert(user, cascade: true);

    user = await userBean.find('2');

    final address = new Address()
      ..id = '2'
      ..street = 'Stockholm';
    addressBean.associateUser(address, user);
    await addressBean.insert(address);
  }

  // Manual One-To-One preload
  {
    final user = await userBean.find('2');
    print(user);
    user.address = await addressBean.findByUser(user.id);
    print(user);
  }

  // Preload many
  {
    final users = await userBean.getAll();
    print(users);
    await userBean.preloadAll(users);
    print(users);
  }

  // Cascaded One-To-One update
  {
    User user = await userBean.find('1', preload: true);
    user.name = 'Teja Hackborn';
    user.address.street = 'Stockholm, Sweden';
    await userBean.update(user, cascade: true);
  }

  // Fetch One-To-One relationship preloaded
  {
    final user = await userBean.find('1', preload: true);
    print(user);
  }

  // Cascaded removal of One-To-One relation
  await userBean.remove('1', true);

  // Remove addresses belonging to a User
  await addressBean.removeByUser('2');

  exit(0);
}

Changelog #

2.2.30 #

  • Update dependencies to be ok with last flutter stable

2.2.29 #

  • Fix upsert that wsa not doing on cascade upsert when foreign key used

2.2.28 #

  • Fix upsert when foreign keys are enabled by adding a flag on the generated method

2.2.24 #

  • Fixed bugs related to or expression in generated methods

2.2.23 #

  • onlyNonNull for set columns, insert, upsert and update

2.2.22 #

  • Deduplication in attach during upsert
  • attach gets amn optional upsert parameter to control upsert or insert

2.2.21 #

  • newModel instead of model is used in generated upsert code

2.2.16 #

  • Fixed builder.dart library name

2.2.10 #

  • fetchBy* bug fix when pivots are empty

2.2.8 #

  • Immutability
  • Fixes for reflexive relations

2.2.6 #

  • Fixed autoincrement

2.2.5 #

  • Reflexive relations

2.1.20 #

  • IgnoreColumn on getters fix

2.1.17 #

  • Better exception printing for field parse exceptions

2.1.16 #

  • Dart2 fixes

2.1.15 #

  • Relations without associations

2.1.14 #

  • Generate preloadAll for many-to-many relations
  • Do not generate tableName

2.1.12 #

  • Added only to update

2.1.10 #

  • Removed findWhere and removeWhere. They are now in Bean.

2.1.9 #

  • Added findOneWhere

2.1.8 #

  • Autoincrement cascading

2.1.6 #

  • Return insert id for associations

2.1.5 #

  • Changed NumField to DoubleField

2.1.4 #

  • Using parseValue for parsing value from Database

2.1.2 #

  • Fixed bug where BoolField is generated as BitField

2.1.1 #

  • Dart2 support

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  jaguar_orm_gen: ^2.2.30

2. Install it

You can install packages from the command line:

with pub:


$ pub get

Alternatively, your editor might support pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:jaguar_orm_gen/builder.dart';
import 'package:jaguar_orm_gen/jaguar_orm_cli.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
67
Health:
Code health derived from static analysis. [more]
78
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
50
Overall:
Weighted score of the above. [more]
67
Learn more about scoring.

We analyzed this package on Jul 2, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.8.4
  • pana: 0.13.13

Analysis suggestions

Package not compatible with SDK flutter

Because it is not compatible with any of the supported runtimes: flutter-native, flutter-web

Package not compatible with runtime flutter-native on android

Because of the import of dart:mirrors via the import chain package:jaguar_orm_gen/builder.dartpackage:source_gen/source_gen.dartpackage:source_gen/src/type_checker.dartdart:mirrors

Package not compatible with runtime flutter-native on ios

Because of the import of dart:mirrors via the import chain package:jaguar_orm_gen/builder.dartpackage:source_gen/source_gen.dartpackage:source_gen/src/type_checker.dartdart:mirrors

Package not compatible with runtime flutter-native on linux

Because of the import of dart:mirrors via the import chain package:jaguar_orm_gen/builder.dartpackage:source_gen/source_gen.dartpackage:source_gen/src/type_checker.dartdart:mirrors

Package not compatible with runtime flutter-native on macos

Because of the import of dart:mirrors via the import chain package:jaguar_orm_gen/builder.dartpackage:source_gen/source_gen.dartpackage:source_gen/src/type_checker.dartdart:mirrors

Package not compatible with runtime flutter-native on windows

Because of the import of dart:mirrors via the import chain package:jaguar_orm_gen/builder.dartpackage:source_gen/source_gen.dartpackage:source_gen/src/type_checker.dartdart:mirrors

Package not compatible with runtime flutter-web on web

Because of the import of dart:io via the import chain package:jaguar_orm_gen/builder.dartpackage:source_gen/source_gen.dartpackage:source_gen/src/utils.dartpackage:build/build.dartpackage:build/src/generate/run_post_process_builder.dartpackage:build/src/builder/post_process_builder.dartpackage:build/src/builder/builder.dartpackage:build/src/builder/build_step.dartpackage:build/src/asset/reader.dartpackage:glob/glob.dartpackage:glob/src/list_tree.dartpackage:glob/src/io.dartpackage:glob/src/io_export.dartdart:io

Package not compatible with runtime native-aot

Because of the import of dart:mirrors via the import chain package:jaguar_orm_gen/builder.dartpackage:source_gen/source_gen.dartpackage:source_gen/src/type_checker.dartdart:mirrors

Package not compatible with runtime web

Because of the import of dart:io via the import chain package:jaguar_orm_gen/builder.dartpackage:source_gen/source_gen.dartpackage:source_gen/src/utils.dartpackage:build/build.dartpackage:build/src/generate/run_post_process_builder.dartpackage:build/src/builder/post_process_builder.dartpackage:build/src/builder/builder.dartpackage:build/src/builder/build_step.dartpackage:build/src/asset/reader.dartpackage:glob/glob.dartpackage:glob/src/list_tree.dartpackage:glob/src/io.dartpackage:glob/src/io_export.dartdart:io

Health suggestions

Fix lib/src/common/common.dart. (-9.54 points)

Analysis of lib/src/common/common.dart reported 20 hints, including:

line 8 col 19: Unnecessary new keyword.

line 10 col 16: Unnecessary new keyword.

line 12 col 18: Unnecessary new keyword.

line 14 col 22: Unnecessary new keyword.

line 16 col 18: Unnecessary new keyword.

Fix lib/src/writer/writer.dart. (-6.78 points)

Analysis of lib/src/writer/writer.dart reported 14 hints, including:

line 316 col 9: Use isNotEmpty instead of length

line 425 col 9: Use isNotEmpty instead of length

line 456 col 9: Use isEmpty instead of length

line 458 col 9: Use isEmpty instead of length

line 536 col 9: Use isNotEmpty instead of length

Fix lib/src/parser/parser.dart. (-4.89 points)

Analysis of lib/src/parser/parser.dart reported 10 hints, including:

line 70 col 43: Use = to separate a named parameter from its default value.

line 70 col 69: Use = to separate a named parameter from its default value.

line 135 col 9: DO use curly braces for all flow control structures.

line 191 col 11: DO use curly braces for all flow control structures.

line 205 col 11: DO use curly braces for all flow control structures.

Fix lib/src/hook/hook.dart. (-1.49 points)

Analysis of lib/src/hook/hook.dart reported 3 hints:

line 29 col 15: Unnecessary new keyword.

line 38 col 32: Unnecessary new keyword.

line 41 col 22: Unnecessary new keyword.

Fix lib/src/model/model.dart. (-1 points)

Analysis of lib/src/model/model.dart reported 2 hints:

line 21 col 13: Unnecessary new keyword.

line 114 col 9: Unnecessary new keyword.

Maintenance issues and suggestions

Make sure dartdoc successfully runs on your package's source files. (-10 points)

exitCode: 255 stdout: Documenting jaguar_orm_gen... Initialized dartdoc with 833 libraries in 132.1 seconds Generating docs for library jaguar_orm_gen from package:jaguar_orm_gen/jaguar_orm_cli.dart... Generating docs for library jaguar_orm_gen from package:jaguar_orm_gen/builder.dart... Validating docs... Documented 2 public libraries in 13.7 seconds stderr: warning: unresolved doc reference [GenSerializer], from jaguar_orm_gen.BeanGenerator.generateForAnnotatedElement: (file:///tmp/pub-dartlang-dartdocAKTWDN/pkg/lib/src/hook/hook.dart:25:18) warning: unresolved doc reference [Api], from jaguar_orm_gen.BeanGenerator.generateForAnnotatedElement: (file:///tmp/pub-dartlang-dartdocAKTWDN/pkg/lib/src/hook/hook.dart:25:18) warning: unresolved doc reference [api], from jaguar_orm_gen.BeanGenerator.generateForAnnotatedElement: (file:///tmp/pub-dartlang-dartdocAKTWDN/pkg/lib/src/hook/hook.dart:25:18) warning: jaguar_orm_gen has no library level documentation comments, from jaguar_orm_gen: (file:///tmp/pub-dartlang-dartdocAKTWDN/pkg/lib/builder.dart:1:9) error: failed to write file at: jaguar_orm_gen/jaguar_orm_gen-library.html for symbol jaguar_orm_gen: (file:///tmp/pub-dartlang-dartdocAKTWDN/pkg/lib/builder.dart:1:9) conflicting with file already generated by jaguar_orm_gen: (file:///tmp/pub-dartlang-dartdocAKTWDN/pkg/lib/jaguar_orm_cli.dart:7:9) Dartdoc generates a path and filename to write to for each symbol. jaguar_orm_gen conflicts with another symbol in the generated path, and therefore can not be written out. Changing the name, library name, or class name (if appropriate) of one of the conflicting items can resolve the conflict. Alternatively, use the @nodoc tag in one symbol's documentation comments to hide it. warning: dartdoc generated a broken link to: jaguar_orm_gen/BeanGenerator-class.html (from index.json) warning: dartdoc generated a broken link to: jaguar_orm_gen/BeanGenerator/BeanGenerator.html (from index.json) warning: dartdoc generated a broken link to: jaguar_orm_gen/BeanGenerator/generateForAnnotatedElement.html (from index.json) found 7 warnings and 1 error Unhandled exception: dartdoc encountered 1 errors while processing. #0 Dartdoc.generateDocs (package:dartdoc/dartdoc.dart:225:9)

Support latest dependencies. (-10 points)

The version constraint in pubspec.yaml does not support the latest published versions for 1 dependency (analyzer).

The package description is too short. (-20 points)

Add more detail to the description field of pubspec.yaml. Use 60 to 180 characters to describe the package, what it does, and its target use case.

Maintain an example. (-10 points)

Create a short demo in the example/ directory to show how to use this package.

Common filename patterns include main.dart, example.dart, and jaguar_orm_gen.dart. Packages with multiple examples should provide example/README.md.

For more information see the pub package layout conventions.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0 <3.0.0
analyzer ^0.38.0 0.38.5 0.39.11
build ^1.2.2 1.3.0
jaguar_orm ^2.2.7 2.2.7
jaguar_query ^2.2.9 2.2.9
logging ^0.11.3+2 0.11.4
meta ^1.1.8 1.1.8
source_gen ^0.9.4+6 0.9.4+6 0.9.5
Transitive dependencies
args 1.6.0
async 2.4.1
charcode 1.1.3
convert 2.1.1
crypto 2.1.5
csslib 0.16.1
dart_style 1.3.3 1.3.6
front_end 0.1.27 0.1.29
glob 1.2.0
html 0.14.0+3
js 0.6.2
kernel 0.3.27 0.3.29
matcher 0.12.8
node_interop 1.1.1
node_io 1.1.1
package_config 1.9.3
pedantic 1.9.0 1.9.1
pub_semver 1.4.4
quiver 2.1.3
source_span 1.7.0
stack_trace 1.9.5
string_scanner 1.0.5
term_glyph 1.1.0
typed_data 1.2.0
watcher 0.9.7+15
yaml 2.2.1
Dev dependencies
build_runner ^1.7.2
build_test ^0.10.11
collection ^1.14.12 1.14.13
path ^1.6.4 1.7.0
test ^1.9.4