Getting started

Discover ObjectBox: The Lightning-Fast Mobile Database for Persistent Object Storage. Streamline Your Workflow, Eliminate Repetitive Tasks, and Enjoy a User-Friendly Data Interface.

PreviousObjectBox Docs NextTutorial: Demo Project

Last updated 1 day ago

Was this helpful?

Getting started

Discover ObjectBox: The Lightning-Fast Mobile Database for Persistent Object Storage. Streamline Your Workflow, Eliminate Repetitive Tasks, and Enjoy a User-Friendly Data Interface.

Add ObjectBox to your project

Prefer to look at example code? Check out .

ObjectBox tools and dependencies are available on .

To add ObjectBox to your Android project, follow these steps:

Open the Gradle build file of your root project (not the ones for your app or module subprojects) and add a global variable for the version and the ObjectBox Gradle plugin:

/build.gradle(.kts)

buildscript {
    ext.objectboxVersion = "4.3.0" // For Groovy build scripts
    // val objectboxVersion by extra("4.3.0") // For KTS build scripts
    
    repositories {
        mavenCentral()
    }
    
    dependencies {
        // Android Gradle Plugin 8.0 or later supported
        classpath("com.android.tools.build:gradle:8.0.2")
        classpath("io.objectbox:objectbox-gradle-plugin:$objectboxVersion")
    }
}

Open the Gradle build file for your app or module subproject and, after the com.android.application plugin, apply the io.objectbox plugin:

/app/build.gradle(.kts)

// Using plugins syntax:
plugins {
    id("com.android.application")
    id("kotlin-android") // Only for Kotlin projects
    id("kotlin-kapt") // Only for Kotlin projects
    id("io.objectbox") // Apply last
}

// Or using the old apply syntax:
apply plugin: "com.android.application"
apply plugin: "kotlin-android" // Only for Kotlin projects
apply plugin: "kotlin-kapt" // Only for Kotlin projects
apply plugin: "io.objectbox" // Apply last

Then do "Sync Project with Gradle Files" in Android Studio so the Gradle plugin automatically adds the required ObjectBox libraries and code generation tasks.
Your project can now use ObjectBox, continue by defining entity classes.

The ObjectBox Java SDK and runtime libraries support applications:

running on the JVM on Linux (x86_64, arm64, armv7), Windows (x86_64) and macOS 10.15 or newer (x86_64, Apple M1)
written in Java or Kotlin
targeting at least Java 8
built with Gradle or Maven

Maven projects

Gradle projects

Open the Gradle build script of your root project and
1. add a global variable to store the common version of ObjectBox dependencies and

/build.gradle(.kts)

buildscript {
    ext.objectboxVersion = "4.3.0" // For Groovy build scripts
    // val objectboxVersion by extra("4.3.0") // For KTS build scripts
    
    repositories {
        mavenCentral()
    }
    
    dependencies {
        classpath("io.objectbox:objectbox-gradle-plugin:$objectboxVersion")
    }
}

Open the Gradle build file for your application subproject and, after other plugins, apply the io.objectbox plugin:

/app/build.gradle(.kts)

// Using plugins syntax:
plugins {
    id("java-library") // or org.jetbrains.kotlin.jvm for Kotlin projects.
    id("io.objectbox") // Apply last.
}

// Or using the old apply syntax:
apply plugin: "java-library" // or org.jetbrains.kotlin.jvm for Kotlin projects.
apply plugin: "io.objectbox" // Apply last.

Using your IDE of choice with a Gradle project might require additional configuration. E.g.

Optionally, add a runtime library for each platform that your application should run on and instead apply the Gradle plugin after the dependencies block:

dependencies {
    // ObjectBox platform-specific runtime libraries
    // Add or remove them as needed to match what your application supports
    // Linux (x64)
    implementation("io.objectbox:objectbox-linux:$objectboxVersion")
    // macOS (Intel and Apple Silicon)
    implementation("io.objectbox:objectbox-macos:$objectboxVersion")
    // Windows (x64)
    implementation("io.objectbox:objectbox-windows:$objectboxVersion")

    // Additional ObjectBox runtime libraries
    // Linux (32-bit ARM)
    implementation("io.objectbox:objectbox-linux-arm64:$objectboxVersion")       
    // Linux (64-bit ARM)
    implementation("io.objectbox:objectbox-linux-armv7:$objectboxVersion")
}

