feat: use configured DNS name to lookup instance IP address

If a custom DNS name is provided, resolve it to an IP address (A record) and use it for the connection.
Fallback to metadata IP if resolution fails.

Fixes #513

Author: hessjcg

src/cloud-sql-instance.ts

@@ -18,6 +18,7 @@ import {
   isSameInstance,
   resolveInstanceName,
 } from './parse-instance-connection-name';
+import {resolveARecord} from './dns-lookup';
 import {InstanceMetadata} from './sqladmin-fetcher';
 import {generateKeys} from './crypto';
 import {RSAKeys} from './rsa-keys';
@@ -69,12 +70,16 @@ export class CloudSQLInstance {
   static async getCloudSQLInstance(
     options: CloudSQLInstanceOptions
   ): Promise<CloudSQLInstance> {
+    const instanceInfo = await resolveInstanceName(
+      options.instanceConnectionName,
+      options.domainName
+    );
+    if (options.domainName && !instanceInfo.domainName) {
+      instanceInfo.domainName = options.domainName;
+    }
     const instance = new CloudSQLInstance({
       options: options,
-      instanceInfo: await resolveInstanceName(
-        options.instanceConnectionName,
-        options.domainName
-      ),
+      instanceInfo,
     });
     await instance.refresh();
     return instance;
@@ -266,7 +271,20 @@ export class CloudSQLInstance {
       rsaKeys.publicKey,
       this.authType
     );
-    const host = selectIpAddress(metadata.ipAddresses, this.ipType);
+    let host;
+    if (this.instanceInfo && this.instanceInfo.domainName) {
+      try {
+        const ips = await resolveARecord(this.instanceInfo.domainName);
+        if (ips && ips.length > 0) {
+          host = ips[0];
+        }
+      } catch (e) {
+        // ignore error, fallback to metadata IP
+      }
+    }
+    if (!host) {
+      host = selectIpAddress(metadata.ipAddresses, this.ipType);
+    }
     const privateKey = rsaKeys.privateKey;
     const serverCaCert = metadata.serverCaCert;
     this.serverCaMode = metadata.serverCaMode;

src/dns-lookup.ts

@@ -48,3 +48,15 @@ export async function resolveTxtRecord(name: string): Promise<string> {
     });
   });
 }
+
+export async function resolveARecord(name: string): Promise<string[]> {
+  return new Promise((resolve, reject) => {
+    dns.resolve4(name, (err, addresses) => {
+      if (err) {
+        reject(err);
+        return;
+      }
+      resolve(addresses);
+    });
+  });
+}

test/cloud-sql-instance-dns.ts

