Two weeks ago I graded SSMS Copilot's code completions and gave it a C. Inline suggestions were fast and schema-aware, but unpredictable — and one bad Tab away from deleting a million rows without a safety net. I should say, though, my code completions are improving! I think it's a matter of usage. Over time, the effectivity improves. 😆
But anyway... today's post. SSMS 22.3 was released on February 10 with something that may fix a problem that I've had with Copilot: it doesn't know my database. It could see the schema, tables, columns and data types — but it didn't know what any of it really meant. It didn't understand the context, and that increased my development time substantially.
Not anymore. SSMS 22.3 has a new feature called Database Instructions, which stores your business rules and context as metadata in the database. Think of it like 'living documentation' for Copilot that reduces the need for me to manually explain business logic to AI.
What Database Instructions Are
Database Instructions are extended properties with specific names that Copilot discovers at runtime. When you ask Copilot a question or generate T-SQL, it reads these properties and uses them as additional context — so its responses reflect your business rules rather than just your object names.
There are two types:
| Type |
Extended Property Name |
Scope |
| Instruction |
AGENTS.md |
Per object (table, column, proc, etc.) |
| Constitution |
CONSTITUTION.md |
Database-wide, highest precedence |
No additional configuration required. No other settings to enable. If the extended property exists and you're running SSMS 22.3 or later with GitHub Copilot, it works.
Prerequisites
SSMS 22.3 or later with the AI Assistance workload installed, and a GitHub account with Copilot access. The free tier gives you 2,000 completions per month. If you're still on 22.2, you'll need to upgrade to 22.3. Check Help\About to be sure.
The Demo
I built a small set of tables with intentionally terrible column names — not intuitive at all. The kind of schema you inherit from a developer who was in a hurry fifteen years ago and is long-gone.
CREATE TABLE dbo.Apts (
AptID INT IDENTITY(1,1) PRIMARY KEY,
PtID INT NOT NULL,
PrvID INT NOT NULL,
DtCrtd DATETIME NOT NULL DEFAULT GETDATE(),
DtSched DATETIME NOT NULL,
Sts TINYINT NOT NULL DEFAULT 1,
Amt DECIMAL(10,2) NULL
);
CREATE TABLE dbo.Pts (
PtID INT IDENTITY(1,1) PRIMARY KEY,
FNm VARCHAR(50) NOT NULL,
LNm VARCHAR(50) NOT NULL,
DOB DATE NULL,
Actv BIT NOT NULL DEFAULT 1
);
CREATE TABLE dbo.Prvs (
PrvID INT IDENTITY(1,1) PRIMARY KEY,
PNm VARCHAR(100) NOT NULL,
Spec VARCHAR(50) NULL,
Actv BIT NOT NULL DEFAULT 1
);
GO
INSERT INTO dbo.Pts (FNm, LNm, DOB) VALUES
('John', 'Smith', '1985-03-15'),
('Sarah', 'Johnson', '1992-07-22'),
('Mike', 'Williams', '1978-11-03');
INSERT INTO dbo.Prvs (PNm, Spec) VALUES
('Dr. Rebecca Miller', 'Cardiology'),
('Dr. James Chen', 'Internal Medicine');
INSERT INTO dbo.Apts (PtID, PrvID, DtSched, Sts, Amt) VALUES
(1, 1, '2026-02-20 09:00', 2, 250.00),
(1, 1, '2026-02-25 10:00', 1, 250.00),
(2, 2, '2026-02-21 14:00', 2, 175.00),
(2, 2, '2026-02-26 11:00', 5, 175.00),
(3, 1, '2026-02-19 08:00', 99, NULL),
(3, 2, '2026-02-27 15:00', 1, 200.00);
GO
Copilot Already Reads the Schema
Credit where it's due. I connected to the database in SSMS 22.3, opened the Copilot chat window, and asked: 'How many appointments were completed last week?'
It thought for a moment and came back with:
2 appointments were completed last week.
These were:
John Smith with Dr. Rebecca Miller on 2/20
Sarah Johnson with Dr. James Chen on 2/21
Correct. It figured out that Sts = 2 means completed, joined Apts to Pts and Prvs, and returned the right answer from abbreviated column names. Copilot's schema awareness out-of-the-box is genuinely impressive — much better than I expected from a table called Apts with a column called Sts.
So why do we need Database Instructions at all?
Because schema awareness gets you the columns, but business awareness gets you the rules. Copilot correctly identified 'completed' from the data patterns, but it couldn't possibly know that revenue in this dataset means SUM(Amt) for completed appointments only, that Actv = 0 means the provider left the practice and their data should be treated as historical, or that the fiscal year starts in July... The business rules that live only in people's heads — until now.
Adding Instructions
Database instructions are added with sp_addextendedproperty. The extended property name must be exactly AGENTS.md. Only one AGENTS.md property can exist per object.
Start with a constitution — the database-wide rules that apply to every Copilot interaction:
EXECUTE sp_addextendedproperty
@name = N'CONSTITUTION.md',
@value = N'This is a medical appointment scheduling database.
Tables use abbreviated names: Apts = Appointments, Pts = Patients, Prvs = Providers.
All monetary values are in USD.
Revenue is defined as SUM(Amt) for completed appointments only (Sts = 2).
Cancelled appointments (Sts = 99) should be excluded from revenue calculations.
Fiscal year begins July 1.
Queries should never use SELECT *.
Always use explicit column aliases for readability.';
Then add table-level instructions for object-specific context:
EXECUTE sp_addextendedproperty
@name = N'AGENTS.md',
@value = N'The Apts table stores patient appointment records.
Column mappings: AptID = Appointment ID, PtID = Patient ID, PrvID = Provider ID,
DtCrtd = Date Created, DtSched = Date Scheduled, Sts = Status, Amt = Appointment Amount.
Status codes: 1 = Scheduled, 2 = Completed, 5 = Confirmed, 99 = Cancelled.
An appointment is only billable when Sts = 2 (Completed).',
@level0type = N'SCHEMA', @level0name = N'dbo',
@level1type = N'TABLE', @level1name = N'Apts';
GO
EXECUTE sp_addextendedproperty
@name = N'AGENTS.md',
@value = N'The Pts table stores patient demographics.
Column mappings: PtID = Patient ID, FNm = First Name, LNm = Last Name,
DOB = Date of Birth, Actv = Active (1 = active patient, 0 = inactive).',
@level0type = N'SCHEMA', @level0name = N'dbo',
@level1type = N'TABLE', @level1name = N'Pts';
GO
EXECUTE sp_addextendedproperty
@name = N'AGENTS.md',
@value = N'The Prvs table stores medical provider information.
Column mappings: PrvID = Provider ID, PNm = Provider Name,
Spec = Specialty, Actv = Active (1 = active provider, 0 = inactive).
Providers with Actv = 0 have left the practice. Their historical data
should be included in past reports but excluded from scheduling queries.',
@level0type = N'SCHEMA', @level0name = N'dbo',
@level1type = N'TABLE', @level1name = N'Prvs';
GO
No SSMS settings to change. No restart. The instructions are in the database now, and Copilot reads them on the next interaction.
Where This Pays Off
The simple questions — 'how many completed appointments' — Copilot already handles well on its own. The Database Instructions earn their keep on the questions where business context matters:
'Show me revenue by provider for this fiscal year.' Without the constitution, Copilot has to guess what 'revenue' means and when your fiscal year starts. With it, the query filters to Sts = 2, excludes cancelled appointments, and uses July 1 as the fiscal year boundary — all without you restating the rules.
Copilot returns this:
Then I asked Copilot to 'Show me the query used to get this information' because I trust nothing easily... You can see the rules are there!
Remember, the Database Instructions don't replace Copilot's schema intelligence — they build on top of it. Copilot still reads the tables, columns, and relationships, but now the instructions add the business layer that the schema cannot express by itself.
Managing Instructions
Update with sp_updateextendedproperty. Remove with sp_dropextendedproperty:
EXECUTE sp_updateextendedproperty
@name = N'AGENTS.md',
@value = N'Updated instruction text here.',
@level0type = N'SCHEMA', @level0name = N'dbo',
@level1type = N'TABLE', @level1name = N'Apts';
GO
EXECUTE sp_dropextendedproperty
@name = N'AGENTS.md',
@level0type = N'SCHEMA', @level0name = N'dbo',
@level1type = N'TABLE', @level1name = N'Apts';
GO
Can't remember what's in there? You can ask Copilot directly: 'Show me the database instructions for this database':
Things to Know
One AGENTS.md per object. You cannot add two AGENTS.md extended properties to the same table. All context for a single object goes into one property value.
Constitution is database-wide. A CONSTITUTION.md property applies to every Copilot interaction in that database, for every user. Write it like policy, not like a suggestion.
Third-party extension conflicts. SSMS 22.3 updated Microsoft.Data.SqlClient and SMO under the hood. Erin Stellato's announcement called out that some third-party extensions may break. If you run SQL Prompt or similar tools, check compatibility before upgrading. The Visual Studio Installer lets you roll back to 22.2 if needed.
Instructions travel with the database. Extended properties survive backup, restore, and migration. This is documentation that doesn't live in a wiki nobody reads — it lives where the data lives.
Don't Forget
Write your instructions like you'd write a good AI prompt — specific, unambiguous, and complete. 'Revenue excludes cancelled appointments' is useful. 'Be careful with revenue' is not. The more precise the instruction, the more precise Copilot's output.
Bottom Line
Copilot's schema awareness is already solid — it figured out abbreviated table and column names, joined correctly on foreign keys, and answered a plain-English question accurately from a schema that would confuse most humans. Database instructions take it further by adding the business rules that schema alone cannot express: what 'revenue' means, which status codes to exclude and when the fiscal year starts.
The feature uses extended properties — nothing new to SQL Server — with two specific names: AGENTS.md for object-level context and CONSTITUTION.md for database-wide policy. No other configurations or settings. Just metadata that Copilot reads automatically.
If you've been meaning to document that vendor schema with the three-letter column names for the last decade, this is your excuse. The Database Instructions help Copilot today and the next DBA who inherits the database tomorrow.
More to Read
Microsoft: Database Instructions for GitHub Copilot in SSMS
Microsoft: SSMS 22 Release Notes
Microsoft: Get Started with GitHub Copilot in SSMS
sqlfingers: SSMS Copilot Code Completions. Some of it Was Brilliant.
