Code Generation

aim_orm uses build_runner to generate type-safe query builders from your schema definitions.

Setup

1. Add Dependencies

# pubspec.yaml
dependencies:
  aim_orm: ^0.4.0
  aim_orm_postgres: ^0.4.0
  aim_postgres: ^0.4.0

dev_dependencies:
  build_runner: ^2.4.0
  aim_orm_codegen: ^0.4.0

2. Configure Schema Path

Specify your schema file location in pubspec.yaml:

# pubspec.yaml
aim:
  database:
    schema: lib/schema.dart

This tells the code generator and migration tools where to find your table definitions.

TIP

If not specified, the default path is lib/schema, which may be a file or a directory.

3. Define Schema

Create a file with your table definitions:

// lib/tables.dart
import 'package:aim_orm/aim_orm.dart';
import 'package:aim_orm_postgres/aim_orm_postgres.dart';
import 'package:aim_postgres/aim_postgres.dart';

part 'tables.g.dart';

@PgTable('users')
final users = (
  id: uuid('id').primaryKey(),
  name: varchar('name', length: 255),
  email: varchar('email', length: 255).unique(),
  createdAt: timestamp('created_at').withDefaultNow(),
);

@PgTable('posts')
final posts = (
  id: serial('id').primaryKey(),
  userId: uuid('user_id'),
  title: varchar('title', length: 255),
  content: text('content'),
  createdAt: timestamp('created_at').withDefaultNow(),
);

4. Run Code Generation

# One-time build
dart run build_runner build

# Watch mode (regenerate on file changes)
dart run build_runner watch

Generated Code

For each @PgTable definition, the following is generated:

Database Extension

extension PostgresUsersDatabaseX on PostgresDatabase {
  UsersQueryBuilder get users => UsersQueryBuilder(this);
}

This allows you to access tables directly from the database connection:

final db = await PostgresDatabase.connect('...');
db.users  // UsersQueryBuilder
db.posts  // PostsQueryBuilder

Row Type

typedef UsersRow = ({
  String id,
  String name,
  String email,
  DateTime createdAt,
});

Query Builder

class UsersQueryBuilder {
  UsersSelectBuilder select();
  UsersInsertBuilder insert();
  UsersUpdateBuilder update();
  UsersDeleteBuilder delete();
}

File Structure

lib/
├── tables.dart      # Your schema definitions
├── tables.g.dart    # Generated code (do not edit)
└── main.dart        # Your application code

Regenerating Code

Run the build command after modifying schema:

dart run build_runner build --delete-conflicting-outputs

Troubleshooting

"Could not find a file named tables.g.dart"

Make sure you have:

1. Added part 'tables.g.dart'; to your schema file
2. Run dart run build_runner build

Build Errors

# Clean and rebuild
dart run build_runner clean
dart run build_runner build

Next Steps

• Schema Definition - Define tables and columns
• SELECT - Query data
• INSERT - Insert data
• Transactions - Atomic operations