@@ -0,0 +1,144 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import t from 'tap';
+import {IpAddressTypes} from '../src/ip-addresses';
+import {AuthTypes} from '../src/auth-types';
+import {CA_CERT, CLIENT_CERT, CLIENT_KEY} from './fixtures/certs';
+import {setupCredentials} from './fixtures/setup-credentials';
+
+t.test('CloudSQLInstance DNS Lookup', async t => {
+  setupCredentials(t);
+
+  const fetcher = {
+    async getInstanceMetadata() {
+      return {
+        ipAddresses: {
+          public: '127.0.0.1',
+        },
+        serverCaCert: {
+          cert: CA_CERT,
+          expirationTime: '2033-01-06T10:00:00.232Z',
+        },
+      };
+    },
+    async getEphemeralCertificate() {
+      return {
+        cert: CLIENT_CERT,
+        expirationTime: '2033-01-06T10:00:00.232Z',
+      };
+    },
+  };
+
+  let resolveARecordMock = async (name: string): Promise<string[]> => {
+    return [];
+  };
+
+  const {CloudSQLInstance} = t.mockRequire('../src/cloud-sql-instance', {
+    '../src/crypto': {
+      generateKeys: async () => ({
+        publicKey: '-----BEGIN PUBLIC KEY-----',
+        privateKey: CLIENT_KEY,
+      }),
+    },
+    '../src/time': {
+      getRefreshInterval() {
+        return 50;
+      },
+      isExpirationTimeValid() {
+        return true;
+      },
+    },
+    '../src/dns-lookup': {
+      resolveARecord: async (name: string) => resolveARecordMock(name),
+      resolveInstanceName: async () => ({
+        projectId: 'my-project',
+        regionId: 'us-east1',
+        instanceId: 'my-instance',
+        domainName: 'example.com',
+      }),
+    },
+  });
+
+  t.test('should use resolved IP when domainName is present', async t => {
+    const expectedIp = '10.0.0.1';
+    resolveARecordMock = async (name: string) => {
+      t.equal(name, 'example.com');
+      return [expectedIp];
+    };
+
+    const instance = await CloudSQLInstance.getCloudSQLInstance({
+      ipType: IpAddressTypes.PUBLIC,
+      authType: AuthTypes.PASSWORD,
+      instanceConnectionName: 'my-project:us-east1:my-instance',
+      domainName: 'example.com',
+      sqlAdminFetcher: fetcher,
+    });
+    t.after(() => instance.close());
+
+    t.equal(instance.host, expectedIp, 'Host should match resolved IP');
+  });
+
+  t.test('should fallback to metadata IP when resolution fails', async t => {
+    resolveARecordMock = async (name: string) => {
+      throw new Error('DNS Error');
+    };
+
+    const instance = await CloudSQLInstance.getCloudSQLInstance({
+      ipType: IpAddressTypes.PUBLIC,
+      authType: AuthTypes.PASSWORD,
+      instanceConnectionName: 'my-project:us-east1:my-instance',
+      domainName: 'example.com',
+      sqlAdminFetcher: fetcher,
+    });
+    t.after(() => instance.close());
+
+    t.equal(instance.host, '127.0.0.1', 'Host should fallback to metadata IP');
+  });
+
+  t.test('should fallback to metadata IP when resolution returns empty', async t => {
+    resolveARecordMock = async (name: string) => {
+      return [];
+    };
+
+    const instance = await CloudSQLInstance.getCloudSQLInstance({
+      ipType: IpAddressTypes.PUBLIC,
+      authType: AuthTypes.PASSWORD,
+      instanceConnectionName: 'my-project:us-east1:my-instance',
+      domainName: 'example.com',
+      sqlAdminFetcher: fetcher,
+    });
+    t.after(() => instance.close());
+
+    t.equal(instance.host, '127.0.0.1', 'Host should fallback to metadata IP');
+  });
+
+  t.test('should use metadata IP when domainName is not present', async t => {
+    // resolveARecord should not be called, but if it is, ensure it doesn't return the expected IP
+    resolveARecordMock = async (name: string) => {
+      t.fail('Should not attempt to resolve DNS');
+      return ['10.0.0.1'];
+    };
+
+    const instance = await CloudSQLInstance.getCloudSQLInstance({
+      ipType: IpAddressTypes.PUBLIC,
+      authType: AuthTypes.PASSWORD,
+      instanceConnectionName: 'my-project:us-east1:my-instance',
+      sqlAdminFetcher: fetcher,
+    });
+    t.after(() => instance.close());
+
+    t.equal(instance.host, '127.0.0.1', 'Host should use metadata IP');
+  });
+});

test/dns-lookup.ts

@@ -15,7 +15,7 @@
 import t from 'tap';
 
 t.test('lookup dns with mock responses', async t => {
-  const {resolveTxtRecord} = t.mockRequire('../src/dns-lookup.ts', {
+  const {resolveTxtRecord, resolveARecord} = t.mockRequire('../src/dns-lookup.ts', {
     'node:dns': {
       resolveTxt: (name, callback) => {
         switch (name) {
@@ -39,6 +39,15 @@ t.test('lookup dns with mock responses', async t => {
             return;
         }
       },
+      resolve4: (name, callback) => {
+        if (name === 'example.com') {
+          callback(null, ['10.0.0.1']);
+        } else if (name === 'empty.example.com') {
+          callback(null, []);
+        } else {
+          callback(new Error('not found'));
+        }
+      },
     },
   });
 
@@ -67,6 +76,11 @@ t.test('lookup dns with mock responses', async t => {
     {code: 'EDOMAINNAMELOOKUPFAILED'},
     'should throw type error if an extra item is provided'
   );
+
+  // resolveARecord tests
+  t.same(await resolveARecord('example.com'), ['10.0.0.1'], 'should resolve A record');
+  t.same(await resolveARecord('empty.example.com'), [], 'should return empty array');
+  t.rejects(async () => await resolveARecord('not-found'), /not found/, 'should reject on error');
 });
 
 t.test('lookup dns with real responses', async t => {