Connections and connectors

A connector defines how tapstate understands a system. A connection supplies the endpoint, credentials, scope, and role for one use of that connector.

In the current product path, MySQL, PostgreSQL, Oracle, SQL Server, and the Db2 preview are published sources and MongoDB is the published operational-state target. Broader connector metadata and roadmap pages do not expand that current path.

Connector definition     Connection resource         Pipeline reference
MySQL fields + modes      →  orders_mysql       ┐
PostgreSQL fields + modes →  shipments_postgres ├→ source: [orders_mysql, shipments_postgres]
                                                  └→ nest → view: order_state → managed MongoDB state

From a connection to current state

The main workflow is to prepare a source system, configure a connection, discover its tables, select the data for a pipeline, and verify the resulting state. Monitor both the initial load and subsequent changes.

Use the web application to explore the sources, pipelines, and observations available in your deployment. The underlying concepts stay the same when a developer or AI agent uses CLI, REST, or MCP. YAML examples in the references describe that shared resource model; installing the CLI is not a prerequisite for the Quickstart.

Connector definition

The connector definition answers questions that should stay consistent across environments:

• Which connector ID identifies the integration?
• Can it read, write, or do both?
• Which read modes are declared?
• Which configuration keys and value shapes are recognized?
• Which preparation steps and limitations apply to the external system?

Connectors must be registered with the server before connections can be applied. The standard self-hosted image starts with an empty catalog; the Cloud image stages a fixed connector set. Quickstart registers its three demonstration connectors. See Register and test connectors.

Registering identical artifact bytes is a no-op. A different JAR is a connector upgrade: test it and plan affected pipeline restarts. Registration checks the artifact's integrity, and native connectors reuse the artifact's class loader across tests, discovery, and pipeline operations.

The connector directory separates the current product roles from roadmap entries. A connector definition can validate known fields and modes; connectivity and permissions are checked when the connection is used.

One pipeline can reference multiple source connections, including connections that use different source connectors. Give each source its own endpoint, credentials, and selected tables. A transform such as nest can then assemble related rows from those sources; it does not create a cross-database SQL join.

Connection resource

A connection applies the connector definition to one endpoint and set of credentials. Give each connection a stable ID that describes its job rather than its password, host, or environment.

Typical source concerns include:

• endpoint and database scope;
• the account used for discovery and reads;
• selected tables or table-name patterns;
• Snapshot, CDC, Stream, or API read mode;
• source-side log retention and recovery position.

Typical target concerns include:

• the destination namespace;
• write and table-creation privileges;
• append or key-based update behavior;
• schema-change policy;
• conflict and retry behavior.

In these docs, Source and Target describe what the connection does in a data path. They are not literal database role names. Create database accounts that follow your organization's privilege model.

Source and target use

A source connection includes a read mode because tapstate must know how to obtain records. A target-only connection supplies destination configuration to a pipeline and does not need a source read mode.

Do not infer a target role from writable-looking fields or CDC support from a database family. Use the roles and modes listed on the connector page.

Scope connections narrowly

Prefer separate connections when any of these differ:

• environment or network boundary;
• credential owner or rotation policy;
• database, warehouse, or tenant;
• source versus target privileges;
• read mode or recovery policy.

This keeps reviews understandable and limits the impact of a leaked or over-privileged credential.

Next steps