nui_database 1.1.2

nui_database: ^1.1.2 copied to clipboard

id: flutter-sdk-nuidatabase title: NUIDatabase Overview sidebar_label: Overview #

NUIDatabase is part of the Flutter SDK that allows you to integrate local database feature into the app in a more convenient and simpler way:

• Simplified Database Initialization - Specify all the entities that are going to be in database, the name of the database and you are good to go.

• Entity Based - Add any entity/table to the database as long as it extends NUIDBEntity. These entities will be json decodable/encodable by default.

• Multiple Database In A Single App - Initialize multiple databases with NUIDatabaseBuilder and access any of the databases from the NUIDatabase instance with the targeted database name.

• Migration Made Easy - All the entity migrations are done automatically, let it be adding a new entity, removing a new entity, adding new fields or removing fields. NUIDatabase automatically detects the changes in the database structure and migrate the database whenever neccessary.

Builder Method for NUIDatabase #

Initialize NUIDatabase with NUIDatabaseBuilder. #

Create a NUIDatabaseBuilder instance to build the NUIDatabase instance.

var builder = NUIDatabaseBuilder();

Specifying the database model for NUIDatabase. #

On the builder method, users are required to specify the database model, which must extends NUIDatabaseModel and provide the name and entities for this database.

class XPloreDatabase extends NUIDatabaseModel{
  static const String name = "xplore.db";
  static NUIDatabase get(){
    return NUIDatabase.get(name);
  }

  String databaseName() => name;

  List<NUIDBEntityMapper> entities() => [
    AppUserEntity(),
    CommentEntity(),
    PlaceEntity(),
    SettingEntity(),
    NUIMediaFileEntity(),
    NotificationEntity(),
    TravelRecordEntity(),
    DailyTrackerEntity(),
    PostEntity(),
    EventEntity()
  ];
}

builder.model(XPloreDatabase());

Adding a Callback To The Builder. #

On the builder method, users can add a callback listener to be notified when the database is opened and ready to be used.

builder.readyCallback((success, message){
    log("Open database successful : $success");
});

Build the NUIDatabase instance #

Once all the configurations are done for the NUIDatabaseBuilder, building the instance will return the instance of the NUIDatabase.

Future<NUIDatabase> db = builder.build();

A Complete Example for Building A NUIDatabase Instance #

final db = NUIDatabaseBuilder()
        .model(XPloreDatabase())
        .readyCallback((success, message) {
            log("Open database with success : $success");
          })
        .build();

Available Methods for NUIDatabase #

Getting the NUIDatabase Instance #

Users can get the NUIDatabase instance for the any specific database as long as it is build previously with NUIDatabaseBuilder.

final db = NUIDatabase.get("xplore.db");

Defining an Entity #

To register an entity to the NUIDatabase, simply create a class that extends NUIDBEntity and implement the abstract methods. Each entity class comes with its individual NUIDBEntityMapper class that represents the identity of this entity. It defines all the fields available for this entity.

class TravelRecord extends NUIDBEntity<TravelRecord>{
  TravelRecord();
  TravelRecord.empty();
  String areacodeLine;
  String lastVisitedDate;
  int lastVisitedDateLong;
  int stayDuration;
  String countryCode;
  bool isBought = false;

  @override
  NUIEntMapper<TravelRecord> mapper() => TravelRecordEntity();
}

class TravelRecordEntity extends NUIDBEntityMapper<TravelRecord>{
  @override
  List<NUIDBField> dbFields() {
    final fields = [
      NUIDBField<TravelRecord>(name: "areacodeLine", type: NUIEntType.STRING, setter: (data, value) => data.areacodeLine = value, getter: (data) => data.areacodeLine, primaryKey: true),
      NUIDBField<TravelRecord>(name: "lastVisitedDate", type: NUIEntType.STRING, setter: (data, value) => data.lastVisitedDate = value, getter: (data) => data.lastVisitedDate),
      NUIDBField<TravelRecord>(name: "lastVisitedDateLong", type: NUIEntType.INTEGER, setter: (data, value) => data.lastVisitedDateLong = value, getter: (data) => data.lastVisitedDateLong),
      NUIDBField<TravelRecord>(name: "stayDuration", type: NUIEntType.INTEGER, setter: (data, value) => data.stayDuration = value, getter: (data) => data.stayDuration),
      NUIDBField<TravelRecord>(name: "countryCode", type: NUIEntType.INTEGER, setter: (data, value) => data.countryCode = value, getter: (data) => data.countryCode),
      NUIDBField<TravelRecord>(name: "isBought", type: NUIEntType.BOOLEAN, setter: (data, value) => data.isBought = value, getter: (data) => data.isBought),
    ];
    return fields;
  }

  @override
  String entityName() => "TravelRecord";

  @override
  TravelRecord newInstance() => TravelRecord.empty();
}

Declaring Non-Primative Field Types #

Most of the time we will need to store objects or list of objects within an entity, NUIDBEntity allows non-primitive fields to be declared in the entity.

final listObjectField = NUIDBField<T>(name: "images", type: NUIEntType.LIST_OBJECT, setter: (data, value) => data.images = asListOfDBObjects(NUIMediaFileEntity(), value), getter: (data) => data.images),

