Database

Database sources let an organization ingest durable records from a read-only database connection.

Create and manage database sources from the organization dashboard under Integrations > Database.

When to use a database source

Use a database source when records already live in an operational database and should become available to Achiral memory.

Database sources are best for structured records such as orders, accounts, cases, events, documents, inventory, usage records, or internal product state.

Create a source

Select New database source, then provide:

• Source name: a human-readable name for the source.
• Database type: MongoDB, PostgreSQL, MySQL, Amazon Redshift, Snowflake, BigQuery, or SQL Server.
• Database name: the database to read from.
• Collection or table: the specific record set Achiral should read.
• Read-only connection string: a credential with the narrowest possible read access.
• Memory event type: the event label assigned to records from this source.

Use Validate to check the source before creating it. Use Preview rows to inspect sample records.

Advanced read settings

Advanced settings expose lower-level read controls:

• Read operation: the database read operation to run.
• Read filter: JSON that scopes which records should be read.
• Query parameters: optional values passed to the read operation.
• Cursor field: an optional timestamp field used to resume later reads.

Keep filters narrow. A database source should ingest only the records that are useful for organization memory.

Supported databases

Achiral supports read-only database sources for:

• MongoDB: use a MongoDB connection string, database name, collection name, and a JSON read filter.
• PostgreSQL: use a postgres:// connection string and a read-only SQL query.
• MySQL: use a mysql:// connection string and a read-only SQL query.
• Amazon Redshift: use a Postgres-compatible connection string and a read-only SQL query.
• Snowflake: use a Snowflake URL or JSON connection configuration and a read-only SQL query.
• BigQuery: use a JSON connection configuration and a read-only SQL query.
• SQL Server: use a SQL Server URL or JSON connection configuration and a read-only SQL query.

Relational and warehouse sources accept queries that start with select or with. Mutating statements such as insert, update, delete, drop, alter, truncate, create, grant, revoke, merge, replace, call, and exec are blocked before execution.

Connection formats

Use the narrowest credential that can read the records you need.

PostgreSQL and Redshift use standard Postgres connection strings:

postgres://readonly:[email protected]:5432/app?sslmode=require

MySQL uses a standard MySQL connection string:

mysql://readonly:[email protected]:3306/app?ssl=true

SQL Server can use a URL:

sqlserver://readonly:[email protected]:1433/app?encrypt=true

Snowflake can use a URL:

snowflake://readonly:[email protected]/ANALYTICS?schema=PUBLIC&warehouse=LOAD_WH&role=ACHIRAL_READONLY

BigQuery uses JSON because Google Cloud authentication usually needs a project and credentials:

{
  "projectId": "customer-project",
  "keyFilename": "/path/to/service-account.json"
}

Snowflake and SQL Server also accept JSON configuration when URL fields are not enough.

Query parameters

Use parameters instead of interpolating values into SQL.

PostgreSQL and Redshift use positional parameters:

select id, updated_at from orders where updated_at > $1 order by updated_at asc

MySQL and Snowflake use ? parameters:

select id, updated_at from orders where updated_at > ? order by updated_at asc

SQL Server uses named @p1, @p2, and later parameters:

select id, updated_at from dbo.orders where updated_at > @p1 order by updated_at asc

BigQuery can use named parameters:

select id, updated_at from `dataset.orders` where updated_at > @cursor order by updated_at asc

Security

Use a read-only credential. Limit access to the database, table, collection, and fields that Achiral needs.

Prefer network allow-listing and TLS where supported. Rotate connection strings when access changes or a source is retired.

Operations

Database sources can be paused, resumed, or archived from the Database tab.

• Active sources are available for ingestion.
• Paused sources remain configured but do not run scheduled ingestion work.
• Archived sources are retired and should not be used for new ingestion.

Troubleshooting

If validation, preview, or ingestion fails:

• Confirm the connection string uses a read-only credential.
• Confirm the database and collection or table names are correct.
• Confirm the read filter is valid JSON.
• Check whether network policy, TLS, or allow-listing is blocking the connection.

Related pages

• Connectors — authorize popular apps and tools.
• API sources — read records from APIs that are not available as connectors.
• Organization — manage organization settings and access.