// When manually adding ObjectBox dependencies, the plugin must be
// applied after the dependencies block so it can detect them.
// Using Groovy build scripts
apply plugin: "io.objectbox"
// Using KTS build scripts
apply(plugin = "io.objectbox")

The ObjectBox database runs mostly in native code written in C/C++ for optimal performance. Thus, ObjectBox will load a runtime library: a “.dll” on Windows, a “.so” on Linux, and a “.dylib” on macOS.\

By default, the Gradle plugin adds a runtime library (only) for your current operating system. It also adds the Java SDK (objectbox-java) and if needed the ObjectBox Kotlin extension functions (objectbox-kotlin).

ObjectBox only supports 64-bit systems for best performance going forward. Talk to us if you require 32-bit support.

Your project can now use ObjectBox, continue by defining entity classes.

You can watch these video tutorials as well 😀:

To add ObjectBox to your Flutter project:

Run these commands:

flutter pub add objectbox objectbox_flutter_libs:any
flutter pub add --dev build_runner objectbox_generator:any

flutter pub add objectbox objectbox_sync_flutter_libs:any
flutter pub add --dev build_runner objectbox_generator:any

To run unit tests on your machine, download the latest native ObjectBox library for your machine by running this script in a bash shell (e.g. Git Bash on Windows):

