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

# Integrations

> Sync data from external systems into read-only tables

Integrations bring data from the systems your business already runs on, such as
an ERP, a CRM or a PostgreSQL database, into your Bijection deployment. The data
lands in ordinary tables that your [queries](/functions/query-functions) read
and subscribe to like any other table.

You describe the external system once, in TypeScript, inside your `bijection/`
directory. Bijection then runs the sync for you: it calls the provider on a
schedule, checks every response against the contract you declared, and
publishes each page of results into your tables in one transaction.

Here is the shape of it. An integration declares a `customers` collection that
is read every five minutes:

```ts bijection/crm.ts {6-8} theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { defineIntegration } from "bijection/server";
import { v } from "bijection/values";

export const crm = defineIntegration({
  collections: {
    customers: {
      schema: { external_id: v.string(), name: v.string() },
      sync: { every: { minutes: 5 }, async read(ctx, input) { … } },
      …
    },
  },
  …
});
```

Your schema binds a table to that collection with `.source(...)`:

```ts bijection/schema.ts {5} theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { defineSchema, defineTable } from "bijection/server";
import { crm } from "./crm";

export default defineSchema({
  customers: defineTable(crm.customers.schema).source(crm.customers),
});
```

And your app reads it like any other table:

```ts bijection/customers.ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { query } from "./_generated/server";

export const list = query({
  args: {},
  handler: async (ctx) => {
    return await ctx.db.query("customers").take(100);
  },
});
```

The provider's address and credentials are not part of this code. You connect
the integration to a real account per deployment, with the
[`bijection integration`](/integrations/cli) commands or the console.

## Concepts

* An **integration** groups what Bijection needs to know about one external
  system: the HTTP requests it may make, the collections it reads and the
  commands it can send.
* A **collection** is one kind of record the provider holds, such as customers
  or invoices. Each collection declares its schema, what the provider's
  responses prove about it, and its **sync**: how often it is read and how a
  response becomes records.
* A **synced table** is a table bound to a collection with `.source(...)`. Only
  the sync writes to it. Your mutations cannot.
* A **connection** installs an integration against one verified provider
  account in one deployment, with a private credential that your functions
  never see.

## Kinds of integrations

* [`defineIntegration`](/integrations/defining-integrations) declares an
  integration over a provider's HTTP API. Your code maps responses to records.
* [`definePostgresIntegration`](/integrations/postgres) replicates selected
  PostgreSQL tables through logical replication.
* [`defineMailIntegration`](/integrations/mail) reads an IMAP mailbox.

<Note>
  Sending changes back to a provider is done with integration commands, which
  your code requests as durable external calls. See
  [Operations](/operations/overview).
</Note>

<CardGroup cols={2}>
  <Card title="Defining integrations" href="/integrations/defining-integrations">
    Declare requests, collections, syncs and commands with `defineIntegration`.
  </Card>

  <Card title="Synced tables" href="/integrations/synced-tables">
    Bind tables to collections and read synced data in your functions.
  </Card>

  <Card title="Connecting and syncing" href="/integrations/connections">
    Provide credentials, verify the account, install sources and follow syncs.
  </Card>

  <Card title="PostgreSQL" href="/integrations/postgres">
    Replicate PostgreSQL tables with change data capture.
  </Card>

  <Card title="Mail" href="/integrations/mail">
    Sync messages, contents and folders from an IMAP mailbox.
  </Card>

  <Card title="Listeners and webhooks" href="/integrations/listeners">
    Refresh a collection as soon as the provider notifies you.
  </Card>

  <Card title="CLI reference" href="/integrations/cli">
    Every `bijection integration` subcommand.
  </Card>
</CardGroup>