Skip to content

Defining Database Schema

Jump to bottom
Siim Kinks edited this page Mar 21, 2017 · 6 revisions

SqliteMagic supports two types of objects to define database schema with - POJOs (or Plain Old Java Objects) and AutoValue immutable objects. Generally, there is no difference for SqliteMagic which one (or both) to use, except some minor differences which are described below.

Minimal requirement to define a database table is to annotate an object with @Table(persistAll=true). No other extra configuration needed - the annotation processor can find its way from there on. Also, when using AutoValue there has to be one long or Long type returning method with @Id annotation which represents the primary key.

POJO SQL 
@Table(persistAll = true)
public class Author {
  String firstName;
  String lastName;

  ...
}
 
CREATE TABLE IF NOT EXISTS author (
  _id        INTEGER PRIMARY KEY AUTOINCREMENT,
  first_name TEXT,
  last_name  TEXT
);
AutoValue SQL 
@Table(persistAll = true)
@AutoValue
public abstract class Author {
  @Id
  public abstract long id();
  public abstract String firstName();
  public abstract String lastName();
  
  ...
}
 
CREATE TABLE IF NOT EXISTS author (
  id         INTEGER PRIMARY KEY AUTOINCREMENT,
  first_name TEXT,
  last_name  TEXT
);

Note that there is no need to extend or implement any base classes or interfaces.

By default only fields/methods with @Column annotation are added to the schema. In the example above there is an annotation @Table(persistAll = true) which configures annotation processor to add all suitable fields/methods to the schema.

Annotations

There are following annotations for defining database table schema:

  • @Table Defines a table in a database.

    • value: String Table name. The default is lowercased object name where camel case is replaced with "_" character.
    • persistAll: boolean Persist all suitable columns using the default behavior of @Column. If any column has @Column annotation then it uses its preferences. If any column is annotated with @IgnoreColumn then this field is ignored. The default is false.
    • useAccessMethods: boolean Respect access methods when accessing fields. This parameter has effect only on POJOs. Access methods can be with names representing field names e.g. name(), name(String) or with JavaBeans-style prefixes like getName(), setName(String), isMale(). The default is false.

  • @Column Defines a column in a table. This annotation is valid on methods for AutoValue objects and on fields for POJO objects.

    • value: String Column name. The default is field or method name where camel case is replaced with "_" character.
    • handleRecursively: boolean Define if complex column should be handled recursively, meaning that its values are persisted/retrieved in full extent. If set to false, only its @Id annotated column is persisted/retrieved. Note that complex column must also be defined with @Table annotation for system to know how to persist/retrieve them. The default value is true.
    • onDeleteCascade: boolean Define for complex column if ON DELETE CASCADE foreign key action should be added to table definition. The default value is false.
    • useAccessMethods: boolean Respect access methods when accessing this column. This parameter has effect only on POJOs. Access methods can be with names representing field names e.g. name(), name(String) or with JavaBeans-style prefixes like getName(), setName(String), isMale(). The default is false.

  • @Id Define a column to be the primary key for table. Annotated field/method must have either long or Long Java type. Each table must have one and only one column with @Id annotation. The only exception is POJO objects where it can be omitted. In that case system generates "magic" long type private field named "id" (see also Database Operations). There is no need to define @Column annotation if column already has @Id annotation.

    • autoIncrement: boolean Define if id column should be auto-incremented. The default value is true.

  • @IgnoreColumn All fields with this annotation are ignored when @Table#persistAll() is true.

  • @Unique Define a SQL UNIQUE constraint on column.

Android Support Annotations

SqliteMagic supports @NonNull/@Nullable annotations on columns which adds/removes null checks when parsing data.

These annotations are also used to determine how shallow object can be when querying complex data structures. See more at Deep vs Shallow.

Supported Java Types

All primitive Java datatypes and their boxed counterparts plus byte arrays and String objects are supported.

All Java datatypes are translated into SQLite supported datatypes:

  • NULL - all null objects
  • INTEGER - long, Long, int, Integer, boolean and Boolean
  • REAL - double, Double, float and Float
  • TEXT - String
  • BLOB - byte, Byte, byte[] and Byte[]

Other Supported Types

SqliteMagic supports the following objects as columns:

Clone this wiki locally