Getting Started

The quickstart will help create a new project from scratch so you can start using Fluent.

Prerequisites

To take advantage of the latest developments in the Dart language, we've chosen to exploit the full power of the new API released with version 3 of the language.

environment:
  sdk: ^3.0.5

Your first project

Create a new Dart project

First, you need to create a new Dart project. If you are not familiar with Dart, you can refer to Official Dart Documentation.

dart create fluent_demo

Add Fluent to your project

Add the following dependencies to your pubspec.yaml file and run dart pub get to install them.

dart pub add fluent_orm

dependencies:
  fluent_orm: ^1.0.0

Create the fluent manager

The manager is a central point in the use of fluent, as it is responsible for the connection to your database, but also allows you to act on it thanks to the QueryBuilder.

import 'package:fluent_orm/fluent_orm.dart';

final psqlClient = PostgresClient(
  database: 'you_database_name',
  host: 'localhost',
  user: 'postgres',
  password: 'postgres',
  port: 5432
);

final FluentManager manager = FluentManager(
  models: [],
  migrations: [],
  client: psqlClient
);

await manager.client.connect();

Structure our database

Now that our client has been created, we need to create the structure of our SQL tables. To do this, we're providing a class dedicated to SQL migrations.

In our example, we're going to create an articles table, which will contain discussion topics.

Discover migrations

final class Article1691342071 extends Schema {
  final String tableName = 'articles';

  @override
  Future<void> up () async {
    schema.createTable(tableName, (table) {
      table.increments('id');
      table.string('title').notNullable();
      table.text('content');
    });
  }

  @override
  Future<void> down () async {
    schema.dropTable(tableName);
  }
}

Although your migration has been created, it is not yet effective in your database.

You must therefore explicitly ask your application to send the contents of your migration via your manager.

final FluentManager manager = FluentManager(
  migrations: [Article1691342071.new],
);

await manager.runMigration();

Using table into your application

Active Record is the philosophy we follow. It introduces an obligation to represent each SQL table within our application in the form of a class.

This clean alternative makes it possible to encapsulate a multitude of methods, to obtain Model-dependent auto-completion and to know every property available for use.

To represent our SQL table, we will extend the Model class provided by Fluent.

import 'package:fluent_orm/fluent_orm.dart';

final class Article extends Model<Article> {
  // model declaration
}

import 'package:fluent_orm/fluent_orm.dart';

final class Article extends Model<Article> {
  Article(): super(properties: ['id', 'title', 'content'])
}

import 'package:fluent_orm/fluent_orm.dart';

final class Article extends Model<Article> {
  Article(): super(properties: ['id', 'title', 'content'])

  int get id => properties.get('id');
  String get title => properties.get('title');
  String get content => properties.get('content');
}

Now that your template is complete, you need to add it to the manager in the appropriate property

final FluentManager manager = FluentManager(
  models: [Article.new],
);

Taking into account the migration, model and manager created earlier, we'll now look at a CRUD in the form of the example below.

Future<void> main () async {
  final Map<String, String> payload = {
    'title': 'My first article',
    'content': 'Lorem ipsum dolor sit amet, consectetur adipiscingd.'
  };
  
  final article = await Database.of(manager)
    .forModel<Article>()
    .insert(payload)
    .save();

  expect(article, isNotNull);
  expect(article, isA<Article>());
}

Future<void> main () async {
  final articles = await Database.of(manager)
    .forModel<Article>()
    .all();

  expect(article, isA<List<Article>>());
}

Future<void> main () async {
  final Article? article = await Database.of(manager)
    .forModel<Article>()
    .where(column: 'id', value: 1)
    .first();
}

Future<void> main () async {
  final article = await Database.of(manager)
    .forModel<Article>()
    .where(column: 'id', value: 1)
    .firstOrFail();
  
  await article.update({ 'title': 'Hello World' });
}

Future<void> main () async {
  final article = await Database.of(manager)
    .forModel<Article>()
    .where(column: 'id', value: 1)
    .firstOrFail();
  
  await article.delete();
}