CREATE DATABASE SCOPED CREDENTIAL

CREATE DATABASE SCOPED CREDENTIAL#

Creates a database scoped credential in the current virtual database. A credential is a named record that holds an identity and, optionally, a secret; features that authenticate to an external resource reference it by name. A credential belongs to exactly one virtual database and its name is unique within that database.

Syntax#

CREATE DATABASE SCOPED CREDENTIAL credential name WITH IDENTITY = 'identity_name' , SECRET = 'secret'

Arguments#

credential_name

The name of the credential. Must be unique within the virtual database — creating a second credential with the same name raises an error. The name may be at most 128 characters and must not start with # (a leading # is reserved for system credentials).

IDENTITY = ‘identity_name‘

The identity presented when connecting to the external resource. Certain reserved values select an authentication mode: SHARED ACCESS SIGNATURE, MANAGED IDENTITY, USER IDENTITY, S3 ACCESS KEY. Any other value is treated as a basic user identity.

Note

Every mode above can be stored, but not every mode can yet authenticate a read: a storage read authenticates with SHARED ACCESS SIGNATURE or with a basic identity and password. See Authenticated reads from remote storage for what each mode does and which pairings are refused.

SECRET = ‘secret‘

The secret — for example a password, a SAS token, or an access key. Optional: identity-only credentials such as MANAGED IDENTITY omit it.

Remarks#

The secret is never stored or shown in clear text. It is protected at rest, and it is redacted wherever statement text is logged or traced (for example sys.qua_recent_statements). The sys.database_scoped_credentials catalog view exposes the identity metadata only — never the secret.

Two different virtual databases may each hold a credential of the same name; they are independent records.

A database scoped credential is contained by — and moves with — its virtual database. To hold one credential that every database on the server shares, create a server-level credential with CREATE CREDENTIAL instead.

IF NOT EXISTS is not supported.

How credentials are used#

A credential is resolved on every use — never cached — so creating, rotating or dropping one takes effect on the next statement that needs it.

External data sources. CREATE EXTERNAL DATA SOURCE ... CREDENTIAL = name resolves the name to a database scoped credential in the database where the reading statement runs — the SQL Server binding, unchanged. Only when no database scoped credential of that name exists does Querona fall back to a server-level credential of the same name, so a database scoped credential acts as a per-database override of a cluster-wide default. The name is validated when the data source is created or altered (ALTER EXTERNAL DATA SOURCE ... SET CREDENTIAL = name); a name that resolves at neither scope fails the statement with error 46516.

AI provider API keys. A database scoped credential named by an AI model’s endpoint URL supplies the API key for calls made from its database, overriding a server-level credential of the same name — for example, a tenant database on a shared cluster holding its own key. See qua_add_external_ai_model.

URL bulk reads never use database scoped credentials. A remote-URL OPENROWSET (BULK …) read authenticates through server-level credentials only, exactly as in SQL Server — see CREATE CREDENTIAL.

Authenticated reads work the same at either scope. How the secret is applied to the outgoing request, and which credential-and-location pairings are refused, are properties of the read rather than of the credential’s scope - see Authenticated reads from remote storage.

Using a credential requires no permission on the credential itself — matching SQL Server. Any principal allowed to run the consuming statement in this database uses the matching credential; the secret is never shown to that principal. The database boundary is the access boundary: a database scoped credential is reachable only from statements running in its own database.

Permissions#

Requires the connection-management permission (CreateConnection) on the server.

Examples#

  1. A basic identity and secret

CREATE DATABASE SCOPED CREDENTIAL AppCred
    WITH IDENTITY = 'reporting_user', SECRET = 'strong-secret';

  1. A shared access signature

CREATE DATABASE SCOPED CREDENTIAL BlobCred
    WITH IDENTITY = 'SHARED ACCESS SIGNATURE', SECRET = 'sv=2022-11-02&ss=b&srt=co&sp=r&sig=...';

  1. An identity-only credential (no secret)

CREATE DATABASE SCOPED CREDENTIAL MiCred
    WITH IDENTITY = 'MANAGED IDENTITY';

See also#