Connecting to SQL Server

Prerequisites

PuppyGraph version 0.95 or higher.
The SQL Server instance is accessible over the network from the PuppyGraph instance.

Overview

PuppyGraph supports connecting to SQL Server with different authentication methods:

Connecting with username and password
Connecting with Azure AD Service Principal
Connecting with Kerberos / Windows Authentication (on-premises Active Directory, requires PuppyGraph 1.0 or higher)

Connecting with username and password

Configuration	Explanation
Username	The username used to connect to the SQL Server database.
Password	The password associated with the database user account.
JDBC URI	A JDBC-compatible connection string for the SQL Server instance. See Building the Connection URL for syntax details.
JDBC Driver Class	The class name of the SQL Server JDBC driver. Default: `com.microsoft.sqlserver.jdbc.SQLServerDriver`.
JDBC Driver URL	The URL of the SQL Server JDBC driver. Choose the version compatible with your SQL Server instance.

Connecting with Kerberos / Windows Authentication

Kerberos / Windows Authentication lets PuppyGraph connect to on-premises SQL Server instances joined to an Active Directory domain. No password is stored in the catalog configuration or transmitted over the wire. Authentication is handled entirely by a service principal and keytab mounted into the PuppyGraph container.

Additional prerequisites:

PuppyGraph version 1.0 or higher.
A Kerberos-enabled Active Directory domain with a service principal and keytab for PuppyGraph.
SQL Server configured to accept Windows Authentication (Integrated Security).

Operator setup

Three files must be present inside the PuppyGraph container before the catalog is created. These are typically mounted via Kubernetes ConfigMaps and Secrets.

File	Typical path	What it contains
Kerberos config	`/etc/puppygraph/krb5.conf`	Realm and KDC settings
Keytab	`/secrets/puppygraph.keytab`	Service principal credentials
JAAS config	`/etc/puppygraph/jaas.conf`	Login module configuration pointing to the keytab

Three environment variables wire the mounted files into the JVM:

Environment variable	Effect
`AUTHENTICATION_KERBEROS_CONFIGPATH`	Sets `-Djava.security.krb5.conf`
`AUTHENTICATION_KERBEROS_JAASCONFIGPATH`	Sets `-Djava.security.auth.login.config`
`AUTHENTICATION_KERBEROS_DEBUG` (optional)	Set to `true` to enable Kerberos debug logging (`-Dsun.security.krb5.debug=true`). Only set this when troubleshooting authentication issues.

Sample krb5.conf:

[libdefaults]
    default_realm = EXAMPLE.COM
    dns_lookup_kdc = false
    dns_lookup_realm = false
    rdns = false
    udp_preference_limit = 1

[realms]
    EXAMPLE.COM = {
        kdc = kdc.example.com
        admin_server = kdc.example.com
    }

[domain_realm]
    .example.com = EXAMPLE.COM
    example.com = EXAMPLE.COM

Sample jaas.conf:

SQLJDBCDriver {
  com.sun.security.auth.module.Krb5LoginModule required
  useKeyTab=true
  keyTab="/secrets/puppygraph.keytab"
  principal="puppygraph_reader@EXAMPLE.COM"
  storeKey=true
  refreshKrb5Config=true
  doNotPrompt=true;
};

Configuration

Configuration	Explanation
SQL Server Auth Type	Kerberos / Windows Authentication (on-prem AD)
JDBC URI	A JDBC connection string for the SQL Server instance, for example: `jdbc:sqlserver://dbhost.example.com:1433;databaseName=mydb;encrypt=true;`. PuppyGraph automatically appends `integratedSecurity=true;authenticationScheme=JavaKerberos;`. Do not include these manually.
Server SPN Override	The Service Principal Name registered in Active Directory for this SQL Server instance. Providing this value is recommended. When connecting to multiple SQL Server instances, each instance must have a distinct SPN configured, making this field mandatory.
JDBC Driver Class	The class name of the SQL Server JDBC driver. Default: `com.microsoft.sqlserver.jdbc.SQLServerDriver`.
JDBC Driver URL	The URL of the SQL Server JDBC driver. Choose the version compatible with your SQL Server instance.

Username and password are not required and will be ignored when Kerberos authentication is selected.

Data Type Mapping

SQL Server Type	PuppyGraph Type	Description
`BIT`	`Boolean`	True or false
`TINYINT`, `SMALLINT`	`Short`	16-bit signed integer. `TINYINT` is unsigned in SQL Server, so it is widened
`INT`	`Int`	32-bit signed integer
`BIGINT`	`Long`	64-bit signed integer
`REAL`, `FLOAT(n)` with n up to 24	`Float`	32-bit IEEE 754 floating point
`FLOAT`, `FLOAT(n)` with n from 25 to 53	`Double`	64-bit IEEE 754 floating point. A bare `FLOAT` is `FLOAT(53)`
`DECIMAL(P, S)`, `NUMERIC(P, S)`, `MONEY`, `SMALLMONEY`	`Decimal(P, S)`	Fixed-point decimal; precision P, scale S
`CHAR`, `NCHAR`, `VARCHAR`, `NVARCHAR`, `TEXT`, `NTEXT`	`String`	Character strings
`UNIQUEIDENTIFIER`	`String`	GUID in its text form
`XML`	`String`	XML document as text
`DATETIMEOFFSET`	`String`	Date, time and offset as text
`BINARY`, `VARBINARY`, `IMAGE`	`Binary`	Byte sequence
`ROWVERSION`, `TIMESTAMP`	`Binary`	8-byte row version. `TIMESTAMP` is the deprecated synonym for `ROWVERSION`, not a date and time
`GEOGRAPHY`, `GEOMETRY`, `HIERARCHYID`	`Binary`	Value in SQL Server's internal binary serialization
`DATE`	`Date`	Calendar date without time or timezone
`DATETIME`, `DATETIME2`, `SMALLDATETIME`	`DateTime`	Date and time

JSON stored in NVARCHAR or VARCHAR columns is read as String. For the native json type of SQL Server 2025, the bundled SQL Server JDBC driver (12.8.2) does not list these columns, so they do not appear in PuppyGraph. With a driver that lists them, they map to String.
Columns of any other type, such as TIME or SQL_VARIANT, are not supported. They are listed in Schema Builder, but you cannot add them to a node or edge as attributes.

If you need a data type that is not supported, or one that is not listed here, contact us.

Demo

See Querying SQL Server Data as a Graph for a complete demo. The demo includes setting up the connection to a SQL Server instance.