Data and clients

Dart SDK

Use the PocketBase Dart SDK to authenticate users and work with records from web, mobile, desktop, or CLI applications.

The official Dart SDK provides an idiomatic client for PocketBase applications targeting web, mobile, desktop, or CLI environments. This tutorial builds one small workflow: initialize the client, sign in, create and query a record, update it, and release a realtime subscription.

Before you begin

You need a running PocketBase server and a posts collection with a title field. Configure its API rules for the user role you will test. Create a test auth record and use synthetic content.

Add the package to pubspec.yaml, then run dart pub get:

yaml

dependencies:
  pocketbase: ^0.0.1

Use the current compatible version from the Dart SDK package when you create your project. The exact package version is intentionally selected by your application's dependency constraints.

Build the Dart workflow

Initialize the client

Import the package and create a client for the server.

dart

import 'package:pocketbase/pocketbase.dart';

final pb = PocketBase('http://127.0.0.1:8090');

Keep this instance available to the part of the application that performs authentication and data access.

Authenticate the user

Authenticate an auth collection record.

dart

try {
  final authData = await pb.collection('users').authWithPassword(
    'reader@example.com',
    'use-a-test-password',
  );
  print(authData.record.id);
} catch (error) {
  print('Sign-in failed: $error');
}

After success, the client auth store contains the session state. Keep credentials out of source control and logs.

Create and list records

Create a record and request the first page with a filter.

dart

final created = await pb.collection('posts').create(
  body: {'title': 'A Dart SDK note'},
);

final page = await pb.collection('posts').getList(
  page: 1,
  perPage: 30,
  sort: '-created',
  filter: 'title ~ "Dart"',
);

print('${created.id}: ${page.items.length}');

The create call returns the new record. The list call returns a paginated result. Rules can limit the records returned or reject the operation.

Read and update a record

Use the returned ID to read the record and apply a partial update.

dart

final record = await pb.collection('posts').getOne(created.id);
final updated = await pb.collection('posts').update(
  created.id,
  body: {'title': '${record.data['title']} (updated)'},
);

print(updated.data['title']);

The update corresponds to the record PATCH operation. The collection's update rule and field validation still apply.

Subscribe and clean up

Subscribe to changes and remove the subscription when the consuming widget, screen, or command ends.

dart

final subscription = await pb.collection('posts').subscribe('*', (event) {
  print('${event.action}: ${event.record.id}');
});

await pb.collection('posts').unsubscribe('*');

The callback receives the action and changed record. Cleanup prevents a disposed view from continuing to receive events.

✅The completed workflow prints a record ID, a page item count, the updated title, and any later record-change events.

Troubleshoot requests

For 403, inspect the collection's create, list, view, or update rule and confirm the client is authenticated when required.
For 400, validate the body fields and filter syntax against the collection schema. Start with a request containing one known field.
For a missing record, verify that the collection name and ID came from the same server and environment.
If events continue after a screen closes, call unsubscribe during that screen's disposal lifecycle.

Next steps

Read work with records and queries, realtime subscriptions, and Dart SDK API records. Use JavaScript SDK when your client targets JavaScript.