Dart on Linux + Precompiled C++: Building a Native MongoDB Driver

Capoerus — Sun, 11 Oct 2026 17:07:13 +0000

Creating an API in Dart is relatively easy. The challenge begins when the API needs to run reliably in production and depends on secure, well-maintained components for database access, file management, request processing, and cross-platform data handling.

While developing Capoerus, I found that ready-made components did not always meet the requirements of my architecture. In some cases, I decided to build my own packages and technologies.

One of the most interesting engineering decisions was combining Dart compiled for Linux with a precompiled C++ MongoDB access driver.

This approach provides greater control over implementation, shared data representations, and reduced dependence on third-party packages. However, it also introduces challenges involving native memory management, error handling, and communication between programming languages.

This article explores how this combination works, why I chose it, and what I learned from the trade-offs.

1. The Challenge Goes Beyond Creating an API

Dart provides a productive environment for building APIs. However, a production system requires more than routing, request handlers, and asynchronous functions.

During the development of Capoerus, I needed several components:

A universal JSON encoding and decoding package shared by the frontend, backend, and native database driver.
A MongoDB access driver integrated with Dart.
Cloud file management for Oracle Cloud Infrastructure Object Storage.
A lightweight local database that stores data in JSON format on mobile and desktop devices, without requiring code generation.
A multipart request handler shared between the application and the API.

These components support an architecture in which mobile applications, web applications, and server-side code share a significant portion of their implementation.

Developing them independently required considerable effort. However, it also allowed me to establish consistent interfaces and behaviors across the entire ecosystem.

The MongoDB driver is a particularly interesting example because it crosses the boundary between Dart-managed code and native C++ execution.

2. Why Use C++ for the MongoDB Driver?

The API runs on Linux, compiled from Dart, while the MongoDB driver is implemented in C++ and compiled into a native library before deployment.

Dart communicates with native functions through FFI (Foreign Function Interface).

Instead of implementing every database operation entirely in Dart, the driver exposes native functions that can be called through their symbols.

For example, the Dart side declares an operation like this:

const String findOneSymbol = 'findOne';

@Native<Method>(
  assetId: assetId,
  symbol: findOneSymbol,
  isLeaf: isLeaf,
)
external Pointer<Utf8> findOne(Pointer<Utf8> request);

The findOne function represents a native entry point. Dart passes a pointer to the request, and the native function returns a pointer containing the response.

Each database operation has its own symbol, allowing operations to be exposed independently.

This gives the Dart layer a relatively small interface to work with while the native library handles the database-specific implementation.

It also means that the native library must respect a strict contract regarding memory, data representation, and return values.

That contract is where the most important engineering decisions begin.

3. A Bidirectional Buffer Shared by Dart and C++

The driver uses a buffer allocated on the Dart side for both the request and the response.

The process works as follows:

Dart serializes the request into JSON.
Dart encodes the JSON string into UTF-8 bytes.
Dart allocates a native memory buffer large enough for the request and the expected response.
The request bytes are copied into that buffer, followed by a null terminator.
Dart calls the native C++ function, passing the buffer pointer.
C++ processes the request and writes the response into the same buffer.
The native function returns the pointer to that buffer.
Dart reads the response, decodes the JSON, and releases the allocated memory.

Conceptually, the data flow looks like this:

Dart API
   |
   | Serialize request to JSON
   | Encode as UTF-8
   | Allocate response-capable buffer
   v
+------------------------------+
| Dart-allocated native buffer |
|                              |
| JSON request                 |
+------------------------------+
   |
   | FFI call
   v
+------------------------------+
| Precompiled C++ driver       |
|                              |
| Process request              |
| Execute MongoDB operation    |
| Write response into buffer   |
+------------------------------+
   |
   | Return the same pointer
   v
Dart API
   |
   | Read UTF-8 response
   | Decode JSON
   | Release allocation
   v
Application response

The key idea is that the native function does not need to allocate a separate response buffer and transfer ownership of that allocation to Dart.

Instead, Dart owns the allocation, and C++ writes the response into the memory provided by Dart.

This design reduces the complexity of memory ownership between the two layers. However, it does not automatically provide memory safety. The native implementation must respect the buffer's capacity and the agreed pointer contract.

4. Allocating Enough Memory Is the Difficult Part

The buffer must be large enough to contain the response, not merely the original request.

A small MongoDB query can return a large document. A query that returns multiple documents can produce a response considerably larger than its input.

If C++ writes beyond the allocated capacity, it can corrupt memory and crash the process.

