DOCSEARCHbyAlgolia
Submit Docs

ObjectBox Dart & Flutter

repository·main·Indexed 22 days ago

https://github.com/objectbox/objectbox-dart

A high-performance, ACID-compliant NoSQL database for Flutter and Dart, featuring built-in support for on-device vector search for AI applications. The SDK includes the core objectbox runtime and the objectbox_generator for boilerplate code generation. It supports entity relations, reactive data streams, and provides specialized libraries like objectbox_flutter_libs for Flutter platform integration.

Tokens
6.3K
Snippets
14
Records
36
Agent score
79%

What's inside objectbox-dart

  1. Core features of ObjectBox for Flutter and Dart

    main

    ObjectBox is a high-performance NoSQL database designed for mobile and IoT devices. Key features include:

    • Vector Support: On-device vector database for AI applications.
    • Performance: High response rates for real-time applications.
    • ACID Compliance: Ensures data integrity (Atomic, Consistent, Isolated, Durable).
    • Multiplatform: Supports Android, iOS, macOS, Linux, Windows, and any POSIX-system.
    • Built-in Relations: Native support for object links and relationships.
    • Statically Typed: Compile-time checks and optimizations.
    • Schema Migration: Tools to evolve your data model safely.
    • Data Sync: Capability to synchronize data between devices and servers (online or offline).

  2. Understand the integration test execution lifecycle

    main

    Each subdirectory in generator/integration-tests represents a complete Dart package and a single test case. The execution follows this lifecycle:

    1. Cleanup: Before a test starts, the directory is cleaned using git clean -fXd <directory-path> to remove ignored files.
    2. Pre-generation Setup: If [0-9]-pre.dart files exist, they are executed via dart N-pre.dart to prepare the environment before code generation.
    3. Code Generation: pub run build_runner build is executed before each test file (except 0.dart).
    4. Test Execution: Test files named [0-9].dart are executed in ascending order using pub run test N.dart.

    Note on Persistence: Tests are permitted to modify the file system within their own directory. These changes are preserved between individual test files within a test case, but are not removed between different test-case runs.

  4. How ObjectBox entity merging and ID/UID generation works

    main

    The code generation process involves a merging step to maintain consistency with your existing database schema:

    1. Entity Discovery: The generator finds all classes annotated with @Entity.
    2. Merging: Found entities are compared against the existing model definition stored in objectbox-model.json.
    3. ID/UID Assignment:
      • IDs: Assigned in ascending order for new instances.
      • UIDs: Generated randomly for new instances.

    Important Note on UIDs: UIDs are never reused. If a property, entity, or index is removed, its UID is stored in the objectbox-model.json file to prevent future collisions. This ensures that the mapping between your Dart code and the underlying database remains stable.

  5. Checklist for adding a new property type to ObjectBox Dart

    main

    To add support for a new ObjectBox property type, follow this sequence of updates across the C bindings, Dart core, and the code generator:

    1. C Bindings: Copy the new enum from objectbox_c.dart to OBXPropertyType. If necessary, re-generate Dart bindings first.
    2. Dart Core: Add the new type to the PropertyType enum.
    3. Integration Tests: Add the new type to generator/integration-tests/basics (update both the lib and the associated file).
    4. Mappings: Update the following mappings to include the new OBXPropertyType:
      • propertyTypeToOBXPropertyType
      • obxPropertyTypeToString
    5. Entity Resolution: Update the detection logic in generator/lib/src/entity_resolver.dart.
    6. Code Generation: Update the code generator in generator/lib/src/code_chunks.dart.
      • Note: You may need to add a new FlatBuffers reader in objectbox/lib/src/native/bindings/flatbuffers_readers.dart.
    7. Testing: Add necessary put/get and query tests to objectbox_test.

  6. Generate Dart C API bindings

    main

    To download C library header files and generate new bindings using ffigen (requires LLVM), run the following script:

    ./tool/update-c-binding.sh

    After running the script, you must perform these manual steps:

    1. Sync Enums: Copy/update any enums that need to be exposed to users from objectbox/lib/src/native/bindings/objectbox_c.dart to objectbox/lib/src/modelinfo/enums.dart.
    2. Verify Signatures: Check changed files and update the Dart library if method signatures have changed.
    3. Update Metadata: ⚠️ You must update the minimum C API and core version and the associated notes in objectbox/lib/src/native/bindings/bindings.dart.
    4. Commit: Use a descriptive commit message following the pattern Update C API [old_version -> new_version].

  7. Update C libraries for Desktop, Android, and Apple OSs

    main

    To ensure the Dart C bindings match the included C libraries and avoid memory bugs, you must update the platform-specific C library versions using the provided scripts. Each platform uses a different mechanism:

    Desktop, Scripts (Linux/Windows)

    Uses GitHub release artifacts of ObjectBox C. Use the set-c-version.sh script.

    Android

    Uses Maven artifacts of objectbox-android and objectbox-android-objectbrowser. Use the set-android-version.sh script. If using Admin, ensure you update io.objectbox:objectbox-android-objectbrowser in your android/app/build.gradle.kts or android/app/build.gradle.

    Apple OSs (iOS/macOS)

    Uses the ObjectBox CocoaPod. Use the set-swift-version.sh script. For existing projects, you may need to run pod repo update and pod update ObjectBox in the ios or macos directories.

    # Desktop/Scripts
./tool/set-c-version.sh 5.3.2

# Android
./tool/set-android-version.sh 5.4.2

# Apple OSs
./tool/set-swift-version.sh 5.3.0

  8. Run generator integration tests

    main

    Integration tests for the generator are located in the generator/integration-tests directory. You can execute them using the ../test.sh script located in the parent directory.

    To run the entire suite, execute the script without arguments. To run tests for a specific test case, provide the directory path as an argument.

    # Run all tests
../test.sh

# Run a specific test
../test.sh <directory>

  9. Run ObjectBox tests with improved logging

    main

    For better log output, such as attributing native logs to specific tests, run the tests with concurrency disabled and use the expanded reporter. This is recommended when running only one test suite (one test file) at a time.

    dart test --concurrency=1 --reporter expanded

  11. Run the Event Management Flutter Tutorial

    main

    The Event Management tutorial project is divided into two parts located in the event_manager and many_to_many directories.

    • event_manager: Covers modeling and working with one-to-one and one-to-many relationships.
    • many_to_many: An extension of the application demonstrating many-to-many relationships.

    To run either application, follow these steps:

    1. Navigate to the desired directory.
    2. Install Flutter dependencies.
    3. Run the build_runner to generate the necessary ObjectBox binding code.
    4. Launch the application on an emulator or device.

  12. Customize iOS Launch Screen Assets

    main

    To customize the launch screen for your iOS application, you can either replace the image files directly in the ios/Runner/Assets.xcassets/LaunchImage.imageset/ directory or use Xcode for a visual approach.

    Using Xcode:

    1. Open your Flutter project's iOS workspace using open ios/Runner.xcworkspace.
    2. In the Xcode Project Navigator, select Runner/Assets.xcassets.
    3. Drag and drop your desired images into the asset catalog.
    open ios/Runner.xcworkspace