> For the complete documentation index, see [llms.txt](https://quantumphp.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://quantumphp.gitbook.io/docs/packages/database/contracts.md).

# Contracts

The Database package exposes two main interfaces.

## `DbalInterface`

`Quantum\Database\Contracts\DbalInterface` defines the common model-facing API for both relational and SleekDB adapters.

### Connection methods

* `connect(array $config)`
* `getConnection(): ?array`
* `disconnect()`

These are static, because adapter connections are stored at adapter-class level.

### Query-building methods

* `select(...$columns)`
* `criteria(string $column, string $operator, $value = null)`
* `criterias(...$criterias)`
* `having(string $column, string $operator, ?string $value = null)`
* `groupBy(string $column)`
* `orderBy(string $column, string $direction)`
* `offset(int $offset)`
* `limit(int $limit)`
* `isNull(string $column)`
* `isNotNull(string $column)`

All of these return the same adapter instance for fluent chaining.

`offset()` is only useful when you also apply `limit()`. The interface documents it as a paged-result modifier rather than a standalone skip operation.

### Result methods

* `get(): array`
* `count(): int`
* `asArray(): array`
* `findOne(int $id)`
* `findOneBy(string $column, $value)`
* `first()`

`get()` returns a list of adapter/model objects, not plain arrays.

Lookup miss behavior matters when you reuse the same model instance:

* Idiorm leaves the current instance unchanged when `findOne()`, `findOneBy()`, or `first()` do not find a row.
* SleekDB resets the instance data to an empty payload on a miss.

If you are doing probe-style lookups, prefer a fresh model instance or explicitly inspect the result before reusing the object.

### Mutation methods

* `create()`
* `prop(string $key, $value = null)`
* `save(): bool`
* `delete(): bool`
* `truncate(): bool`
* `deleteMany(): bool`

`prop()` doubles as getter and setter.

### Relation method

* `joinTo(DbModel $model, bool $switch = true)`

`joinTo()` relies on the current model's relation metadata. If the relation type or keys are missing, model-level exceptions are thrown when the join is validated.

## `RelationalInterface`

`Quantum\Database\Contracts\RelationalInterface` is only for relational adapters.

### Static raw-query methods

* `execute(string $query, array $parameters = []): bool`
* `query(string $query, array $parameters = []): array`
* `lastQuery(): ?string`
* `lastStatement(): object`
* `queryLog(): array`

These methods power `Database::execute()`, `Database::query()`, and the schema builder.

### SQL join methods

* `join(string $table, array $constraint, ?string $tableAlias = null)`
* `innerJoin(string $table, array $constraint, ?string $tableAlias = null)`
* `leftJoin(string $table, array $constraint, ?string $tableAlias = null)`
* `rightJoin(string $table, array $constraint, ?string $tableAlias = null)`

## Error surface

The package mostly raises `DatabaseException` for adapter/config/operator failures:

* unsupported adapter key
* unsupported query operator
* missing or incorrect database config
* schema table existence failures
* missing transactional method on the active adapter

Relation validation failures come from the Model package, not from `DatabaseException`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://quantumphp.gitbook.io/docs/packages/database/contracts.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.