Register and test connectors

Registration makes executable connector code available to a running tapstate server. Use this guide only when the server does not already have the connector artifact you need. Validation, registration, and connection testing answer different questions:

Offline validation can accept a resource when catalog-required fields are missing, connector-specific keys are unknown, or environment-variable values are unresolved. It never opens a network connection.

When registration is required

The standard self-hosted server image starts without connector JARs. The Cloud image stages a fixed connector set. Check the server's catalog before deciding whether registration is needed.

Whether you need to register a connector depends on how the server is deployed:

• Quickstart: no manual registration is required for MySQL, PostgreSQL, or MongoDB. The Quickstart downloads and registers those three artifacts automatically before applying the sample workspace. Oracle, SQL Server, and Db2 are not part of the demo.
• New server deployments: register each connector artifact before applying connections that reference it. Run connectors -o json to inspect the catalog; if a connector is absent, register it by published ID (register <id>) or upload a local JAR.
• Upgrades from prior versions:
  • Existing registered connectors persist in the backend store across server container upgrades. You do not need to re-register existing connectors after updating the server image.
  • A server upgrade does not install a newly needed connector. Register it before use.
  • Re-registering identical bytes is a safe no-op with newlyRegistered: false. For a different JAR, retain the old artifact, test the replacement, and plan affected pipeline restarts.
• Pre-seeded offline deployments: a server started with connector artifacts in its seed directory (TAPSTATE_CONNECTORS_SEED_DIR, default /var/lib/tapstate/connectors) scans and registers those artifacts automatically at startup.

After you connect and sign in, run connectors -o json to inspect the server's catalog. If the connector artifact you need is already available, skip the registration step and continue with Apply the connections.

Before you begin

• Bootstrap and authenticate.
• Create and validate the connection resources locally.

Official preview connector artifacts

The default accepted set contains 17 connector IDs. Registration acceptance does not certify every managed service or database version:

Artifacts are published through the floating connector preview release. The Oracle JAR bundles ojdbc8, orai18n, and xdb under the Oracle Free Use Terms; the SQL Server JAR bundles the Microsoft JDBC Driver under the MIT License. Their implementations are subject to the applicable commercial connector terms. The Db2 JAR bundles the IBM Data Server Driver under IBM's license terms; its connector implementation is also subject to the applicable commercial terms.

Db2 has no automated live-database release lane. The four external Atlas acceptance classes remain deferred, and Amazon RDS for MySQL has no completed real-service acceptance. Validate the exact artifact and service you intend to use. See the v0.7 release limits.

Current preview registration boundary

The public guides cover MySQL, PostgreSQL, Oracle, SQL Server, and the Db2 preview as sources, with MongoDB as the operational-state target.

In Cloud, serve.sync accepts only mongodb or mongodb-atlas targets. Self-hosted deployments use the registered catalog's sink capability, subject to source-only restrictions. Db2 and aws-rds-mysql are source-only in both modes. The server rejects either as a sync target with dsl.unsupported-target-connector, even when the aws-rds-mysql catalog entry reports sink capability. Allowing a connector does not certify its write behavior.

Registering an artifact with an unaccepted connector ID returns connector.not-official; the server does not register it. The same boundary applies when a server scans a connector seed directory.

In a cluster, register through one entry member. Concurrent registration of the same connector can produce connector.ambiguous-registration; avoiding concurrent seeding does not repair an already duplicated registry.

Register connector artifacts

Registering a connector requires an authenticated administrator session (login admin).

Register by published ID

You can download and register official connectors directly by ID without manually fetching JAR files:

tapstate -w work

connect http://127.0.0.1:8080
login admin
register mysql -o json
register postgres -o json
register mongodb -o json
register oracle -o json
register sqlserver -o json
register db2 -o json
connectors -o json

The CLI resolves and downloads the exact published artifact from the GitHub connectors-preview release, verifies its integrity, and uploads it to the server. Automatic download by ID supports mysql, postgres, mongodb, mongodb-atlas, aws-rds-mysql, oracle, sqlserver, and db2. Register only the artifacts you need. For an accepted ID without a download entry, pass a local JAR as described below. To route downloads through an internal HTTPS mirror, set the TAPSTATE_CONNECTORS_URL environment variable in your CLI environment.

The preview assets can change independently of a versioned server release. Use a current CLI with matching size and digest metadata. If integrity checks fail, do not disable verification or substitute an untrusted JAR.

Register from a local file or directory

You can also stage JAR files locally. When a path is passed to register, local files take precedence over published IDs:

register ../connector-artifacts/mysql-connector.jar -o json
register ../connector-artifacts/ -o json

A registration result includes the connector ID, content hash, PDK API version when declared, source, and newlyRegistered. Registering the identical artifact again is an idempotent no-op with newlyRegistered: false.

Passing a directory to register uploads every direct *.jar child. The batch fails if any artifact fails, so review every returned item.

Apply the connections

At the same prompt:

apply
get orders_source
get operational_state

apply reparses and validates the YAML on the server. It reports each artifact as CREATED, UPDATED, or UNCHANGED.

Environment-variable interpolation happens in the CLI before upload. Confirm the variables are set in the CLI process and avoid printing resolved secrets.

Test a connection

Run the connector's own test:

test orders_source -o json

The report contains:

• connectionId and connectorId;
• overall outcome: PASSED or FAILED;
• connector-supplied checks with PASSED, WARNING, or FAILED;
• optional message, reason, solution, and connector error code;
• testedAt as epoch milliseconds.

A warning does not fail the overall outcome. A failed check produces outcome: FAILED. If the connector throws instead of returning checks, tapstate returns a coded connector test failure.

The CLI waits for the server to finish connection testing and schema discovery; these requests no longer have a 30-second client read deadline. You can cancel the wait. Connector, proxy, and connection-establishment limits still apply.

Read the most recently stored report without testing again:

test-result orders_source -o json

In the current preview's interactive REPL, a failed line does not end the session. Inspect the report's outcome; do not treat the session's eventual exit as the connection-test result.

What to expect with a placeholder address

A resource using mysql.invalid, postgres.invalid, or mongo.invalid can pass offline validation because the YAML, mode, and provided field types are valid. After the connector is registered and the resource is applied, test should either:

• return a normal report with outcome: FAILED; or
• return a coded connector test error if the connector cannot produce a report.

It must not be documented as connected. The exact failed check and timeout are connector-controlled. Use placeholder addresses only to verify negative-path behavior, never as a substitute for a representative staging test.

Discover a source schema

After a source connection passes:

discover-schema orders_source -o json
schema orders_source -o json
schema orders_source orders -o json

discover-schema runs the connector and stores the latest model. schema reads that stored model without rediscovering it. A target-only connection is not a source-discovery witness.

Troubleshoot the sequence

Next steps

• MySQL connector
• PostgreSQL connector
• Db2 connector
• MongoDB connector
• Apply and run a pipeline