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

• Quickstart: no action is required. The Quickstart downloads and registers the official MySQL, PostgreSQL, and MongoDB JARs before it applies the sample workspace.
• A server started with connector artifacts in its seed directory: no manual registration is required. The server registers those artifacts at startup.
• Any other connected server: register an artifact only when the connector you need is not already available to that server.

After you connect and sign in, run connectors -o json to inspect the server's catalog. If the MySQL, PostgreSQL, or MongoDB 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.

Get the current preview connector JARs

The current preview publishes the official MySQL, PostgreSQL, and MongoDB artifacts through the connector preview release. Download mysql-connector.jar, postgres-connector.jar, or mongodb-connector.jar to a local directory that the CLI can read. Do not use a catalog entry, roadmap page, or unlisted JAR as evidence that the current server will accept it.

Current preview registration boundary

The current preview documents MySQL and PostgreSQL as source artifacts and MongoDB as the operational-state target artifact. A connector catalog entry, a roadmap page, or a JAR by itself does not expand that public runtime boundary.

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

Register connector artifacts

The JAR does not need to live in the workspace. The CLI uploads it, and the server stores the accepted artifact. For example:

tapstate-work/
├── connector-artifacts/
│   ├── mysql-connector.jar
│   └── mongodb-connector.jar
└── work/

Start an authenticated REPL:

tapstate -w work

connect http://127.0.0.1:8080
login admin
register ../connector-artifacts/mysql-connector.jar -o json
register ../connector-artifacts/postgres-connector.jar -o json
register ../connector-artifacts/mongodb-connector.jar -o json
connectors -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.

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
• MongoDB connector
• Apply and run a pipeline