Getting Started

This guide will help you get up and running with DB plugin quickly. You'll learn how to create your first domain objects, and perform basic operations.

Creating Your First Record Class

A Record is your domain object that maps to database storage. Here's a simple example:

1import java.util.ArrayList;
2import java.util.Date;
3import java.util.List;
4
5import com.psddev.dari.db.Record;
6
7public class Article extends Record {
8
9    @Indexed
10    private String title;
11
12    @Indexed
13    @Required
14    private Author author;
15
16    @Indexed
17    private Date publishDate;
18
19    private String content;
20
21    private List<String> tags;
22
23    // Getters and setters
24    public String getTitle() {
25        return title;
26    }
27
28    public void setTitle(String title) {
29        this.title = title;
30    }
31
32    public Author getAuthor() {
33        return author;
34    }
35
36    public void setAuthor(Author author) {
37        this.author = author;
38    }
39
40    public Date getPublishDate() {
41        return publishDate;
42    }
43
44    public void setPublishDate(Date publishDate) {
45        this.publishDate = publishDate;
46    }
47
48    public String getContent() {
49        return content;
50    }
51
52    public void setContent(String content) {
53        this.content = content;
54    }
55
56    public List<String> getTags() {
57        if (tags == null) {
58            tags = new ArrayList<>();
59        }
60        return tags;
61    }
62
63    public void setTags(List<String> tags) {
64        this.tags = tags;
65    }
66
67    // Optional: Override getLabel for display purposes
68    @Override
69    public String getLabel() {
70        return title != null ? title : "Untitled Article";
71    }
72}

1import com.psddev.dari.db.Record;
2
3public class Author extends Record {
4
5    @Indexed
6    @Required
7    private String name;
8
9    @Indexed
10    private String email;
11
12    private String bio;
13
14    // Getters and setters
15    public String getName() {
16        return name;
17    }
18
19    public void setName(String name) {
20        this.name = name;
21    }
22
23    public String getEmail() {
24        return email;
25    }
26
27    public void setEmail(String email) {
28        this.email = email;
29    }
30
31    public String getBio() {
32        return bio;
33    }
34
35    public void setBio(String bio) {
36        this.bio = bio;
37    }
38
39    @Override
40    public String getLabel() {
41        return name;
42    }
43}

Important Annotations

@Indexed - Makes a field queryable. Required for any field you want to filter/sort by.
@Required - Field must have a value before saving.
@Embedded - Always stores the object inline (no separate table/document).

Basic CRUD Operations

Creating and Saving Objects

1// Create a new author
2Author author = new Author();
3author.setName("John Doe");
4author.setEmail("john@example.com");
5author.setBio("Experienced writer and developer");
6author.save();
7
8// Create an article
9Article article = new Article();
10article.setTitle("Getting Started with DB plugin");
11article.setAuthor(author);  // Reference to author
12article.setPublishDate(new Date());
13article.setContent("This is the content of the article...");
14article.setTags(Arrays.asList("database", "tutorial", "java"));
15article.save();

Reading Objects by ID

Every Record has a unique ID (UUID):

1// Get the ID
2UUID articleId = article.getId();
3
4// Later, load by ID
5Article loaded = Query.from(Article.class)
6    .where("_id = ?", articleId)
7    .first();

Querying Objects

1// Find all articles
2List<Article> allArticles = Query.from(Article.class)
3    .selectAll();

1// Find articles by author
2List<Article> johnArticles = Query.from(Article.class)
3    .where("author = ?", author)
4    .selectAll();

1// Find articles by author name (path-based query)
2List<Article> authorArticles = Query.from(Article.class)
3    .where("author/name = ?", "John Doe")
4    .selectAll();

1// Find recent articles
2Date recentCutoff = DateUtils.addDays(new Date(), -7);
3List<Article> recentArticles = Query.from(Article.class)
4    .where("publishDate > ?", recentCutoff)
5    .sortDescending("publishDate")
6    .selectAll();

