Overview
CloudBase Flutter SDK enables you to use CloudBase capabilities in Flutter applications, including authentication, document database, data models, MySQL database, cloud functions, cloud hosting, APIs, and more. For usage, please refer to CloudBase Flutter SDK, or check the sample code.
CloudBase Flutter SDK is fully aligned with HTTP API
SDK is categorized by functionality:
- Authentication: API methods for user registration and login, supporting multiple login methods.
- Session Management: API methods for managing user session state and tokens.
- User Management: API methods for retrieving, updating, and managing user information.
- Identity Source Management: API methods for managing third-party identity source binding and unbinding.
- Password Management: API methods for password reset and change.
- Verification Management: API methods for verification code sending, verification, resending, CAPTCHA creation, verification, and management.
- Document Database: Operations for NoSQL document database including collections, documents, queries, updates, deletions, aggregation, transactions, and more.
- Data Model: Data model CRUD operations.
- Data Source Query: Query data source aggregation list, details, Schema, and table names.
- MySQL Database: MySQL RESTful database operations.
- Cloud Functions: Call cloud functions and function-type cloud hosting.
- Cloud Hosting: Call cloud hosting container services.
- APIs: Call APIs interfaces.
- Cloud Storage: File upload, download, delete, copy, move, and other operations.
Basic Usage Example
- Initialization
- Login Status Check
- User Registration Flow
- Password Login
- Logout
- Listen for State Changes
- Call Cloud Function
accessKey can be generated in CloudBase Platform/API Key Configuration
import 'package:cloudbase_flutter/cloudbase_flutter.dart';
// Initialize (async)
final app = await CloudBase.init(
env: 'your-env-id', // Replace with your environment ID
region: 'ap-shanghai', // Region, default is Shanghai
accessKey: 'your-key', // Fill in the generated Publishable Key
authConfig: AuthConfig(
detectSessionInUrl: true, // Optional: automatically detect OAuth parameters in URL
),
);
final auth = app.auth;
// Check login status
Future<bool> checkAuthStatus() async {
final result = await auth.getSession();
if (result.error != null) {
print('Failed to check login status: ${result.error!.message}');
return false;
}
if (result.data?.session != null) {
print('User is logged in: ${result.data!.user?.id}');
return true;
} else {
print('User is not logged in');
return false;
}
}
// User registration example (two-step verification flow)
Future<void> registerUser(String email, String password) async {
// Step 1: Send verification code
final signUpResult = await auth.signUp(SignUpReq(
email: email,
password: password,
));
if (signUpResult.error != null) {
print('Failed to send verification code: ${signUpResult.error!.message}');
return;
}
print('Verification code sent, waiting for user input...');
// Step 2: Verify verification code and complete registration
final verifyResult = await signUpResult.data!.verifyOtp!(
VerifyOtpParams(token: 'User input verification code'),
);
if (verifyResult.error != null) {
print('Registration failed: ${verifyResult.error!.message}');
} else {
print('Registration successful: ${verifyResult.data?.user?.id}');
}
}
// Password login example
Future<void> loginWithPassword(String email, String password) async {
final result = await auth.signInWithPassword(
SignInWithPasswordReq(email: email, password: password),
);
if (result.error != null) {
print('Login failed: ${result.error!.message}');
} else {
print('Login successful: ${result.data?.user?.id}');
print('Access Token: ${result.data?.session?.accessToken}');
}
}
// Logout example
Future<void> logout() async {
await auth.signOut();
print('Logged out');
}
// Listen for authentication state changes
final result = auth.onAuthStateChange((event, session, info) {
switch (event) {
case AuthStateChangeEvent.signedIn:
print('User signed in');
break;
case AuthStateChangeEvent.signedOut:
print('User signed out');
break;
case AuthStateChangeEvent.tokenRefreshed:
print('Token refreshed');
break;
case AuthStateChangeEvent.userUpdated:
print('User info updated');
break;
default:
break;
}
});
// Unsubscribe
result.data?.subscription.unsubscribe();
// Call cloud function example
final result = await app.callFunction(
name: 'myFunction',
data: {'key': 'value'},
);
if (result.isSuccess) {
print('Execution result: ${result.result}');
} else {
print('Execution failed: ${result.message}');
}
Authentication
signUp
Future<SignUpRes> auth.signUp(SignUpReq params)
Register a new user account using smart registration and login flow.
- Creates a new user account
- Uses smart registration and login flow: send verification code → wait for user input → smart judgment of user existence → auto login or register and login
- If user already exists, directly login; if user does not exist, register new user and auto login
参数
返回
示例
signInAnonymously
Future<SignInRes> auth.signInAnonymously({String? providerToken})
Anonymous login, creates a temporary anonymous user account.
- Creates a temporary anonymous user account
- No identity verification info needed
- Suitable for scenarios requiring temporary access
参数
Third-party platform token, used to associate third-party platform identity
返回
示例
signInWithPassword
Future<SignInRes> auth.signInWithPassword(SignInWithPasswordReq params)
Login with password. Supports login via username, email, or phone number.
参数
返回
示例
signInWithOtp
Future<SignInWithOtpRes> auth.signInWithOtp(SignInWithOtpReq params)
Login with OTP (one-time verification code). After calling, a verification code will be sent. You need to complete verification through the returned verifyOtp callback.
- If the user does not exist, a user will be created by default. You can control whether to automatically create a user with the
shouldCreateUserparameter (default is true)
参数
返回
示例
signInWithOAuth
Future<SignInOAuthRes> auth.signInWithOAuth(SignInWithOAuthReq params)
Login with OAuth third-party platform. Returns authorization URL, you need to guide the user to redirect to this URL to complete authorization.
参数
返回
示例
signInWithIdToken
Future<SignInRes> auth.signInWithIdToken(SignInWithIdTokenReq params)
Login with IdToken. Suitable for scenarios where third-party platform tokens have been obtained.
参数
返回
示例
signInWithCustomTicket
Future<SignInRes> auth.signInWithCustomTicket(Future<String> Function() getTicketFn)
Login with custom ticket. By passing an async function to get the ticket, the server generates the ticket and completes the login.
参数
Async function to get custom login ticket
返回
示例
Session Management
getSession
Future<SignInRes> auth.getSession();
Get current session. If token has expired, it will be automatically refreshed.
参数
无参数
返回
示例
refreshSession
Future<SignInRes> auth.refreshSession([String? refreshToken])
Refresh session. Use Refresh Token to get a new Access Token.
参数
Refresh token (optional, defaults to current session's refreshToken)
返回
示例
setSession
Future<SignInRes> auth.setSession(SetSessionReq params)
Set session. Restore session state with Refresh Token.
参数
返回
示例
signOut
Future<SignOutRes> auth.signOut([SignOutReq? params])
Logout. Clear local session and notify server to revoke token.
参数
Logout configuration options (optional)
返回
示例
onAuthStateChange
OnAuthStateChangeResult auth.onAuthStateChange(OnAuthStateChangeCallback callback)
Listen for authentication state changes. Supports listening for login, logout, token refresh, and user update events.
参数
State change callback function
返回
示例
getClaims
Future<GetClaimsRes> auth.getClaims();
Get JWT Claims of current Access Token (token claims).
参数
无参数
返回
示例
User Management
getUser
Future<GetUserRes> auth.getUser();
Get current logged-in user info.
参数
无参数
返回
示例
refreshUser
Future<SignInRes> auth.refreshUser();
Refresh user info. Re-fetch the latest user data from server and update local session.
参数
无参数
返回
示例
updateUser
Future<UpdateUserRes> auth.updateUser(UpdateUserReq params)
Update user info. If updating email or phone number, verification code verification is required.
参数
返回
示例
deleteUser
Future<CloudBaseResponse<void>> auth.deleteUser(DeleteUserReq params)
Delete current user. Password is required for security verification.
参数
返回
示例
Identity Source Management
getUserIdentities
Future<GetUserIdentitiesRes> auth.getUserIdentities();
Get the list of identity sources bound to the current user.
参数
无参数
返回
示例
linkIdentity
Future<LinkIdentityRes> auth.linkIdentity(LinkIdentityReq params)
Bind third-party identity source. Will redirect to third-party authorization page to complete binding.
参数
返回
示例
unlinkIdentity
Future<CloudBaseResponse<void>> auth.unlinkIdentity(UnlinkIdentityReq params)
Unbind third-party identity source.
参数
返回
示例
Password Management
resetPasswordForEmail
Future<ResetPasswordForEmailRes> auth.resetPasswordForEmail(String emailOrPhone, {String? redirectTo})
Reset password via email or phone number. After calling, a verification code will be sent. You need to complete password reset through the returned updateUser callback.
参数
Email or phone number
Redirect URL
返回
示例
resetPasswordForOld
Future<SignInRes> auth.resetPasswordForOld(ResetPasswordForOldReq params)
Reset password with old password.
参数
返回
示例
reauthenticate
Future<ReauthenticateRes> auth.reauthenticate();
Re-authenticate. Send verification code to user's email or phone number. After verification, sensitive operations can be performed (such as setting a new password).
参数
无参数
返回
示例
Verification Management
getVerification
Future<GetVerificationRes> auth.getVerification(GetVerificationReq params)
Send verification code. Supports sending to email or phone number.
参数
返回
示例
verify
Future<VerifyRes> auth.verify(VerifyReq params)
Verify verification code (for email/phone verification).
参数
返回
示例
verifyOAuth
Future<SignInRes> auth.verifyOAuth(VerifyOAuthReq params)
Verify OAuth callback. Handle the callback after user authorization on third-party platform.
参数
返回
示例
verifyOtp
Future<SignInRes> auth.verifyOtp(VerifyOtpParams params)
Verify OTP (one-time password). Used to verify the verification code sent by signInWithOtp or signUp.
参数
返回
示例
resend
Future<ResendRes> auth.resend(ResendReq params)
Resend verification code.
参数
返回
示例
getCaptchaToken
Future<GetCaptchaTokenRes> auth.getCaptchaToken()
Get CAPTCHA token. Used to get CAPTCHA verification token before sending verification code.
参数
无参数
返回
示例
createCaptchaData
Future<CreateCaptchaDataRes> auth.createCaptchaData(CreateCaptchaDataReq params)
Create CAPTCHA verification data. Used to initialize CAPTCHA challenge.
参数
返回
示例
verifyCaptchaData
Future<VerifyCaptchaDataRes> auth.verifyCaptchaData(VerifyCaptchaDataReq params)
Verify CAPTCHA. Validate user's CAPTCHA response.
参数
返回
示例
clearCaptchaToken
Future<ClearCaptchaTokenRes> auth.clearCaptchaToken()
Clear CAPTCHA token. Clean up CAPTCHA state after verification.
参数
无参数
返回
示例
Document Database
The document database (NoSQL) provides JS SDK-style chained calls, and you get an instance via app.database(). It supports create, read, update, and delete operations on collections and documents, complex conditional queries, aggregation, transactions, and more, and is fully aligned with the HTTP API.
- Initialize & Add
- Conditional Query
- Update & Delete
- Transaction
final app = await CloudBase.init(env: 'your-env-id');
final db = app.database();
// Add a single record
final addRes = await db.collection('todos').add({
'title': 'Learn CloudBase',
'completed': false,
'createdAt': DateTime.now(),
});
print('New document ID: ${addRes.id}');
final db = app.database();
final _ = db.command;
final res = await db
.collection('todos')
.where({'completed': false, 'priority': _.inList(['high', 'medium'])})
.orderBy('createdAt', OrderDirection.desc)
.limit(10)
.get();
print('Query results: ${res.data}');
final db = app.database();
final _ = db.command;
// Update a single document, increment a field
await db.collection('todos').doc('doc-id').update({'count': _.inc(1)});
// Delete a single document
await db.collection('todos').doc('doc-id').remove();
final db = app.database();
final _ = db.command;
final transaction = await db.startTransaction();
try {
await transaction.collection('accounts').doc('a').update({'balance': _.inc(-100)});
await transaction.collection('accounts').doc('b').update({'balance': _.inc(100)});
await transaction.commit();
} catch (e) {
await transaction.rollback();
}
database
CloudBaseDatabase app.database({String? instance, String? database})
Gets a document database instance. The optional parameters instance (instance ID) and database (database name) specify the database to access. Both can be omitted, in which case (default) is used (the default database of the default instance). You only need to pass them explicitly when accessing a non-default instance or database.
参数
Instance ID, defaults to (default)
Database name, defaults to (default)
返回
Database instance, providing capabilities such as collection, command, Geo, and startTransaction
示例
createCollection
Future<DbCreateCollectionResult> db.createCollection(String collName)
Creates a collection.
参数
Collection name
返回
示例
collection
CollectionReference db.collection(String collName)
Gets a collection reference, on which you can chain query methods such as where, orderBy, limit, skip, and field, or call doc, add, get, count, and aggregate.
参数
Collection name
返回
Collection reference
示例
add
Future<DbAddResult> collection.add(dynamic data)
Adds records to a collection, supporting single (Map) and batch (List) additions.
参数
Document data. Pass a Map for a single addition, or a List for batch addition
返回
示例
doc
DocumentReference collection.doc(dynamic docId)
Gets a document reference, on which you can call get, update, set, remove, and field.
参数
Document ID
返回
Document reference
示例
where
Query collection.where(Map<String, dynamic> condition)
Sets query conditions, supporting equality matching and complex condition filtering via db.command operators.
参数
Query condition object, supporting equality matching, operator matching, nested field matching, and more
返回
Query object, on which you can chain methods such as orderBy, limit, skip, field, get, count, update, and remove
示例
orderBy
Query collection.orderBy(String field, OrderDirection direction)
Sets the sort rule. direction can be OrderDirection.asc or OrderDirection.desc. You can call it multiple times to combine multi-field sorting.
参数
Sort field
Sort direction: OrderDirection.asc (ascending) or OrderDirection.desc (descending)
返回
Query object, on which you can continue chaining
示例
limit
Query collection.limit(int max)
Sets the maximum number of records to return.
参数
Maximum number of records to return
返回
Query object, on which you can continue chaining
示例
skip
Query collection.skip(int offset)
Sets the number of records to skip, commonly used for pagination.
参数
Number of records to skip (offset)
返回
Query object, on which you can continue chaining
示例
field
Query collection.field(Map<String, dynamic> projection)
Specifies the fields to return in the query. true means return, and false means do not return. The document reference doc also supports the field method.
参数
Field projection, e.g. {'title': true, 'content': false}
返回
Query object, on which you can continue chaining
示例
get
Future<DbGetResult> collection.get()
Future<DbGetResult> query.get()
Future<DbGetResult> doc.get()
Gets query results. Called on a collection reference, it performs an unconditional query; called on a Query, it returns the list of matching documents; called on a document reference, it returns a single document (data is an empty list when the document does not exist).
参数
无参数
返回
示例
count
Future<DbCountResult> collection.count()
Future<DbCountResult> query.count()
Counts the number of documents matching the conditions.
参数
无参数
返回
示例
update
Future<DbUpdateResult> query.update(Map<String, dynamic> data)
Future<DbUpdateResult> doc.update(Map<String, dynamic> data, {bool returnDoc = false})
Updates documents. Called on a Query, it batch-updates documents matching the conditions; called on a document reference, it performs a merge update on a single document, and returns the updated document when returnDoc is true.
参数
Update data. You can use db.command update operators (such as _.inc, _.set, _.push, etc.)
Supported only by document reference update. When true, returns the updated document. Defaults to false
返回
示例
set
Future<DbUpdateResult> doc.set(Map<String, dynamic> data)
Sets document data (full replacement; creates the document if it does not exist).
参数
Full document data, which will completely replace the original document
返回
示例
remove
Future<DbRemoveResult> query.remove()
Future<DbRemoveResult> doc.remove()
Deletes documents. Called on a Query, it batch-deletes documents matching the conditions; called on a document reference, it deletes a single document.
参数
无参数
返回
示 例
command
DbCommand get db.command
Gets the query/update command (corresponding to the JS SDK's db.command, commonly abbreviated as _). It supports comparison, logical, field/array, update, geolocation, and other operators.
参数
无参数
返回
Command object, used to build query conditions and update operations
示例
aggregate
Aggregate collection.aggregate()
Gets an aggregation operation object. Chain aggregation stages and then call end() to execute. Supports match, group, sort, project, limit, skip, unwind, lookup, addFields, count, sample, bucket, bucketAuto, geoNear, replaceRoot, sortByCount, and custom stage.
参数
无参数
返回
Aggregation operation object. Chain stages and then call end() to execute
示例
startTransaction
Future<Transaction> db.startTransaction()
Starts a transaction and returns a transaction object. Use the transaction object's collection to get a collection reference within the transaction to operate on, and finally call commit to commit or rollback to roll back.
参数
无参数
返回
示例
runCommands
Future<DbRunCommandsResult> db.runCommands({required List<Map<String, dynamic>> commands, String? transactionId})
Executes native MongoDB database commands (in batch). Callable by administrators only.
参数
Array of command objects
Transaction ID (optional, executes all commands within the transaction)
返回
示例
Geo
GeoNamespace get db.Geo
DbRegExp db.RegExp({required String regexp, String? options})
DbServerDate db.serverDate({int offset = 0})
Database helper types: the geolocation namespace Geo, the regular expression RegExp, and the server-side time serverDate.
Geosupportspoint,lineString,polygon,multiPoint,multiLineString, andmultiPolygon, used together with the operatorsgeoNear,geoWithin, andgeoIntersects.RegExpis used for fuzzy queries;optionssuch asimeans case-insensitive.serverDategenerates server-side time, whereoffsetis the offset in milliseconds.
参数
无参数
返回
Geolocation namespace
示例
Data Model
getById
Future<GetByIdRes> app.data.model(collectionName).getById(String id)
Get a single record by ID.
参数
Record ID
返回
示例
get
Future<GetRes> app.data.model(collectionName).get([GetReq? params])
Query records with filters. Supports WHERE conditions, sorting, pagination, etc.
参数
Query parameters (optional)
返回
示例
list
Future<ModelFindManyResponse> app.models.list({
required String modelName,
Map<String, dynamic>? filter,
Map<String, dynamic>? select,
int? pageSize,
int? pageNumber,
bool? getCount,
List<Map<String, String>>? orderBy,
})
Query multiple records. Supports filter conditions, field selection, pagination, and sorting.
参数
Data model identifier
Filter condition, format: {'where': {'field': {'\$eq': 'value'}}}
Field selection, format: {'\$master': true} or {'field': true}
Page size, default 10
Page number, default 1
Whether to return total count
Sorting, up to 3 fields, format: [{'field': 'desc'}]
返回
示例
listSimple
Future<ModelFindManyResponse> app.models.listSimple({required String modelName, int? pageSize, int? pageNumber, bool? getCount})
Simple query for multiple records (GET request, only supports pagination parameters).
参数
Data model identifier
Page size
Page number, default 1
Whether to return total count, default false
返回
示例
create
Future<ModelCreateResponse> app.models.create({required String modelName, required Map<String, dynamic> data})
Create a single record.
参数
Data model identifier
Record data
返回
示例
createMany
Future<ModelCreateManyResponse> app.models.createMany({required String modelName, required List<Map<String, dynamic>> data})
Batch create records.
参数
Data model identifier
List of records to create
返回
示例
update
Future<ModelUpdateDeleteResponse> app.models.update({required String modelName, required Map<String, dynamic> filter, required Map<String, dynamic> data})
Update a single record.
参数
Data model identifier
Filter condition
Data to update
返回
示例
updateMany
Future<ModelUpdateDeleteManyResponse> app.models.updateMany({required String modelName, required Map<String, dynamic> filter, required Map<String, dynamic> data})
Batch update records.
参数
Data model identifier
Filter condition
Data to update
返回
示例
upsert
Future<ModelUpsertResponse> app.models.upsert({required String modelName, required Map<String, dynamic> filter, Map<String, dynamic>? create, Map<String, dynamic>? update})
Create or update a single record (Upsert). If a matching record is found, it will be updated; otherwise, a new record will be created.
参数
Data model identifier
Filter condition
Data to create when record does not exist
Data to update when record already exists
返回
示例
deleteById
Future<ModelUpdateDeleteResponse> app.models.deleteById({required String modelName, required String recordId})
Delete a single record by ID.
参数
Data model identifier
Record ID
返回
示例
deleteRecord
Future<ModelUpdateDeleteResponse> app.models.deleteRecord({required String modelName, required Map<String, dynamic> filter})
Delete a single record by condition.
参数
Data model identifier
Filter condition
返回
示例
deleteMany
Future<ModelUpdateDeleteManyResponse> app.models.deleteMany({required String modelName, required Map<String, dynamic> filter})
Batch delete records.
参数
Data model identifier
Filter condition
返回
示例
mysqlCommand
Future<ModelMysqlCommandResponse> app.models.mysqlCommand({required String sqlTemplate, List<ModelMysqlParameter>? parameter, ModelMysqlConfig? config})
Execute MySQL commands. Supports parameterized queries.
参数
SQL statement, supports parameter placeholders {{ var }}
SQL parameter list
Execution config (timeout, preparedStatements, dbLinkName)
返回
示例
Data Source Queries
getAggregateDataSourceList
Future<AggregateDataSourceListResponse> app.models.getAggregateDataSourceList({
List<String>? idList,
List<String>? nameList,
int? pageSize,
int? pageNumber,
bool? getCount,
List<Map<String, String>>? orderBy,
})
Query aggregate data source list (GET request, supports pagination and sorting).
参数
Data source ID list
Data source name list
Page size, default 10
Page number, default 1
Whether to return total count
Sorting, format: [{'field': 'desc'}]
返回
示例
getDataSourceAggregateDetail
Future<DataSourceAggregateDetailResponse> app.models.getDataSourceAggregateDetail({
String? datasourceId,
String? dataSourceName,
String? viewId,
int? queryPublish,
bool? queryModelRelation,
String? dbInstanceType,
String? databaseTableName,
})
Query aggregate data source detail by conditions. datasourceId and dataSourceName cannot both be empty.
参数
Data source ID (cannot both be empty with dataSourceName)
Data source name (cannot both be empty with datasourceId)
View ID
Query published data source (0: preview, 1: published)
Whether to query relation
DB instance type
Database table name
返回
示例
getDataSourceByTableName
Future<DataSourceByTableNameResponse> app.models.getDataSourceByTableName({required List<String> tableNames})
Query data source schema definition by database table name.
参数
Database table name list
返回
示例
getBasicDataSourceList
Future<BasicDataSourceListResponse> app.models.getBasicDataSourceList({
List<String>? idList,
List<String>? nameList,
int? pageNum,
int? pageSize,
bool? queryAll,
List<DataSourceQueryFilter>? queryFilterList,
bool? onlyFlexDb,
})
Query basic data source list by conditions (POST request, supports filter conditions).
参数
Data source ID list
Data source name list
Page number, default 1
Page size, default 10
Whether to query all
Query filter list
Whether to query only flexdb type
返回
示例
getBasicDataSource
Future<BasicDataSourceResponse> app.models.getBasicDataSource({
String? datasourceId,
String? dataSourceName,
String? viewId,
int? queryPublish,
bool? queryModelRelation,
String? dbInstanceType,
String? databaseTableName,
})
Query basic data source info by conditions. datasourceId and dataSourceName cannot both be empty.
参数
Data source ID (cannot both be empty with dataSourceName)
Data source name (cannot both be empty with datasourceId)
View ID
Query published data source (0: preview, 1: published)
Whether to query relation
DB instance type
Database table name
返回
示例
getSchemaList
Future<DataSourceSchemaListResponse> app.models.getSchemaList({List<String>? dataSourceNameList})
Query all data source schemas in the environment. If no parameters are provided, all schemas are returned.
参数
Data source name list (optional, query all if not provided)
返回
示例
getTableName
Future<DataSourceTableNameResponse> app.models.getTableName({String? dataSourceName})
Query the corresponding database table name by data source name.
参数
Data source name
返回
示例
MySQL Database
query
Future<MySqlResponse> app.mysql.query({required String table, String? schema, String? instance, MySqlQueryOptions? options})
Query MySQL data. Supports field selection, pagination, sorting, and filter conditions.
Supported filter operators: eq (equal), neq (not equal), gt (greater than), gte (greater than or equal), lt (less than), lte (less than or equal), like (fuzzy match), in (in list), is (null check)
参数
Table name
Database name
Database instance identifier (requires schema)
Query options
返回
示例
insert
Future<MySqlWriteResponse> app.mysql.insert({required String table, required dynamic data, String? schema, String? instance, bool? upsert, String? onConflict})
Insert data. Supports single and batch insert, as well as Upsert mode.
参数
Table name
Insert data, single Map or batch List<Map>
Database name
Database instance identifier
Whether to enable Upsert mode (default false)
Upsert conflict field
返回
示例
update (MySQL)
Future<MySqlWriteResponse> app.mysql.update({required String table, required Map<String, dynamic> data, required Map<String, String> filters, String? schema, String? instance})
Update MySQL data. WHERE condition is required.
参数
Table name
Data to update
WHERE condition (cannot be empty)
Database name
Database instance identifier
返回
示例
delete (MySQL)
Future<MySqlWriteResponse> app.mysql.delete({required String table, required Map<String, String> filters, String? schema, String? instance})
Delete MySQL data. WHERE condition is required.
参数
Table name
WHERE condition (cannot be empty)
Database name
Database instance identifier
返回
示例
count
Future<MySqlCountResponse> app.mysql.count({required String table, Map<String, String>? filters, String? schema, String? instance})
Count MySQL data records.
参数
Table name
Filter conditions
Database name
Database instance identifier
返回
示例
Cloud Functions
callFunction
Future<FunctionResponse> app.callFunction({
required String name,
FunctionType? type,
Map<String, dynamic>? data,
HttpMethod? method,
String? path,
Map<String, String>? header,
bool? parse,
})
Call cloud function. Supports both basic cloud functions and function-type cloud run.
参数
Function/service name
Call type: FunctionType.function (default) / FunctionType.cloudrun
Request data
HTTP method (only valid for cloudrun type, default POST)
HTTP path (only valid for cloudrun type, default /)
HTTP headers (only valid for cloudrun type)
Whether to parse return object (only valid for function type, default true)
返回
示例
Cloud Run
callContainer
Future<CloudRunResponse> app.callContainer({
required String name,
HttpMethod? method,
String? path,
Map<String, String>? header,
Map<String, dynamic>? data,
})
Call cloud run container service. Supports custom HTTP method, path, and headers.
参数
Cloud run service name
HTTP request method (default GET)
HTTP request path (default /)
HTTP request headers
HTTP request body
返回
示例
APIs
apis[name]
ApiMethodProxy app.apis[String apiName]
Call API gateway interface. Supports accessing API proxy objects via subscript operator for chained calls. Supports GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH methods.
参数
API name
返回
API method proxy object, supports chained calls
API response
示例
Cloud Storage
Cloud Storage module provides file upload, download, delete, copy, move and other operations.
Initialization
final app = await CloudBase.init(
env: 'your-env-id',
accessKey: 'your-access-key',
);
final storage = app.storage.from();
upload
Future<StorageResponse<StorageUploadResult>> storage.upload(
String path,
List<int> fileData, {
StorageUploadOptions? options,
})
Upload file to cloud storage. This method will first get upload info, then upload file to COS, and finally return fileID.
参数
Cloud storage relative path, e.g. `images/photo.jpg`.
File byte data.
Upload options.
返回
CloudBase fileID.
Upload path.
File full path.
Error message.
示例
getUploadInfo
Future<StorageResponse<List<StorageUploadInfo>>> storage.getUploadInfo(
List<String> paths,
)
Get file upload info. Returns upload URL and other info for client to directly upload files to COS.
参数
File path list (cloud storage relative path).
返回
Upload info list.
Error message.
示例
getDownloadUrls
Future<StorageResponse<List<StorageDownloadInfo>>> storage.getDownloadUrls(
List<String> fileIds, {
int? expiresIn,
})
Get file download URLs.
参数
File ID list (full cloudObjectId, e.g. `cloud://envId.xxx/path/file.jpg`).
Reserved parameter, current API does not support custom expiration time.
返回
Download info list.
Error message.
示例
createSignedUrl
Future<StorageResponse<String>> storage.createSignedUrl(
String fileId,
int expiresIn,
)
Create signed URL (temporary access link).
参数
Full fileID.
Expiration time (seconds).
返回
Signed URL.
Error message.
示例
createSignedUrls
Future<StorageResponse<List<StorageDownloadInfo>>> storage.createSignedUrls(
List<String> fileIds,
int expiresIn,
)
Batch create signed URLs.
参数
Full fileID list.
Expiration time (seconds).
返回
Download info list.
Error message.
示例
remove
Future<StorageResponse<List<StorageDeleteResult>>> storage.remove(
List<String> fileIds,
)
Delete files.
参数
File ID list to delete (full fileID).
返回
Delete result list.
Error message.
示例
copy
Future<StorageResponse<StorageCopyResult>> storage.copy(
String fromPath,
String toPath, {
bool overwrite = true,
})
Copy file.
参数
Source file path (relative path).
Target file path (relative path).
Whether to overwrite if target exists, default `true`.
返回
Copy result.
Error message.
示例
copyBatch
Future<StorageResponse<List<StorageCopyResult>>> storage.copyBatch(
List<Map<String, dynamic>> items,
)
Batch copy files.
参数
Copy item list, each item contains `srcPath` and `dstPath`.
返回
Copy result list.
Error message.
示例
move
Future<StorageResponse<StorageCopyResult>> storage.move(
String fromPath,
String toPath, {
bool overwrite = true,
})
Move file (implemented by copy + removeOriginal).
参数
Source file path (relative path).
Target file path (relative path).
Whether to overwrite if target exists, default `true`.
返回
Move result.
Error message.
示例
Storage Related Types
StorageUploadOptions
Upload options:
| Parameter | Type | Description |
|---|---|---|
cacheControl | String? | Cache control, e.g. max-age=3600 |
contentType | String? | File MIME type, e.g. image/jpeg |
metadata | Map<String, dynamic>? | Custom metadata |
upsert | bool | Whether to overwrite existing file, default true |
StorageUploadResult
Upload result:
| Parameter | Type | Description |
|---|---|---|
id | String? | CloudBase fileID |
path | String? | Upload path |
fullPath | String? | File full path |
StorageUploadInfo
Upload info:
| Parameter | Type | Description |
|---|---|---|
path | String? | File path |
uploadUrl | String? | Upload URL |
token | String? | Upload token |
authorization | String? | Upload authorization |
fileId | String? | File ID |
cosFileId | String? | COS file ID |
code | String? | Error code |
message | String? | Error message |
StorageDownloadInfo
Download info:
| Parameter | Type | Description |
|---|---|---|
fileId | String? | File ID |
downloadUrl | String? | Download URL |
code | String? | Error code (on partial failure) |
message | String? | Error message (on partial failure) |
StorageDeleteResult
Delete result:
| Parameter | Type | Description |
|---|---|---|
fileId | String? | File ID |
code | String? | Error code (on partial failure) |
message | String? | Error message (on partial failure) |
StorageCopyResult
Copy result:
| Parameter | Type | Description |
|---|---|---|
cloudObjectId | String? | Cloud file ID of copied object |
code | String? | Error code (on partial failure) |
message | String? | Error message (on partial failure) |
StorageResponse<T>
Storage response:
| Parameter | Type | Description |
|---|---|---|
data | T? | Response data |
error | StorageError? | Error message |
StorageError
Storage error:
| Parameter | Type | Description |
|---|---|---|
code | String? | Error code |
message | String? | Error message |
requestId | String? | Request ID |
Changelog
1.2.0 (2026-07-24)
- Add NoSQL Database module (
CloudBaseDatabase) with JS-SDK-style chainable APIdb.collection().doc()document references- Chainable query:
where/orderBy/limit/skip/field - CRUD:
add(single & batch),get,count,update,set,remove - Query/update commands via
db.command: comparison (eq/gt/gte/lt/lte/neq/in/nin), logic (and/or/not/nor), update operators (set/inc/mul/remove/push/pull/pop/shift/unshift/addToSet/rename/max/min) - Aggregation pipeline via
collection().aggregate()...end() - Transactions via
db.startTransaction()withcommit/rollback - Geo types (
GeoPoint/GeoLineString/GeoPolygon/GeoMultiPoint/GeoMultiLineString/GeoMultiPolygon) and geo queries RegExp,serverDatehelpers and automatic EJSON encode/decode (e.g.DateTime)- Raw MongoDB commands via
runCommands
1.1.0 (2026-07-01)
- Add Cloud Storage module (
CloudBaseStorage)- Upload files to cloud storage with upload info and direct COS upload
- Get signed download URLs (single and batch)
- Delete files (batch)
- Copy files (single and batch)
- Move/rename files
- Get upload info for client-side direct upload
1.0.9 (2026-06-30)
- Add
X-SDK-Versionheader (@cloudbase/flutter-sdk/<version>) to all HTTP requests for platform identification - Add version management tooling (
tool/update_version.dart) to auto-sync version frompubspec.yaml - Add
CONTRIBUTING.mdwith release workflow documentation - Improve HTTP client to support List request body (for storage APIs)
1.0.8 (2026-05-06)
- Fix
UserProfile.toUser()incorrectly falling back tousername(phone number) whenemailis null, which caused reauthentication to send an invalid email format to the server - Fix
reauthenticate()to properly distinguish between empty string and valid email, ensuring phone-only users use phone number for verification instead of invalid email
1.0.7 (2026-03-11)
- Add
shouldCreateUseroption tosignInWithOtpfor auto-registration when user does not exist - Refactor internal signup logic into reusable
_signUpAndSaveSessionmethod
1.0.6 (2026-03-05)
- Add MySQL module (
CloudBaseMySQL)- Direct SQL query execution
- Transaction support (begin, commit, rollback)
- Database/table management operations
- Add example code for MySQL modules
- Add unit tests for MySQL modules
1.0.5 (2026-03-05)
- Add Data Model module (
CloudBaseDataModel)- CRUD operations with filter, select, orderBy, expand support
- Batch create/update/delete operations
- Upsert support
- Raw MySQL command execution
- DataSource query APIs (aggregate list, detail, schema, table name)
- Refactor HTTP client with token auto-refresh and improved documentation
- Add example code for Data Model
- Add unit tests for Data Model
1.0.4 (2026-01-16)
- Add example code
1.0.3 (2026-01-16)
- Update README documentation
1.0.2 (2026-01-15)
- Fix HTTP client not handling empty token string correctly
1.0.1 (2026-01-15)
- Improve README documentation with complete authentication API usage
1.0.0 (2026-01-15)
- Initial release
- Authentication module (
CloudBaseAuth)- Email/phone registration and sign-in
- Password sign-in
- OTP verification sign-in
- OAuth third-party sign-in
- IdToken sign-in
- Custom ticket sign-in
- Anonymous sign-in
- Session management (get, refresh, set)
- User information management
- Identity provider binding/unbinding
- Password reset
- Cloud Functions module (
CloudBaseFunctions)- Basic cloud function invocation
- Function-based cloud run invocation
- Cloud Run module (
CloudBaseCloudRun)- HTTP methods support (GET/POST/PUT/DELETE)
- Custom request headers
- API Gateway module (
CloudBaseApis)- Chained calls
- Multiple HTTP methods support
- Captcha module (
CloudBaseCaptcha)- Image captcha
- Custom captcha handler
- Built-in captcha dialog