Errors

Every error from Orbit is one enum, Error. Some database errors have variants of their own, so a caller can match them. Any other database error is Error::Database, which holds the sqlx error.

use orbit_orm::{Error, Model};

match Post::query().insert(&db, &[("title", "Hello".into())]).await {
    Ok(id) => println!("inserted {id}"),
    Err(Error::UniqueViolation { index }) => println!("unique index {index:?} was violated"),
    Err(Error::ForeignKeyViolation { constraint }) => println!("foreign key {constraint:?} was violated"),
    Err(Error::Deadlock) | Err(Error::LockWaitTimeout) => println!("retry the transaction"),
    Err(other) => return Err(other),
}

Database errors

• Database(sqlx::Error): the database rejected a connection, a query or a statement, and no other variant fits.
• UniqueViolation { index }: an insert or update broke a unique index or the primary key. index is the index name when the server reports it.
• ForeignKeyViolation { constraint }: a row refers to a missing parent, or a parent is still referenced. constraint is the foreign key name when the server reports it.
• Deadlock: the database rolled back the whole transaction to break a deadlock. Run it again.
• LockWaitTimeout: a lock was not released in time. Only the statement failed, and the transaction is still open.

Orbit recognises the deadlock and lock wait cases by MySQL's error numbers, 1213 and 1205.

Query errors

• NotFound { table }: first_or_fail or find_or_fail found no row.
• NotFillable { table, column }: insert, replace or update named a column that is not in the model's FILLABLE list.
• InvalidIdentifier(name): a table or column name is empty or contains a backtick.
• BlockingInRuntime: a blocking call ran on a thread that runs async code. Call it inside tokio::task::spawn_blocking. See Blocking API.

Migration errors

• Read { path, source }: a file could not be read, such as a migration's up.sql.
• DuplicateMigration { name }: two migrations have the same name.
• InvalidMigrationName { name }: a name does not start with a 14-digit timestamp and an underscore.
• DuplicateTimestamp { first, second }: two migrations share a timestamp, so their order is not defined.
• MigrationsLocked { seconds }: another process ran migrations and did not finish within the lock timeout.
• MigrationFailed { name, source }: a migration's up.sql failed. The run stopped there, and earlier migrations stay applied.
• RollbackFailed { name, source }: a migration's down.sql failed. The rollback stopped there.
• UnknownMigration { name }: a migration is recorded as applied, but this migrator has no files for it, so it cannot be rolled back.

See Migrations for how these errors arise.