For a server-side API, this is especially important because a native crash can terminate the entire process rather than just fail a single request.

The Dart implementation therefore accepts a response size limit and checks it against the encoded request size before allocating memory.

A simplified version of the validation is:

final Uint8List requestBytes = utf8.encode(request.toJson);

final int requestBytesLength = requestBytes.length;
final int responseSizeLimit = request.responseSizeLimit;

if (responseSizeLimit < requestBytesLength) {
  throw const MongodbException(
    'The response size limit cannot be smaller '
    'than the request size.',
  );
}

The actual implementation also reserves one additional byte for the null terminator.

This initial validation prevents an obviously undersized buffer from being passed to C++. However, it does not guarantee that the response will fit.

The native side must enforce the capacity before every write, and the driver must define what happens when a response exceeds the configured limit.

A robust implementation should reject oversized responses or return a controlled error rather than attempting to write beyond the buffer.

Why the Null Terminator Matters

The native function receives a pointer to UTF-8 data represented as a null-terminated string.

The allocation therefore includes an additional byte:

final Pointer<Uint8> allocatedPointer =
    malloc<Uint8>(responseSizeLimit + 1);

The request is then copied into the allocated memory:

final Uint8List nativeBytes =
    allocatedPointer.asTypedList(requestBytesLength + 1);

nativeBytes.setAll(0, requestBytes);
nativeBytes[requestBytesLength] = 0;

The zero byte marks the end of the C-style string.

When C++ writes the response, it must preserve that convention and ensure that the response and its terminator fit within the available memory.

The response must also be valid UTF-8 JSON before Dart attempts to decode it.

5. Keeping the Pointer Contract Explicit

Another important check verifies that the native function returns the same pointer that Dart originally allocated.

final int allocatedPointerAddress =
    allocatedPointer.address;

final Pointer<Utf8> requestPointer =
    allocatedPointer.cast<Utf8>();

final Pointer<Utf8> responsePointer =
    request.method(requestPointer);

if (allocatedPointerAddress != responsePointer.address) {
  throw const MongodbException(
    'The native function returned an unexpected pointer.',
  );
}

This is a simplified illustration of the pointer validation used by the driver.

The native functions are expected to write the response into the original allocation and return that same address.

This makes the ownership contract explicit: the native function must not return an independently allocated response buffer under the same interface.

One limitation is worth noting: checking the address after the native function returns cannot prevent an invalid write that has already occurred. Pointer validation is a contract check, not a substitute for bounds checking inside C++.

The native implementation must enforce the buffer capacity before writing any response bytes.

6. Dart Manages the Allocation, but the Trade-Off Remains

One benefit of this design is that Dart controls the buffer's allocation and release.

C++ does not need to transfer ownership of a separately allocated response buffer to the Dart layer. This avoids one class of cross-language ownership problems.

The Dart implementation can read the response and then release the allocation:

final String content = responsePointer.toDartString();

final Json json = Json.treaty(content);

malloc.free(requestPointer);

return json;

The example illustrates the intended lifecycle, but production code must handle cleanup on every execution path.

For example, if decoding throws an exception before malloc.free executes, the allocation could leak. A safer implementation places the native allocation in a try/finally lifecycle so that the buffer is released even when an operation fails.

The central trade-off remains:

Dart controls allocation and release.
C++ must respect the memory boundaries established by Dart.
A native buffer overflow can still crash the API.
Incorrect pointer handling can still cause undefined behavior.

This is one of the areas where native integration requires more care than an ordinary Dart function call.

7. Exceptions and Controlled Failures

A database driver should not assume that every operation succeeds.

MongoDB operations can fail, JSON responses can be invalid, and unexpected conditions can occur at the native boundary.

The driver therefore catches its own database-related exceptions and unexpected Dart-side exceptions, records diagnostic information, and can return an alternative JSON response.

The public interface includes an optional ifFail callback:

Future<Json> request(
  final Request request, {
  Json Function()? ifFail,
}) async {
  // Request processing and native invocation.
}

The callback allows the caller to supply alternative data when a request fails.

The general fallback behavior is:

return json ?? ifFail?.call() ?? Json.emptyMap();

This gives the calling code a way to handle failures without necessarily propagating every exception through the entire request-handling stack.

However, exception handling has an important boundary.

Catching Dart exceptions does not reliably recover from arbitrary native crashes, segmentation faults, or memory corruption. Those failures may terminate the process before Dart can execute its catch block.

For this reason, exception handling must complement, rather than replace, native validation and memory safety.

