Secrets

TutorialApplies to: Unified engine deployments

Create a secret with SQL, inspect its metadata, and reference it from a credential. This page covers encrypted local values and every external secret provider available in Laminar. A secret holds a sensitive value, such as a password, token, key, or credential document. A credential tells Laminar how to use that value to authenticate. Secret providers supply values; credential providers use them.

Before you start

Copy examples into Workbench and run the statements in order in the same session. Stop if a statement fails and inspect its output. The examples use unused names beginning with learn_. Replace example values for your environment. Local values need the encrypted secret store and its persistent encryption key. External references need a provider alias already configured by the operator. SQL creates a local name or reference. It does not configure the provider, create remote secrets, or grant cloud permissions.

Choose a secret type

Type	Where the value lives	Version selection
Encrypted local value	Laminar’s encrypted secret store	Current local version; no history retrieval
AWS Secrets Manager	A secret name or ARN in AWS	Optional provider version ID
AWS Parameter Store	An SSM parameter path	Optional positive integer
Google Secret Manager	A secret in the configured project	Optional positive integer
Azure Key Vault	A secret in the configured vault	Optional provider version identifier
HashiCorp Vault	A path in the configured KV v2 mount	Optional positive integer
Environment variable	A variable mapped by the operator	Not supported
File	A file mapped by the operator	Not supported

An ARN is an AWS resource identifier. SSM is AWS Systems Manager. KV v2 is Vault’s versioned key-value store.

Encrypted local values

Use a local value when Laminar should keep the secret itself. This example uses demonstration text, not a working service token.

CREATE SECRET learn_token AS 'demo-token-not-for-authentication';
SHOW SECRETS;
DESCRIBE SECRET learn_token;

Expect learn_token with revision and version metadata. SHOW and DESCRIBE do not return its plaintext. Copy the name into a credential’s secret-reference field. Text values can also hold JSON documents, including saved AWS key bundles. The secret store treats the value as opaque data. The consuming credential validates the document format.

CREATE SECRET learn_aws_bundle AS
'{"aws_access_key_id":"<access-key-id>","aws_secret_access_key":"<secret-access-key>"}';

Replace the placeholders only when you intend to use real access. Do not save secret-value statements as reusable query documents. For certificates or binary documents, a mapped file or external provider may be a better source. CREATE SECRET IF NOT EXISTS keeps an existing value. It does not replace or rotate it.

External reference format

A reference has the form provider_alias://secret_name?version=value. The alias names a provider configured in this Laminar instance. The examples below use illustrative aliases such as learn_sm and learn_ssm; replace them with actual aliases. The provider alias and local secret name are different. For example, learn_catalog_token can be a stable local name whose source is learn_sm://retail/catalog-token. Only version is supported as a reference query parameter. Do not add a JSON-field selector. An unpinned reference follows the provider’s current or latest selection when resolved.

AWS Secrets Manager

Before running: configure an aws-secrets-manager provider alias and permission to read an existing secret. Set its optional Region or profile and supply an AWS SDK identity to the secret-service process.

CREATE SECRET learn_sm_token
USING 'learn_sm://retail/catalog-token';
DESCRIBE SECRET learn_sm_token;

The identifier can also be the secret’s full ARN. To select a particular value, copy its real VersionId from AWS:

CREATE SECRET learn_sm_pinned
USING 'learn_sm://retail/catalog-token?version=<aws-version-id>';

Use a version ID, not a version-stage label such as AWSCURRENT. The provider reads SecretString or decodes SecretBinary. A JSON SecretString stays a complete document; it is not reduced to one field.

AWS Parameter Store

Before running: configure an aws-ssm alias, its region or profile when required, and an AWS runtime identity that can read the parameter. SecureString parameters also need the required KMS decryption access. This provider uses the AWS SDK.

CREATE SECRET learn_ssm_token
USING 'learn_ssm:///retail/catalog-token';
CREATE SECRET learn_ssm_pinned
USING 'learn_ssm:///retail/catalog-token?version=3';
DESCRIBE SECRET learn_ssm_token;

The third slash preserves the leading slash in /retail/catalog-token. Replace version 3 with an existing positive integer version. Parameter labels are not version numbers.

Google Secret Manager

Before running: configure a gcp-secret-manager alias with a project and Application Default Credentials that can access the existing secret’s versions.

CREATE SECRET learn_google_token
USING 'learn_gsm://catalog-token';
CREATE SECRET learn_google_pinned
USING 'learn_gsm://catalog-token?version=2';
DESCRIBE SECRET learn_google_token;

The secret name is relative to the configured project. An omitted version selects latest. An explicit version must be a positive integer; replace 2 with an existing version. The provider decodes the returned payload bytes.

Azure Key Vault

Before running: configure an azure-key-vault alias with vault_url, its SDK authentication method, and permission to read the existing secret.

CREATE SECRET learn_azure_token
USING 'learn_kv://catalog-token';
CREATE SECRET learn_azure_pinned
USING 'learn_kv://catalog-token?version=<key-vault-version-id>';
DESCRIBE SECRET learn_azure_token;

Use the secret name within that vault. The version is Key Vault’s version identifier, not an integer sequence chosen for this example. An omitted version requests the current value.