1// Paginated results
2PaginatedResult<Article> firstPage = Query.from(Article.class)
3    .sortDescending("publishDate")
4    .select(0, 10);  // Skip 0, limit 10

1// Count articles
2long totalArticles = Query.from(Article.class)
3    .count();

Updating Objects

1// Load the object
2Article loadedArticle = Query.from(Article.class)
3    .where("_id = ?", articleId)
4    .first();
5
6// Modify fields
7loadedArticle.setTitle("Updated Title");
8loadedArticle.getTags().add("updated");
9
10// Save changes
11loadedArticle.save();

Deleting Objects

1// Delete a single object
2article.delete();

1// Delete by query
2Query.from(Article.class)
3    .where("publishDate < ?", cutoffDate)
4    .deleteAll();

Working with References

DB plugin automatically handles relationships between objects:

1// Save author first
2Author author = new Author();
3author.setName("Jane Smith");
4author.save();
5
6// Create article with reference
7Article article = new Article();
8article.setTitle("My Article");
9article.setAuthor(author);  // This stores a reference, not a copy
10article.save();
11
12// Later, when you load the article
13Article loaded = Query.from(Article.class)
14    .where("_id = ?", article.getId())
15    .first();
16
17// The author is lazy-loaded
18Author loadedAuthor = loaded.getAuthor();  // Database query happens here
19System.out.println(loadedAuthor.getName());  // "Jane Smith"

Reference Resolution Options

1// Reference-only query (don't load full objects)
2List<Article> articleRefs = Query.from(Article.class)
3    .resolveToReferenceOnly()
4    .selectAll();
5// articleRefs contains lightweight reference objects

Using Transactions

For multiple operations that should succeed or fail together:

1Database db = Database.Static.getDefault();
2
3try {
4    db.beginWrites();
5
6    // Create multiple objects
7    Author author = new Author();
8    author.setName("John Doe");
9    author.save();
10
11    Article article1 = new Article();
12    article1.setTitle("First Article");
13    article1.setAuthor(author);
14    article1.save();
15
16    Article article2 = new Article();
17    article2.setTitle("Second Article");
18    article2.setAuthor(author);
19    article2.save();
20
21    // Commit all changes
22    db.commitWrites();
23
24} finally {
25    // Always clean up (rolls back on exception)
26    db.endWrites();
27}

Validation

DB plugin validates objects before saving:

1import common.Author;
2import com.psddev.dari.db.Record;
3import com.psddev.dari.db.Recordable;
4
5public class Article extends Record {
6
7    @Recordable.Required
8    @Recordable.Maximum(200)
9    private String title;
10
11    @Recordable.Required
12    private Author author;
13
14    @Override
15    protected void onValidate() {
16        if (title != null && title.contains("spam")) {
17            getState().addError(
18                getState().getField("title"),
19                new IllegalArgumentException("Title contains spam")
20            );
21        }
22    }
23
24    public String getTitle() {
25        return title;
26    }
27
28    public void setTitle(String title) {
29        this.title = title;
30    }
31
32    public Author getAuthor() {
33        return author;
34    }
35
36    public void setAuthor(Author author) {
37        this.author = author;
38    }
39}

1// Attempting to save an invalid object throws ValidationException
2Article article = new Article();
3// article.setTitle(null);    // Required field missing
4// article.setAuthor(null);   // Also required
5
6try {
7    article.save();
8} catch (ValidationException e) {
9    // Handle validation errors
10    for (ObjectField field : e.getStates()
11        .stream()
12        .map(State::getErrorFields)
13        .flatMap(Collection::stream)
14        .collect(Collectors.toList())) {
15        System.out.println("Error in " + field.getInternalName() + ": "
16            + field.getState().getFieldErrors(field));
17    }
18}

Lifecycle Hooks

Override lifecycle methods to add custom behavior:

