> ## Documentation Index
> Fetch the complete documentation index at: https://deepline.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Database reference

> Workspace database schemas, SQL permissions, and cache boundaries.

Each workspace has an ingestion PostgreSQL database. The public query API uses your workspace API key. Direct PostgreSQL access uses a separate database role.
For connection and query procedures, see [Query your Database](https://deepline.com/docs/database-access.md).

## Schemas

| Schema | Contract |
| - | - |
| `enrichments` | Deepline manages enrichment data, including `enrichments.enrichments` and `enrichments.companies`. Customers can read this data but cannot change it. |
| `crm` | Deepline manages normalized CRM and sequencing data. Customers can read this data but cannot change it. |
| Provider schemas | Managed data for `hubspot`, `salesforce`, `attio`, `instantly`, `lemlist`, `heyreach`, `smartlead`, and `theirstack`. Available rows depend on configured ingestion. |
| Monitor schemas | Managed data for `deepline_native`, `parallel`, `firecrawl`, `findymail`, and `predictleads`. Available rows depend on configured Monitors. |
| `dl_catalog` | Managed object-materialization metadata. |
| `dl_ingest`, `dl_meta` | Deepline manages ingestion and metadata objects. The database prevents customer writes to these objects. |
| `storage` | Customer storage contains files and customer-created tables. Separate permissions protect internal runtime receipt objects. |
| Customer-managed schemas | Customers can create schemas with names outside the reserved set. Schema-qualified SQL can create and change objects in these schemas. |

The bootstrap does not provide `dl_resolved.people`, `dl_graph`, `dl_cache`, or
`dl_override` as a managed identity-graph contract.

## SQL API

`POST /api/v2/db/query` accepts one SQL statement and `max_rows` (up to 1,000).
The response contains `rows`, `columns`, `row_count_returned`, and `truncated`.
The SDK equivalent is `client.db.query({ sql, maxRows })`.

Reads include `SELECT`, read-only `WITH`, and `EXPLAIN` subject to the query
policy. Writes must identify a schema-qualified target in `storage` or an
allowed customer-managed schema. Managed data, internal runtime objects,
`public`, `information_schema`, and `pg_*` schemas are not customer write targets.
Retired internal schema names are also reserved. Choose a new schema name
when the query API reports a reserved target.

Example against a provisioned company table:

```sql theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
SELECT domain, company_name, industry, employee_count
FROM enrichments.companies
ORDER BY updated_at DESC
LIMIT 20;
```

Provisioning creates this table. The table can contain no rows.

## Roles and direct connections

* `dl_ingest_customer_db`: This customer connection role reads managed tables. Ownership grants let this role own permitted customer storage objects.
* `dl_ingest_runtime`: This Deepline runtime role can write managed ingestion data and customer storage.
* `dl_ingest_customer_owner`: ownership role for customer-managed objects.
* `dl_ingest_owner`, `dl_ingest_storage_owner`, and
  `dl_ingest_protected_owner`: platform ownership roles, not customer credentials.

URI reveal, provisioning, and password rotation require the dashboard/admin
session flow. A workspace API key for SQL queries is not a URI-reveal credential.

## Persistence and caching

Saved database rows and reusable tool-call results serve different purposes.
Persistence alone does not make future provider requests free.

The [SDK freshness options](https://deepline.com/docs/sdk-v2/sdk-reference.md) control durable call reuse:

| `staleAfterSeconds` | Behavior |
| - | - |
| `null` | Allows indefinite reuse of a completed result. |
| `0` | Starts fresh logical work; a completed operation receipt can recover the same operation after resume. |
| Positive integer | Sets the maximum age of a reusable result, in seconds. |

Edition 11 requires an explicit choice. Earlier admitted editions retain their
omitted-value behavior. The admitted
[authoring contract](https://deepline.com/docs/sdk-v2/sdk-reference.md) determines the applicable rules.

Reuse also depends on the operation, inputs, authentication identity, and
version policy. Certain live-state tools are always fresh. Plays execute at least once. Cache reuse does not guarantee that a provider effect occurs exactly once.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.