final objectField = NUIDBField<T>(name: "image", type: NUIEntType.OBJECT, setter: (data, value) => data.image = asDBObject(NUIMediaFileEntity(), value), getter: (data) => data.image),

final listStringField = NUIDBField<T>(name: "hashtags", type: NUIEntType.LIST_STRING, setter: (data, value) => data.hashTags = asList<String>(value), getter: (data) => data.hashTags),

Get a Single Item #

• Parameters:

  Name	Type	Nullable	Remark
  entity	NUIDBEntityMapper	N	The entity mapper for this for the entity
  condition	InnerLevelQuery	Y	The filtering conditions for the query
  groupBy	String	Y	Group the query by this field
  orderBy	String	Y	The field for the query sorting
  order	NUIQueryOrder	Y	Order the field by either ascending or descending
  offset	int	Y	Offset the query
  callback	DBQueryCallback	Y	Add a callback to listen to the query result

Example of Getting a Single Item #

final tracker = await NUIDatabase.get("xplore.db").getOne(DailyTrackerEntity(), condition: (condition){
        return condition.where(field: "date", condition: NUIDBQueryType.EQUALS, value: "20200912");
      });

Get a List of Items #

• Parameters:

  Name	Type	Nullable	Remark
  entity	NUIDBEntityMapper	N	The entity mapper for this for the entity
  condition	InnerLevelQuery	Y	The filtering conditions for the query
  groupBy	String	Y	Group the query by this field
  orderBy	String	Y	The field for the query sorting
  order	NUIQueryOrder	Y	Order the field by either ascending or descending
  offset	int	Y	Offset the query
  callback	DBQueryCallback	Y	Add a callback to listen to the query result
  limit	int	Y	Limit the number of items returned from the query

Example of Getting a List of Items #

final lastTravelAreas = await NUIDatabase.get("xplore.db").getList(TravelRecordEntity(), orderBy: Parameters.FIELD_MODIFIED_AT, order: NUIQueryOrder.DESC, limit: 8);

Save an Item #

• Parameters:

  Name	Type	Nullable	Remark
  entity	NUIDBEntity	N	The entity data to be saved
  callback	DBExecuteCallback	Y	A callback to be notified when the save is completed
  recordDate	bool	Y	To save the last saved date for this entity, default is set to true

Example of Saving an Item #

await NUIDatabase.get("xplore.db").save(data);

Save a List of Items #

• Parameters:

  Name	Type	Nullable	Remark
  entities	List<NUIDBEntity>	N	The list of entities to be saved
  callback	DBExecuteCallback	Y	A callback to be notified when the save is completed
  recordDate	bool	Y	To save the last saved date for this entity, default is set to false

Example of Save a List of Items #

await NUIDatabase.get("xplore.db").saveList(items, recordDate: true);

Update an Item #

• Parameters:

  Name	Type	Nullable	Remark
  entity	NUIDBEntity	N	The entity data to be updated
  callback	DBExecuteCallback	Y	A callback to be notified when the update is completed
  condition	InnerLevelQuery	Y	The filtering conditions for the update query

Example of Updating an Item #

await NUIDatabase.get("xplore.db").update(TravelRecord(), condition: (query){
      return query.where(field: "date", type: NUIEntType.DATE, condition: NUIDBQueryType.EQUALS, value: "20200102");
    });

Update an Item by Specific Fields #

• Parameters:

  Name	Type	Nullable	Remark
  entity	NUIDBEntityMapper	N	The entity mapper of the data to be updated
  updates	Map<String, dynamic	N	The map of values to be updated
  callback	DBExecuteCallback	Y	A callback to be notified when the update is completed
  condition	InnerLevelQuery	Y	The filtering conditions for the update query

Example of Updating an Item by Specific Fields #

await NUIDatabase.get("xplore.db").updatePartial(TravelRecordEntity(), {
      "address": "The new address",
      "date" : "20201014"
    }, condition : (query){
      return query.where(field: "date", type: NUIEntType.DATE, condition: NUIDBQueryType.EQUALS, value: "20200102");
    });

Delete an Item #

• Parameters:

  Name	Type	Nullable	Remark
  entity	NUIDBEntityMapper	N	The entity mapper of the data to be deleted
  callback	DBExecuteCallback	Y	A callback to be notified when the delete is completed
  condition	InnerLevelQuery	Y	The filtering conditions for the delete query

Example of Deleting an Item #

await NUIDatabase.get("xplore.db").delete(TravelRecordEntity(), condition : (query){
      return query.where(field: "date", type: NUIEntType.DATE, condition: NUIDBQueryType.EQUALS, value: "20200102");
    });

Clear All Items From an Entity #

• Parameters:

  Name	Type	Nullable	Remark
  entity	NUIDBEntityMapper	N	The entity mapper of the data to be cleared
  callback	DBExecuteCallback	Y	A callback to be notified when the clear is completed

Example of Clearing All Items From an Entity #

await NUIDatabase.get("xplore.db").clear(TravelRecordEntity());