Getting Started with Aqueduct


  1. Install Dart.
  2. Activate the Aqueduct CLI

    pub global activate aqueduct
  3. Create a new project.

    aqueduct create my_project

Open the project directory in an IntelliJ IDE, Atom or Visual Studio Code. All three IDEs have a Dart plugin.

How to Learn Aqueduct

There are different approaches depending on how you prefer to learn.

  • The guided tutorial is a hands-on walkthrough where you build an application while learning basic Aqueduct concepts.
  • The example repository contains a few deployable applications that you may review or tinker with.
  • The guides (located in the menu on this website) dive deeply into the concepts of Aqueduct and show example code.
  • Creating a new project and using the API reference to jump right in.

It is best to first understand how HTTP requests are responded to - the foundation of Aqueduct - before moving on to topics such as the ORM and OAuth 2.0. Both the tutorial and the HTTP guides are the primary source of this information. A project created by the aqueduct tool has example routes connected for modification, too.

Creating a Project

The aqueduct create command-line tool creates new Aqueduct project directories. The default template contains the minimal project structure for running an Aqueduct application. A project name must be snake_case.

aqueduct create my_project_name

Other templates exist that contain foundational code for using Aqueduct's ORM and OAuth 2.0 implementation. These templates can be listed:

aqueduct create list-templates

You may provide the name of a template when creating a project to use that template:

aqueduct create -t db my_project_name

Using the Aqueduct ORM

Aqueduct's ORM uses PostgreSQL. During development, you will need a locally running instance of PostgreSQL. On macOS, installing is a very convenient way to run PostgreSQL locally. For other platforms, see PostgreSQL's downloads page.

When creating a project, use the db template. If adding to an existing project, see this guide.

To create a database, make sure PostgreSQL is running and open the command-line utility to connect to it.


Then, create a database that your application will connect to and a user that it will connect with:

CREATE DATABASE my_database_name;
GRANT ALL ON DATABASE my_database_name TO dart_app;

An application must create a ManagedContext that connects to this database:

class MyProjectSink extends RequestSink {
  MyProjectSink(ApplicationConfiguration config) : super(config) {
    var dataModel = new ManagedDataModel.fromCurrentMirrorSystem();
    var store = new PostgreSQLPersistentStore.fromConnectionInfo(
      "dart_app", "dart", "localhost", 5432, "my_database_name");
    ManagedContext.defaultContext = new ManagedContext(dataModel, store);


Once you have declared ManagedObjects in your application, generate the database schema by generating and executing migrations from your project's directory:

aqueduct db generate
aqueduct db upgrade --connect postgres://dart_app:[email protected]:5432/my_database_name

See the guides on connecting to a database and testing with a database