HashiCorp Vault

Before running: configure a vault alias with a KV v2 mount, an API address, and an authorized token in the configured token_env variable. The configured mount is separate from the path in this SQL.

CREATE SECRET learn_vault_bundle
USING 'learn_vault://retail/aws-reader';
CREATE SECRET learn_vault_pinned
USING 'learn_vault://retail/aws-reader?version=4';
DESCRIBE SECRET learn_vault_bundle;

The provider returns the entire KV v2 data object as JSON. For an AWS saved credential, that object can contain aws_access_key_id and aws_secret_access_key. A bearer credential needs raw token text, so a Vault object such as {"token":"..."} is not a matching input. This integration does not select one field from that object. Use an existing positive integer version; deleted, destroyed, or expired data cannot supply a usable value.

Environment variables

Before running: configure an environment alias with a mapping such as secret name catalog_token to variable CATALOG_TOKEN. Set that variable on the host that resolves secrets.

CREATE SECRET learn_env_token
USING 'learn_env://catalog_token';
DESCRIBE SECRET learn_env_token;

catalog_token is the configured mapping key. This is not an arbitrary environment-variable lookup, and it does not read your browser or laptop environment. Do not add ?version=. Changing an environment variable elsewhere does not change the already running process’s environment.

Files

Before running: configure a file alias with a mapping such as catalog_token to /run/secrets/catalog-token. The path must be absolute, readable by the secrets host, and within the configured size limit.

CREATE SECRET learn_file_token
USING 'learn_files://catalog_token';
DESCRIBE SECRET learn_file_token;

The reference selects a mapping key, not an arbitrary file path. The provider supplies file contents as bytes. Keep their format suitable for the consumer, including any trailing newline. Version selection is unsupported.

Use a secret in a credential

For a real bearer token, create one of the references above or replace the demonstration local value. Then create a credential that refers to the local name:

CREATE CREDENTIAL learn_catalog_auth USING bearer
OPTIONS ('authentication' = 'saved')
SECRETS ('token' = 'learn_token');
DESCRIBE CREDENTIAL learn_catalog_auth;

You can also use an external reference directly, without a local alias:

CREATE CREDENTIAL learn_direct_auth USING bearer
OPTIONS ('authentication' = 'saved')
SECRETS ('token' = 'learn_sm://retail/catalog-token');

These statements save definitions. They do not prove that a real token can open a catalog. Attach the credential to a matching service and read a small known table. The Credentials page explains those steps.

Change one thing

Rotate the demonstration local secret and inspect its metadata again:

ALTER SECRET learn_token SET VALUE 'second-demo-token';
DESCRIBE SECRET learn_token;

Expect a changed revision and version, without plaintext output. A credential that uses learn_token keeps the same reference name. To move a local name to an external provider, use an existing provider and remote secret:

ALTER SECRET learn_token USING 'learn_sm://retail/catalog-token';
DESCRIBE SECRET learn_token;

Expect the source metadata to show that reference. This changes the local name’s source; it does not copy or change the remote secret. To move a pinned reference to another version, ALTER it with the new version. Removing ?version= returns it to the provider’s current selection. Local metadata exposes a current version identifier. A reference such as local://learn_token?version=<current-version> can require that exact version. After rotation, an older local version is rejected; this is not historical secret storage.

Check the result

For each example you chose, check the local name, source, and version with DESCRIBE. Use a compatible credential and a real consumer to prove remote resolution and access. SHOW and DESCRIBE alone inspect metadata, not acquired values or permissions.

Clean up

Remove consumers first, then lesson-only credentials, then their secrets. For the local example:

DROP CREDENTIAL IF EXISTS learn_catalog_auth;
DROP CREDENTIAL IF EXISTS learn_direct_auth;
DROP SECRET IF EXISTS learn_token;
DROP SECRET IF EXISTS learn_aws_bundle;

Use DROP SECRET IF EXISTS with the names of any other examples you created above. Dropping an external alias removes only the local registration. It does not delete the remote secret, environment variable, or file. Keep shared aliases and provider configuration in place.

Continue

Credentials covers every supported authentication method. See secret provider configuration for operator setup and external references for provider details.

Transformation Engine

Learn Laminar

Workloads

SQL reference

HTTP API

Recipes

Operations

Before you start

Choose a secret type

Encrypted local values

External reference format

AWS Secrets Manager

AWS Parameter Store

Google Secret Manager

Azure Key Vault

HashiCorp Vault

Environment variables

Files

Use a secret in a credential

Change one thing

Check the result

Clean up

Continue

​Before you start

​Choose a secret type

​Encrypted local values

​External reference format

​AWS Secrets Manager

​AWS Parameter Store

​Google Secret Manager

​Azure Key Vault

​HashiCorp Vault

​Environment variables

​Files

​Use a secret in a credential

​Change one thing

​Check the result

​Clean up

​Continue

Before you start

Choose a secret type

Encrypted local values

External reference format

AWS Secrets Manager

AWS Parameter Store

Google Secret Manager

Azure Key Vault

HashiCorp Vault

Environment variables

Files

Use a secret in a credential

Change one thing

Check the result

Clean up

Continue