Is PrimaryKey's autoGenerate exactly equivalent to SQLite's AUTOINCREMENT?

Question

Is marking a primary key with @PrimaryKey(autoGenerate = true) exactly the same as if you had used PRIMARY KEY AUTOINCREMENT in an SQL statement?

Intuition tells me yes, but documentation seems to suggest no.

Room javadoc states:

Set to true to let SQLite generate the unique id.

as if setting it false will prevent SQLite from generating the key.

But SQLite documentation for AUTOINCREMENT states that SQLite always generates a currently-unique key if none is given when doing an INSERT, and that AUTOINCREMENT merely adds the additional behavior that SQLite will never allow an automatically generated key to overlap with any previously deleted row.

The SQLite documentation also recommends not using AUTOINCREMENT if it isn't needed (for performance reasons), and states that it is usually not needed. From the description, that seems to match my case. My table will be fine if a previously deleted row ID gets reused.

Answer 1

Is marking a primary key with @PrimaryKey(autoGenerate = true) exactly the same as if you had used PRIMARY KEY AUTOINCREMENT in an SQL statement?

Yes, as using autoGenerate=true adds the AUTOINCREMENT keyword.

But

as if setting it false will prevent SQLite from generating the key.

Is false.

If a class is:-

• annotated with @Entity, and
• the column/variable/member is annotated with @PrimaryKey, and
• if the type resolves to an integer type
  • (byte .... double, primitive or Object (e.g. Double))

then the value can be generated (it is INTEGER PRIMARY KEY that makes the column a special column that can be generated as that column is then an alias of the rowid (a normally hidden column)).

AUTOINCREMENT is only applicable to aliases of the rowid (i.e. INTEGER PRIMARY KEY). It does not determine whether the value can be generated (in the absence of a value for the column or when the value is null).

What AUTOINCREMENT does is add an additional rule when generating the value. That rule being that the value MUST be higher than any ever used for that table.

There are subtle differences.

Without AUTOINCREMENT

• deleting the row with the highest value, frees that value for subsequent use (and would be used to generate the value still higher than any other value that exists at that time), and
• should the highest value (9223372036854775807) be reached SQLite will try to find a free lower value, and
• lastly it is possible to double the range of values by using negative values.

With AUTOINCREMENT

• deleting the row with the highest value does not free that value for subsequent use

• should the highest value (9223372036854775807) be reached then subsequent attempts to insert with a generated value will fail with an SQLITE FULL error.

  • If you insert 1 row with a value of 9223372036854775807 then that's the only row that can be inserted.

• negative values cannot be generated (can still be used)

• an additional table is required (sqlite_sequence), which is automatically created by SQLite, that will have a row per table with AUTOINCREMENT. The highest used value is stored in the row. So whenever inserting when the value is to be generated requires the respective row to be retrieved and the value obtained, after insertion the value has to be updated. As such there are overheads associated with using AUTOINCREMENT.

• Note the above is assuming that methods to circumvent SQLite's in-built handling are not circumvented (such as updating values in the sqlite_sequence table).

I would always advocate using (not using autoGenerate=true) e.g.

@PrimaryKey
Long id_column=null;

or

@PrimaryKey
var id_column: Long?=null

thus an @Insert (convenience insert) will autogenerate if no value is given for the id_column.

---

Demo

Consider the following two @Entity annotated classes (with and without autoGenerate=true) :-

AutoInc:-

@Entity
data class AutoInc(
    @PrimaryKey(autoGenerate = true)
    val id: Long?=null,
    val other: String
)

NoAutoInc:-

@Entity
data class NoAutoInc(
    @PrimaryKey
    var id: Long?=null,
    var other:String
)

Room (after compiling and looking at the generated java in the class that is the same name as the @Database annotated class) has the following in the createAllTables method/function:-

    _db.execSQL("CREATE TABLE IF NOT EXISTS `AutoInc` (`id` INTEGER PRIMARY KEY AUTOINCREMENT, `other` TEXT NOT NULL)");
    _db.execSQL("CREATE TABLE IF NOT EXISTS `NoAutoInc` (`id` INTEGER, `other` TEXT NOT NULL, PRIMARY KEY(`id`))");

i.e. the only difference is the AUTOINCREMENT keyword.

Then consider the following code :-

    /* Typical  where the id will be generated */
    dao.insert(AutoInc(other = "A"))
    dao.insert(AutoInc(null,other = "B"))
    dao.insert(NoAutoInc(other ="A"))
    dao.insert(NoAutoInc(null, other = "B"))

    /* Beware */
    /* Room interprets types different ways
        here 0 is taken to be 0 as id is an Object
        if long (Java) then 0 will be generated id
        getters/setters are taken in to consideration when determining type
    * */
    dao.insert(AutoInc(0,other = "W"))
    dao.insert(NoAutoInc(0,other ="W"))

    /* Unusual */
    dao.insert(AutoInc(-100,"X"))
    dao.insert(NoAutoInc(-100,other ="X"))
    dao.insert(AutoInc(9223372036854775807,"Y")) /* The maximum value for an id */
    dao.insert(NoAutoInc(9223372036854775807,"Y")) /* The maximum value for an id */

When run then the tables (via Android Studio's App Inspection) are:-

AutInc:-

Note the Z row has not been added due to :-

E/SQLiteLog: (13) statement aborts at 4: [INSERT OR ABORT INTO `AutoInc` (`id`,`other`) VALUES (?,?)] database or disk is full

However, the disk isn't full as Disk Explorer shows:-

It's by no means full as Disk Explorer shows (and of course the subsequent step works inserting a row into the database):-

and

NoAutInc

Here the Z row has been added with a generated id based upon SQLite finding an unused value due to the highest allowable value for an id having been reached as opposed to the failure due to the disk/table full.