In addition, a fallback value should not make a failed database operation indistinguishable from a successful one. The application must preserve enough information to determine whether the requested operation actually succeeded.

8. Why Precompiled Native Code Requires a Security Strategy

Using a native library also changes the security considerations.

A precompiled library does not expose its implementation as readable source code in the deployed artifact. That can make its behavior harder to inspect during routine debugging, especially when debugging symbols and build artifacts are unavailable.

But compiled code is not inherently trustworthy, nor is it impossible to analyze.

A native library can contain vulnerabilities or perform unintended operations regardless of whether its source code is visible.

For a component that has access to a database and runs inside an API process, I consider control over the implementation an important advantage.

Developing the driver internally gives me control over its source code, its build process, its exposed functions, and the changes introduced between versions.

It also allows the interface between Dart and C++ to remain narrow and explicit.

Still, these benefits should not be confused with an automatic security guarantee.

A custom driver needs code review, dependency management, controlled builds, tests, and careful validation of native inputs. The same applies to permissions and access credentials: the native library should only receive the capabilities it actually needs.

Owning the implementation improves control; security still depends on how that implementation is built, reviewed, and operated.

9. One JSON Language Across the Ecosystem

The native MongoDB driver is only one part of the architecture.

Another important component is the JSON encoding and decoding package developed for Capoerus.

The same representation is used across the mobile application, backend, and native driver.

This reduces the number of translation layers required between components.

Instead of maintaining different data representations for each platform, the system uses a shared JSON contract.

The result is a more consistent flow of data:

Mobile application
       |
       | JSON
       v
Dart application and API
       |
       | JSON encoded as UTF-8
       v
Native C++ MongoDB driver
       |
       | JSON response
       v
Dart API and application

JSON does not eliminate the need for validation or versioning. A shared format still requires consistent handling of missing fields, data types, invalid responses, and schema changes.

Its value is that the components share a common representation and can evolve around the same conventions.

10. The Benefits Extend Beyond MongoDB

Developing the native driver makes more sense when considered alongside the other components created for the ecosystem.

Capoerus also uses its own solutions for local JSON-based storage, cloud file management with Oracle Cloud Infrastructure Object Storage, JSON serialization, and multipart request handling.

These components address different problems, but they follow a common architectural principle: establish interfaces that work consistently across the applications and services that need them.

This approach has practical advantages:

Consistency: mobile, web, and server components share common conventions.
Autonomy: implementation decisions are not entirely dependent on external package maintainers.
Adaptability: changes can be coordinated across the ecosystem.
Reduced dependency surface: fewer third-party components are required for the functionality implemented internally.
Control over updates: internal components can evolve according to the project's needs.

None of these advantages means that building everything in-house is automatically better.

Maintaining custom infrastructure creates responsibilities that would otherwise belong to package maintainers. Security updates, compatibility, testing, documentation, and debugging become part of the project's own workload.

The benefits must justify that ongoing cost.

11. The Cost of Building Your Own Technology

There is a downside to this approach that is easy to underestimate.

Creating a package is only the beginning.

It must be tested, documented, maintained, and adapted as the application evolves. Native code adds another layer of complexity because failures can occur outside Dart's managed execution environment.

A third-party package with a mature implementation may be a better choice for many projects.

For Capoerus, however, developing these components has provided a high degree of autonomy and a consistent technical foundation across the ecosystem.

The decision was not simply to avoid dependencies. It was to build components whose behavior and interfaces could be coordinated with the rest of the architecture.

That distinction matters.

Reducing dependencies is useful only when the cost of owning the replacement remains manageable.

Conclusion

Combining Dart compiled for Linux with a precompiled C++ MongoDB driver has allowed Capoerus to establish a direct interface between its API and native database operations.

The design uses a Dart-allocated buffer for both request and response data, making memory ownership easier to define. It also creates strict requirements for buffer capacity, pointer identity, null termination, exception handling, and cleanup.

The larger benefit comes from how this component fits into the rest of the system.

A shared JSON representation, custom local storage, cloud file management, and reusable request-processing components help keep mobile applications, web applications, and server-side code aligned.

The price is substantial engineering and maintenance work. The reward is greater control over implementation, fewer unnecessary translation layers, and the freedom to adapt components to the needs of the project.

For me, the most important lesson is not that native C++ is always the right choice for a Dart backend.

It is that the boundary between two languages can become a useful architectural tool when its ownership rules, data contract, and failure modes are designed explicitly.

That boundary is also where the most careful engineering is required.

Contato • Website • Links • Play Store

DEV Community: Capoerus