Skip to main content

Connect to the Database

Use DriverManager.getConnection(...) to open a JDBC connection:

Replace the endpoint with your database address. For an authenticated service, uncomment the credential settings and supply your own values from application configuration; do not hard-code real secrets.

String url = "jdbc:dbvisitor:milvus://127.0.0.1:19530/default";
java.util.Properties properties = new java.util.Properties();
properties.setProperty("connectTimeout", "5000");
// Enable these settings when authentication is required:
// properties.setProperty("user", "YOUR_USER");
// properties.setProperty("password", "YOUR_PASSWORD");
// properties.setProperty("token", "YOUR_TOKEN");
try (java.sql.Connection connection = java.sql.DriverManager.getConnection(url, properties)) {
    // Execute JDBC commands here; the connection is closed automatically.
}

Use one service endpoint per connection; the default port is 19530. SDK and Import REST share this endpoint. The /default path selects the database. For secure connections, see TLS and Certificates and Connect to Zilliz Cloud; do not assume plaintext configuration works for a TLS endpoint.

Configure Connection Parameters​

Set options with properties.setProperty("name", "value"), or append ?name=value&other=value to the URL (use & if a query string already exists). For the same key, URL values override Properties. The URL parser does not percent-decode values; put passwords, tokens and values containing & in Properties, and avoid logging credentials.

See Connection Parameters for names, defaults, units and restrictions. Only documented adapter parameters apply; they are not a pass-through for all vendor SDK options.

After connecting, see Execute Commands and Read Results.

Username and Password​

Properties props = new Properties();
props.setProperty("user", "root");
props.setProperty("password", "YOUR_PASSWORD");
props.setProperty("consistencyLevel", "Strong");
// Or use props.setProperty("token", "YOUR_TOKEN"); token takes precedence.
try (Connection conn = DriverManager.getConnection(
        "jdbc:dbvisitor:milvus://127.0.0.1:19530/default", props)) {
    // Use JDBC here.
}

TLS and Certificates​

For one-way TLS, provide a trusted CA, preferably through Properties. The JDBC URL format stays unchanged; the SDK uses gRPC TLS and Import uses HTTPS, on the same host and port:

Properties props = new Properties();
props.setProperty("secure", "true");
props.setProperty("caPemPath", "/absolute/path/ca.crt");
props.setProperty("serverName", "localhost");
try (Connection conn = DriverManager.getConnection(
        "jdbc:dbvisitor:milvus://127.0.0.1:19530/default", props)) {
    // SDK and Import REST share TLS verification.
}

For mutual TLS, also set clientPemPath=/absolute/path/client.crt and clientKeyPath=/absolute/path/client.key. SDK and REST both use the port specified in the JDBC URL. Do not combine caPemPath/serverPemPath or use a server private key as client identity. A supplied trust file replaces rather than augments default system trust.

The deployment must expose the required protocols. Milvus 2.6.2 natively shares a plaintext gRPC/REST port but requires separate internal listeners with native TLS. For full Import support over TLS, expose a unified ingress. For example, Envoy can provide ALPN-based passthrough for gRPC (HTTP/2) and REST (HTTP/1.1), without terminating TLS or bypassing Milvus mutual authentication. The driver never probes another port, downgrades to plaintext, or resubmits a failed job through another API. A direct gRPC-only TLS endpoint supports SDK operations but not REST Import. See the Milvus 2.6.2 listener implementation.

There is no trust-all, hostname-verification bypass, or automatic plaintext fallback. Untrusted certificates, identity mismatch and missing mutual-TLS credentials fail.

For server configuration, see Milvus TLS configuration.

Zilliz Cloud​

For Zilliz Cloud, use the public endpoint and token/API key from the console. Replace https:// with the JDBC prefix, retain the endpoint host and port, and set secure=true. Use 443 when the HTTPS endpoint omits a port; preserve an explicitly supplied port such as 19530. The JDBC default remains 19530; the driver does not infer Cloud type from a hostname:

Properties props = new Properties();
props.setProperty("secure", "true");
props.setProperty("token", "YOUR_ZILLIZ_API_KEY");
try (Connection conn = DriverManager.getConnection(
        "jdbc:dbvisitor:milvus://YOUR_CLUSTER_HOST:443/YOUR_DATABASE", props)) {
    // A publicly trusted certificate normally needs no PEM configuration.
}

Replace YOUR_DATABASE with the actual database name shown in the console, rather than assuming default. An explicit database keeps SQL, JDBC metadata and Import REST on the same database. Keep credentials out of URLs and logs.

Cloud uses the same JDBC driver for SQL execution, parameter binding and dbVisitor API calls. Also consider:

  • Management permissions: database creation, user management and role management depend on the deployment option and account permissions. Use an authorized database for ordinary reads and writes; see database creation API availability.
  • Quotas and rate limits: collection, partition and data operations are subject to Cloud quotas. Reduce request frequency when rate-limited instead of retrying in a tight loop; see Cloud limits for current values.
  • Network access: ensure that the endpoint is reachable and access policies allow the client. Import files must also be accessible to the cloud service.

For endpoint and authentication configuration, see the Zilliz Cloud connection guide.

Custom Clients​

To configure the SDK client yourself, implement CustomMilvus:

public class MyMilvusFactory implements net.hasor.dbvisitor.adapter.milvus.CustomMilvus {
    @Override
    public io.milvus.v2.client.MilvusClientV2 createMilvusClient(
            String jdbcUrl, java.util.Map<String, String> props) {
        return new io.milvus.v2.client.MilvusClientV2(
                io.milvus.v2.client.ConnectConfig.builder()
                        .uri("http://127.0.0.1:19530").dbName("default").build());
    }
}

Register with props.setProperty("customMilvus", MyMilvusFactory.class.getName()). The factory owns SDK configuration. It is called once per JDBC connection; commands share its returned V2 client, which is closed with the connection. The driver limits SDK-internal retries to one attempt to avoid multiplying maxRetry. Use conn.unwrap(MilvusClientV2.class) to access the client, but do not close or reconfigure it while JDBC still uses it.

Import REST uses the JDBC address and authentication/TLS properties, not the custom SDK client's internal configuration; custom factories must keep these properties consistent. Standard Cloud connections use the cluster endpoint and do not require an exposed management port.

Connection Pools​

With HikariCP, explicitly set connectionTestQuery to SHOW TABLES: the current shared driver does not implement Connection.isValid(). Do not use the unsupported SELECT 1. Keep auto-commit enabled and do not configure a transaction isolation level. Configure the URL, authentication, and TLS as for a normal JDBC connection, and close the pool when the application exits.