The SQLDelight documentation is unclear: do you need to run `Database.Schema.migrate(…)` manually or...

# squarelibraries

[ribesg]

The SQLDelight documentation is unclear: do you need to run Database.Schema.migrate(…) manually or not?
https://cashapp.github.io/sqldelight/2.0.1/multiplatform_sqlite/migrations/
The documentation describes how to define migrations, states that These SQL statements are run by the Database.Schema.migrate() method but then If you run your migration from code. What does If mean? It's optional after all?

[Benoit Quenaudon]

SqlDelight will run migration on startup. The If means In the case of : you have the possibility to run this code yourself.

[ribesg]

Right, that's what I guessed then confirmed by trying, but my point is that it should be obvious in the documentation and there is room for improvement here. The fact that these migration files are executed automatically is simply not stated in the documentation

[Benoit Quenaudon]

Got it. I think the repo is open to PR if you wanna improve the doc.

[Derek Ellis]

It depends on the driver. The Android (and iOS) drivers will automatically handle migrations for you. All others don't.

[ribesg]

I don't even get how you could call Database.Schema.migrate() as there don't seem to be a way to know what the current version of the db file is. Are you supposed to store it somewhere else? Or maybe it's platform specific

[jw]

You store it

[jw]

Common place to put it is in a non-schema table

[ribesg]

How does it work automatically then? Isn't it already stored

[jw]

You didn't ask about the automatic case. You asked about the case where you would need to call migrate() yourself.

[jw]

For sqlite on Android, for example, the version is stored with a PRAGMA that gets persisted

[jw]

The built-in API supports providing a version and will automatically give a callback to perform migration, if needed

[jw]

On platforms without built-in support, you can replicate such behavior yourself and explicitly call the create or migrate APIs as needed

[ribesg]

I only know what's in the documentation, so almost nothing. I just learned that some drivers just don't do the automatic migrations.

[ribesg]

When does the automatic migration occur? How do I know when to call Database.Schema.migrate() if I want to? Won't it be called twice then?

[jw]

If there is automatic migration you will never call it

[jw]

It occurs when the database is opened

[Derek Ellis]

There's an example in the SQLite JDBC driver that demonstrates how to check for the database's current version and migrate if needed: https://github.com/cashapp/sqldelight/blob/master/drivers/sqlite-driver/src/main/k[…]tlin/app/cash/sqldelight/driver/jdbc/sqlite/JdbcSqliteSchema.kt

[ribesg]

So: on all platforms that are not Android & iOS, I need to store the version of the db file somewhere and call Database.Schema.migrate(). On Android & iOS, I just let it work automatically. Right?

[Derek Ellis]

Correct