bash <(curl -s https://raw.githubusercontent.com/objectbox/objectbox-dart/main/install.sh)

To get a variant of the library that supports ObjectBox Sync, append the --sync argument to above command.

This should add lines like this to your pubspec.yaml:

dependencies:
  objectbox: ^4.3.0
  objectbox_flutter_libs: any
  # If you run the command for ObjectBox Sync it should add instead:
  # objectbox_sync_flutter_libs: any

dev_dependencies:
  build_runner: ^2.4.11
  objectbox_generator: any

If you added the above lines manually, then install the packages with flutter pub get.

For Android increase the NDK version:

/android/app/build.gradle

android {
    // ObjectBox: Flutter defaults to NDK 23.1.7779620, but
    // - objectbox_flutter_libs requires Android NDK 25.1.8937393
    // - path_provider_android requires Android NDK 25.1.8937393
    // Until Flutter uses a newer version (https://github.com/flutter/flutter/commit/919bed6e0a18bd5b76fb581ede10121f8c14a6f7)
    // manually set the required one:
    // ndkVersion flutter.ndkVersion
    ndkVersion = "25.1.8937393"
}

For all macOS apps need to target macOS 10.15: in Podfile change the platform and in the Runner.xcodeproj/poject.pbxproj file update MACOSX_DEPLOYMENT_TARGET.

Run these commands:

dart pub add objectbox
dart pub add --dev build_runner objectbox_generator:any

This should add lines like this to your pubspec.yaml:

dependencies:
  objectbox: ^4.3.0

dev_dependencies:
  build_runner: ^2.4.11
  objectbox_generator: any

If you added the above lines manually, then install the packages with dart pub get

bash <(curl -s https://raw.githubusercontent.com/objectbox/objectbox-dart/main/install.sh)

bash <(curl -s https://raw.githubusercontent.com/objectbox/objectbox-dart/main/install.sh) --sync

By default the library is downloaded into the lib subdirectory of the working directory. It's not necessary to install the library system-wide. This also allows to use different versions for different projects. For details see below.

Deploying Dart Native projects

The install.sh script downloads the library by default to the lib subdirectory of the working directory. An executable using ObjectBox Dart looks for the library in this lib directory.

If it is not found there, it falls back to using system directories (using Dart's DynamicLibrary.open):

Windows: working directory and %WINDIR%\system32.
macOS: /usr/local/lib (and maybe others).
Linux: /lib and /usr/lib (again, possibly others).

ObjectBox for Python is available via PyPI: Stable Version (4.0.0):

pip install --upgrade objectbox

Define Entity Classes

Define your data model by creating a class with at least an ID property, a so called entity.

A simple entity representing a user with an ID and a name property could look like this:

User.java

@Entity
public class User {
    @Id 
    public long id;
    public String name;
}

models.kt

@Entity
data class User(
        @Id 
        var id: Long = 0,
        var name: String? = null
)

When using a data class, add default values for all parameters. This will ensure your data class will have a constructor that can be called by ObjectBox. (Technically this is only required if adding properties to the class body, like custom or transient properties or relations, but it's a good idea to do it always.)

Avoid naming properties like reserved Java keywords, like private and default. ObjectBox tooling works with the Java representation of your Kotlin code to be compatible with both Java and Kotlin. It will ignore such properties.

models.dart

@Entity()
class User {
  @Id()
  int id = 0;
  
  String? name;
}

You can have multiple entities in the same file (here models.dart), or you can have them spread across multiple files in your package's lib directory.

model.py

from objectbox import Entity, Id, String

@Entity()
class User:
  id = Id
  name = String

Important:

Entities must also have a no-argument constructor, or for better performance, a constructor with all properties as arguments. In the above examples, a default, no-argument constructor is generated by the compiler.

For more details about entities, like how to create an index or a relation, check the Entity Annotations page.

ObjectBox also supports changing your model at a later point. You can add and remove properties in entities and the database model is updated automatically (after re-generating some code, see section below). There is no need to write migration code.

To rename entities or properties, change the type of a property and more details in general see Data Model Updates.

Generate ObjectBox code

Next, we generate some binding code based on the model defined in the previous step.

Build your project to generate the MyObjectBox class and other classes required to use ObjectBox, for example using Build > Make Project in Android Studio.

Note: If you make significant changes to your entities, e.g. by moving them or modifying annotations, make sure to rebuild the project so generated ObjectBox code is updated.

To change the package of the MyObjectBox class, see the annotation processor options on the Advanced Setup page.

To generate the binding code required to use ObjectBox run

dart run build_runner build

ObjectBox generator will look for all @Entity annotations in your lib folder and create

a single database definition lib/objectbox-model.json and
supporting code in lib/objectbox.g.dart.

To customize the directory where generated files are written see Advanced Setup.

If you make changes to your entities, e.g. by adding a property or modifying annotations, or after the ObjectBox library has updated make sure to re-run the generator so generated ObjectBox code is updated.

You typically commit the generated code file objectbox.g.dart to your version control system (e.g. git) to avoid having to re-run the generator unless there are changes.

Actually we lied above. The generator will process lib and test folders separately and generate files for each one (if @Entity classes exist there). This allows to create a separate test database that does not share any of the entity classes with the main database.

Among other files ObjectBox generates a JSON model file, by default to

app/objectbox-models/default.json for Android projects,
lib/objectbox-model.json for Dart/Flutter projects, or
<user-module-dir>/objectbox-model.json for Python projects

To change the model file path, see Advanced Setup.

In Android Studio you might have to switch the Project view from Android to Project to see the default.json model file. Python checks for the call-stack to determine the user-module directory in which the JSON file is stored.

This JSON file changes when you change your entity classes (or sometimes with a new version of ObjectBox).

Keep this JSON file, commit the changes to version control!

This file keeps track of unique IDs assigned to your entities and properties. This ensures that an older version of your database can be smoothly upgraded if your entities or properties change.

Create a Store

Create it using the builder returned by the generated MyObjectBox class, for example in a small helper class like this:

public class ObjectBox {
    private static BoxStore store;

    public static void init(Context context) {
        store = MyObjectBox.builder()
                .androidContext(context)
                .build();
    }

    public static BoxStore get() { return store; }
}

public class ExampleApp extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        ObjectBox.init(this);
    }
}

Create it using the builder returned by the generated MyObjectBox class, for example in a small helper class like this:

object ObjectBox {
    lateinit var store: BoxStore
        private set

    fun init(context: Context) {
        store = MyObjectBox.builder()
                .androidContext(context)
                .build()
    }
}

class ExampleApp : Application() {
    override fun onCreate() {
        super.onCreate()
        ObjectBox.init(this)
    }
}

public class ObjectBox {
    private static BoxStore store;

    public static void init(Context context) {
        store = MyObjectBox.builder()
                .name("objectbox-notes-db")
                .build();
    }

    public static BoxStore get() { return store; }
}

The best time to initialize ObjectBox is when your app starts. For a command line app this is typically inside the main method.

Create it using the generated openStore() method, for example in a small helper class like this:

import 'package:path/path.dart' as p;
import 'package:path_provider/path_provider.dart';
import 'objectbox.g.dart'; // created by `flutter pub run build_runner build`

class ObjectBox {
  /// The Store of this app.
  late final Store store;
  
  ObjectBox._create(this.store) {
    // Add any additional setup code, e.g. build queries.
  }

  /// Create an instance of ObjectBox to use throughout the app.
  static Future<ObjectBox> create() async {
    final docsDir = await getApplicationDocumentsDirectory();
    // Future<Store> openStore() {...} is defined in the generated objectbox.g.dart
    final store = await openStore(directory: p.join(docsDir.path, "obx-example"));
    return ObjectBox._create(store);
  }
}

For example:

openStore(macosApplicationGroup: "FGDTDLOBXDJ.demo")

On desktop systems it is recommended to specify a directory to create a custom sub-directory to avoid conflicts with other apps.

If your code passes a directory that the application can't write to, you get an error that looks somewhat like this: failed to create store: 10199 Dir does not exist: objectbox (30).

The best time to initialize ObjectBox is when your app starts. We suggest to do it in your app's main() function:

/// Provides access to the ObjectBox Store throughout the app.
late ObjectBox objectbox;

Future<void> main() async {
  // This is required so ObjectBox can get the application directory
  // to store the database in.
  WidgetsFlutterBinding.ensureInitialized();

  objectbox = await ObjectBox.create();

  runApp(MyApp());
}

Create it using the generated openStore() method, for example like this:

import 'objectbox.g.dart'; // created by `dart pub run build_runner build`

void main() {
  // Store openStore() {...} is defined in the generated objectbox.g.dart
  final store = openStore();

  // your app code ...

  store.close(); // don't forget to close the store
}

The above minimal example omits the argument to (directory: ), using the default - ./objectbox - in the current working directory.

from objectbox import Store
  
store = Store()

It is possible to specify various options when building a store. Notably for testing or caching, to use an in-memory database that does not create any files:

BoxStore inMemoryStore = MyObjectBox.builder()
        .androidContext(context)
        .inMemory("test-db")
        .build();

 final inMemoryStore =
     Store(getObjectBoxModel(), directory: "memory:test-db");

store = Store(directory="memory:testdata")

Basic Box operations

Box<User> userBox = store.boxFor(User.class);
Box<Order> orderBox = store.boxFor(Order.class);

val userBox = store.boxFor(User::class)
val orderBox = store.boxFor(Order::class)

final userBox = store.box<User>();
final orderBox = store.box<Order>();

user_box = store.box(User)
order_box = store.box(Order)

These are some of the operations offered by the Box class:

put inserts a new object or updates an existing one (with the same ID). When inserting, an ID will be assigned to the just inserted object (this will be explained below) and returned. put also supports putting multiple objects, which is more efficient.

User user = new User("Tina");
userBox.put(user);

List<User> users = getNewUsers();
userBox.put(users);

val user = User(name = "Tina")
userBox.put(user)

val users: List<User> = getNewUsers()
userBox.put(users)

final user = User(name: 'Tina');
userBox.put(user);

final users = getNewUsers();
userBox.putMany(users);

user = User(name="Tina")
user_box.put(user)

users = get_new_users()
user_box.put(*users)

get and getAll: Given an object’s ID, get reads it from its box. To get all objects in the box use getAll .

User user = userBox.get(userId);

List<User> users = userBox.getAll();

val user = userBox[userId]

val users = userBox.all

final user = userBox.get(userId);

final users = userBox.getMany(userIds);

final users = userBox.getAll();

user = user_box.get(user_id)

users = user_box.get_all()

Query<User> query = userBox
    .query(User_.name.equal("Tom"))
    .order(User_.name)
    .build();
List<User> results = query.find();
query.close();

val query = userBox
    .query(User_.name.equal("Tom"))
    .order(User_.name)
    .build()
val results = query.find()
query.close()

final query =
    (userBox.query(User_.name.equals('Tom'))..order(User_.name)).build();
final results = query.find();
query.close();

query = user_box \
    .query(User.name.equals('Tom')) \
    .build()
results = query.find()

remove and removeAll: Remove a previously put object from its box (deletes it). remove also supports removing multiple objects, which is more efficient. removeAll removes (deletes) all objects in a box.

boolean isRemoved = userBox.remove(userId);

userBox.remove(users);
// alternatively:
userBox.removeByIds(userIds);

userBox.removeAll();

val isRemoved = userBox.remove(userId)

userBox.remove(users)
// alternatively:
userBox.removeByIds(userIds)

userBox.removeAll()

final isRemoved = userBox.remove(userId);

userBox.removeMany(userIds);

userBox.removeAll();

is_removed = user_box.remove(user_id)

user_box.remove_all()

count: Returns the number of objects stored in this box.

long userCount = userBox.count();

val userCount = userBox.count()

final userCount = userBox.count();

user_box.count()

Asynchronous operations

ObjectBox has built-in support to run (typically multiple or larger) database operations asynchronously.

runInTxAsync and callInTxAsync: runs the given Runnable/Callable in a transaction on a background thread (the internal ObjectBox thread pool) and calls the given callback once done. In case of callInTxAsync the callback also receives the returned result.

store.callInTxAsync(() -> {
    Box<User> box = store.boxFor(User.class);
    String name = box.get(userId).name;
    box.remove(userId);
    return text;
}, (result, error) -> {
    if (error != null) {
        System.out.println("Failed to remove user with id " + userId);
    } else {
        System.out.println("Removed user with name: " + result);
    }
});

awaitCallInTx (Kotlin Coroutines only): wraps callInTxAsync in a coroutine that suspends until the transaction has completed. Likewise, on success the return value of the given callable is returned, on failure an exception is thrown.

try {
    val name = store.awaitCallInTx {
        val box = store.boxFor(User::class.java)
        val name = box.get(userId).name
        box.remove(userId)
        name
    }
    println("Removed user with name $name")
} catch (e: Exception) {
    println("Failed to remove user with id $userId")
}

Most Box methods do have async versions which run the operation in a worker isolate.

For example putAsync: asynchronously inserts a new object or updates an existing one (with the same ID). The returned future completes when the object is successfully written to the database.

final user = User(name: 'Tina');
Future<int> idFuture = userBox.putAsync(user);

...

final id = await idFuture;
userBox.get(id); // after the future completed, the object is inserted

// The callback must be a function that can be sent to an isolate: 
// either a top-level function, static method or a closure that only
// captures objects that can be sent to an isolate.
String? readNameAndRemove(Store store, int objectId) {
  var box = store.box<User>();
  final nameOrNull = box.get(objectId)?.name;
  box.remove(objectId);
  return nameOrNull;
}
final nameOrNull = 
  await store.runInTransactionAsync(TxMode.write, readNameAndRemove, objectId);

If it is necessary to call put many times in a row, take a look at putQueued: Schedules the given object to be put later on, by an asynchronous queue, returns the id immediately even though the object may not have been written yet. You can use Store's awaitQueueCompletion() or awaitQueueSubmitted() to wait for the async queue to finish.

for (int i = 0; i < 100; i++) {
  userBox.putQueued(User(name: 'User $i'));
}

// Optional: wait until submitted items are processed.
store.awaitQueueSubmitted();
expect(userBox.count(), equals(100));

Object IDs

By default IDs for new objects are assigned by ObjectBox. When a new object is put, it will be assigned the next highest available ID:

User user = new User();
// user.id == 0
box.put(user);
// user.id != 0
long id = user.id;

val user = User()
// user.id == 0
box.put(user)
// user.id != 0
val id = user.id

final user = User();
// user.id == 0
box.put(user);
// user.id != 0
final id = user.id;

user = User()
box.put(user)
id: int = user.id

For example, if there is an object with ID 1 and another with ID 100 in a box, the next new object that is put will be assigned ID 101.

If you try to assign a new ID yourself and put the object, ObjectBox will throw an error.

Reserved Object IDs

Object IDs can not be:

0 (zero) or null (if using java.lang.Long) As said above, when putting an object with ID zero it will be assigned an unused ID (not zero).
0xFFFFFFFFFFFFFFFF (-1 in Java) Reserved for internal use.

Transactions

While ObjectBox offers powerful transactions, it is sufficient for many apps to consider just some basics guidelines about transactions:

A put runs an implicit transaction.
Prefer put bulk overloads for lists (like put(entities)) when possible.
For a high number of DB interactions in loops, consider explicit transactions, such as using runInTx().

Have an app with greenDAO? DaoCompat is for you!

Next steps

To enable debug mode and for advanced use cases, see the Advanced Setup page.

PreviousObjectBox Docs NextTutorial: Demo Project

Last updated 1 day ago

Was this helpful?