nui_database

Description:

nui database

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 #



Method
Remark




model()
Specify the database model that extends NUIDatabaseModel


readyCallback()
Add a callback to know when the database is opened and ready


build()
Build the NUIDatabase instance with the builder.



Initialize NUIDatabase with NUIDatabaseBuilder. #
Create a NUIDatabaseBuilder instance to build the NUIDatabase instance.
var builder = NUIDatabaseBuilder();
copied to clipboard
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());
copied to clipboard
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");
});
copied to clipboard
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();
copied to clipboard
A Complete Example for Building A NUIDatabase Instance #
final db = NUIDatabaseBuilder()
.model(XPloreDatabase())
.readyCallback((success, message) {
log("Open database with success : $success");
})
.build();
copied to clipboard
Available Methods for NUIDatabase #



Method
Remark




get()
Get the instance of the built NUIDatabase instance


getOne()
Get a single item from the database


getList()
Get a list of items from the database with optional filters


save()
Save an item into the database


saveList()
Save a list of items into the database


update()
Update an item in the database


updatePartial()
Update specific fields of an item into the database


delete()
Delete an item from the database


clear()
Remove all the items in an entity/table



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");
copied to clipboard
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();
}
copied to clipboard
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),
copied to clipboard
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");
});
copied to clipboard
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);
copied to clipboard
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);
copied to clipboard
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);
copied to clipboard
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");
});
copied to clipboard
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");
});
copied to clipboard
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");
});
copied to clipboard
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());
copied to clipboard