1import java.util.Date;
2
3import com.psddev.dari.db.Record;
4
5public class Article extends Record {
6
7    private String title;
8    private Date publishDate;
9
10    @Override
11    protected void beforeSave() {
12        // Called before validation and save
13        if (publishDate == null) {
14            publishDate = new Date();
15        }
16    }
17
18    @Override
19    protected void afterSave() {
20        // Called after successful save
21        System.out.println("Article saved: " + getLabel());
22    }
23
24    @Override
25    protected void beforeDelete() {
26        // Called before delete
27        System.out.println("Deleting article: " + getLabel());
28    }
29
30    @Override
31    protected void afterDelete() {
32        // Called after successful delete
33        System.out.println("Article deleted");
34    }
35
36    public String getTitle() {
37        return title;
38    }
39
40    public void setTitle(String title) {
41        this.title = title;
42    }
43
44    public Date getPublishDate() {
45        return publishDate;
46    }
47
48    public void setPublishDate(Date publishDate) {
49        this.publishDate = publishDate;
50    }
51}

Common Query Patterns

Search by Multiple Tags

1// Find articles with any of the specified tags
2List<Article> articles = Query.from(Article.class)
3    .where("tags = ?", Arrays.asList("java", "database", "tutorial"))
4    .selectAll();
5
6// Find articles with all specified tags (requires all)
7// This requires querying differently - use repeated predicates
8Query<Article> query = Query.from(Article.class);
9for (String tag : Arrays.asList("java", "database")) {
10    query.and("tags = ?", tag);
11}
12List<Article> articlesWithAllTags = query.selectAll();

Counting and Statistics

1// Total count
2long totalArticles = Query.from(Article.class).count();
3
4// Conditional count
5long publishedCount = Query.from(Article.class)
6    .where("publishDate != missing")
7    .count();
8
9// Count by author
10long johnCount = Query.from(Article.class)
11    .where("author/name = ?", "John Doe")
12    .count();

Best Practices

1. Always Index Queryable Fields

1// Good
2@Indexed
3private String title;
4
5// Bad - can't query this field
6private String title;

2. Use Transactions for Multiple Writes

1// Good - atomic
2db.beginWrites();
3try {
4    Author author = new Author();
5    author.save();
6    Article article = new Article();
7    article.save();
8    db.commitWrites();
9} finally {
10    db.endWrites();
11}
12
13// Bad - non-atomic, could partially succeed
14Author author2 = new Author();
15author2.save();
16Article article2 = new Article();
17article2.save();

3. Use Pagination for Large Result Sets

1// Good - memory efficient
2PaginatedResult<Article> page = Query.from(Article.class)
3    .select(offset, limit);
4
5// Bad - loads everything into memory
6List<Article> all = Query.from(Article.class)
7    .selectAll();

4. Prefer Path Queries Over Manual Joins

1// Good - simple and efficient
2Query.from(Article.class)
3    .where("author/name = ?", "John Doe")
4    .selectAll();
5
6// Avoid - more complex
7Author author = Query.from(Author.class)
8    .where("name = ?", "John Doe")
9    .first();
10Query.from(Article.class)
11    .where("author = ?", author)
12    .selectAll();

5. Initialize Collections in Getters

1// Good
2public List<String> getTags() {
3    if (tags == null) {
4        tags = new ArrayList<>();
5    }
6    return tags;
7}
8
9// Bad - can return null
10public List<String> getTags() {
11    return tags;
12}

Creating Your First Record Class​

Important Annotations​

Basic CRUD Operations​

Creating and Saving Objects​

Reading Objects by ID​

Querying Objects​

Updating Objects​

Deleting Objects​

Working with References​

Reference Resolution Options​

Using Transactions​

Validation​

Lifecycle Hooks​

Common Query Patterns​

Search by Multiple Tags​

Counting and Statistics​

Best Practices​

1. Always Index Queryable Fields​

2. Use Transactions for Multiple Writes​

3. Use Pagination for Large Result Sets​

4. Prefer Path Queries Over Manual Joins​

5. Initialize Collections in Getters​