SQL MCP Server'da veri işleme dili (DML) araçları

Önemli

SQL Model Bağlam Protokolü (MCP) Sunucusu önizleme aşamasındadır ve bu belgeler ve altyapı uygulaması değişebilir. Veri API oluşturucusu sürüm 1.7 önizleme aşamasındayken, MCP özellikleri henüz etikete dahil 1.7.83-rc edilmediğinden yayın öncesi sürümü açıkça kullanmanız gerekir (örneğin, :latest).

SQL MCP Server altı Veri İşleme Dili (DML) aracını yapay zeka aracılarına sunar. Bu araçlar, kayıt oluşturma, okuma, güncelleştirme ve silme ile saklı yordamları yürütme gibi veritabanı işlemleri için yazılan bir CRUD yüzeyi sağlar. Tüm araçlar rol tabanlı erişim denetimine (RBAC), varlık izinlerine ve yapılandırmanızda tanımlanan ilkelere uyar.

DML araçları nedir?

DML (Veri İşleme Dili) araçları veri işlemlerini işler: kayıtları oluşturma, okuma, güncelleştirme ve silme, ayrıca saklı yordamları yürütme. Şemayı değiştiren DDL'nin (Veri Tanım Dili) aksine, DML yalnızca mevcut tablo ve görünümlerdeki veri düzleminde çalışır.

Altı DML aracı şunlardır:

• describe_entities - Kullanılabilir varlıkları ve işlemleri bulur
• create_record - Yeni satır ekler
• read_records - Sorgu tabloları ve görünümleri
• update_record - Varolan satırları değiştirir
• delete_record - Satırları kaldırır
• execute_entity - Saklı yordamları çalıştırır

DML araçları genel olarak ve bir varlık için etkinleştirildiğinde, SQL MCP Server bunları MCP protokolü aracılığıyla kullanıma sunar. Aracılar hiçbir zaman veritabanı şemanızla doğrudan etkileşim kurmaz; Veri API'sinin oluşturucu soyutlama katmanı üzerinden çalışır.

Araçlar

list_tools yanıtı

Bir aracı çağırdığında list_tools, SQL MCP Server şunu döndürür:

{
  "tools": [
    { "name": "describe_entities" },
    { "name": "create_record" },
    { "name": "read_records" },
    { "name": "update_record" },
    { "name": "delete_record" },
    { "name": "execute_entity" }
  ]
}

varlıkları tanımla

Geçerli role uygun varlıkları geri döndürür. Her girdi alan adlarını, veri türlerini, birincil anahtarları ve izin verilen işlemleri içerir. Bu araç veritabanını sorgulamaz. Bunun yerine, yapılandırma dosyanızdan oluşturulan bellek içi yapılandırmadan okur.

{
  "entities": [
    {
      "name": "Products",
      "description": "Product catalog with pricing and inventory",
      "fields": [
        {
          "name": "ProductId",
          "type": "int",
          "isKey": true,
          "description": "Unique product identifier"
        },
        {
          "name": "ProductName",
          "type": "string",
          "description": "Display name of the product"
        },
        {
          "name": "Price",
          "type": "decimal",
          "description": "Retail price in USD"
        }
      ],
      "operations": [
        "read_records",
        "update_record"
      ]
    }
  ]
}

Uyarı

CRUD ve yürütme DML araçlarından herhangi biri tarafından kullanılan varlık seçenekleri doğrudan describe_entities öğesinden gelir. Her araca bağlı iç anlamsal açıklama, bu iki adımlı akışı sağlar.

kayıt oluştur

Tabloda yeni bir satır oluşturur. Geçerli rol için birimde oluşturma izni gerektirir. Araç girişi varlık şemasına göre doğrular, alan düzeyi izinleri zorlar, oluşturma ilkeleri uygular ve oluşturulan kaydı oluşturulan tüm değerlerle döndürür.

kayıtları_oku

Bir tablo veya görünümü sorgular. Filtreleme, sıralama, sayfalandırma ve alan seçimini destekler. Araç yapılandırılmış parametrelerden deterministik SQL oluşturur, okuma izinleri ve alan projeksiyonları uygular ve satır düzeyi güvenlik ilkelerini uygular.

read_records sonuçları, Veri API'si oluşturucusundan gelen önbelleğe alma sistemi kullanılarak otomatik olarak önbelleğe alınır. Veritabanı yükünü azaltmak için önbellek yaşam süresini (TTL) genel olarak veya varlık başına yapılandırabilirsiniz.

kayıt_güncelle

Var olan bir satırı değiştirir. Güncellenecek birincil anahtar ve alanlar gereklidir. Araç birincil anahtarın mevcut olduğunu doğrular, güncelleştirme izinlerini ve ilkelerini zorlar ve yalnızca geçerli rolün değiştirebileceği alanları güncelleştirir.

kayıt_sil

Varolan bir satırı kaldırır. Ana anahtarı gerektirir. Araç birincil anahtarın mevcut olduğunu doğrular, silme izinlerini ve ilkelerini zorlar ve işlem desteğiyle güvenli silme gerçekleştirir.

Uyarı

Bazı üretim senaryoları, modelleri genel olarak kısıtlamak için bu aracı genel olarak devre dışı bırakır.

execute_entity

Bir saklı yordam çalıştırır. Giriş parametrelerini ve çıkış sonuçlarını destekler. Araç giriş parametrelerini yordam imzasına karşı doğrular, yürütme izinlerini zorlar ve parametreleri güvenli bir şekilde geçirir.

Çalışma zamanı yapılandırması

DML araçlarını, çalışma dab-config.jsonzamanı bölümünde genel olarak yapılandırın:

{
  "runtime": {
    "mcp": {
      "enabled": true,
      "path": "/mcp",
      "dml-tools": {
        "describe-entities": true,
        "create-record": true,
        "read-records": true,
        "update-record": true,
        "delete-record": true,
        "execute-entity": true
      }
    }
  }
}

CLI'yi kullanma

Veri API'si oluşturucu CLI'sını kullanarak özellikleri ayrı ayrı ayarlayın:

dab configure --runtime.mcp.enabled true
dab configure --runtime.mcp.path "/mcp"
dab configure --runtime.mcp.dml-tools.describe-entities true
dab configure --runtime.mcp.dml-tools.create-record true
dab configure --runtime.mcp.dml-tools.read-records true
dab configure --runtime.mcp.dml-tools.update-record true
dab configure --runtime.mcp.dml-tools.delete-record true
dab configure --runtime.mcp.dml-tools.execute-entity true

Araçları devre dışı bırakma

Bir aracı çalışma zamanı düzeyinde devre dışı bırakırsanız, varlık izinlerinden veya rol yapılandırmasından bağımsız olarak aracılara hiçbir zaman gösterilmez. Bu ayar, katı operasyonel sınırlara ihtiyacınız olduğunda kullanışlıdır.

Yaygın senaryolar

• Üretimde veri kaybını önlemek için devre dışı bırakma delete-record
• "create-record'yi salt okunur raporlama uç noktaları için devre dışı bırak"
• execute-entity saklı yordamlar kullanılmadığında devre dışı bırakın

Bir araç genel olarak devre dışı bırakıldığında, araç yanıttan gizlenir list_tools ve çağrılamıyor.

Varlık ayarları

Siz açıkça kısıtlamadığınız sürece varlıklar MCP'ye otomatik olarak katılır. dml-tools Özelliği mevcut olduğundan bir varlığı MCP'nin dışında tutabilirsiniz veya özelliklerini daraltabilirsiniz, ancak normal kullanım için herhangi bir şey ayarlamanız gerekmez.

{
  "entities": {
    "Products": {
      "mcp": {
        "dml-tools": true
      }
    },
    "SensitiveData": {
      "mcp": {
        "dml-tools": false
      }
    }
  }
}

Bir varlıkta belirtmezseniz mcp.dml-tools , mcp genel olarak etkinleştirildiğinde varsayılan true olarak ayarlanır.

Ayrıntılı denetim

Tek tek varlıklar için belirli araçları devre dışı bırakabilirsiniz:

{
  "entities": {
    "AuditLogs": {
      "mcp": {
        "dml-tools": {
          "create-record": true,
          "read-records": true,
          "update-record": false,
          "delete-record": false
        }
      }
    }
  }
}

Bu yapılandırma aracıların denetim günlükleri oluşturmasına ve okumasına izin verir, ancak değişiklik veya silmeyi önler.

RBAC entegrasyonu

Her DML aracı işlemi rol tabanlı erişim denetimi kurallarınızı zorunlu kılar. Bir temsilcinin rolü, hangi varlıkların görünür olduğunu, hangi işlemlere izin verileceğini, hangi alanların dahil edileceğini ve satır seviyesinde politikaların uygulanıp uygulanmayacağını belirler.

anonymous rolü yalnızca Products üzerinde okuma izni veriyorsa:

• describe_entitiesyalnızca işlemlerde gösterilir read_records
• create_record, update_recordve delete_record kullanılamıyor
• Şemada yalnızca anonymous için izin verilen alanlar görünür.

dab-config.json içindeki rollerinizi yapılandırın.

{
  "entities": {
    "Products": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": ["ProductId", "ProductName", "Price"],
                "exclude": ["Cost"]
              }
            }
          ]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

İlgili içerik

• SQL MCP Server'a genel bakış
• SQL MCP Server'a anlamsal açıklamalar ekleme
• Veri API oluşturucusu (DAB) yapılandırma başvurusu
• SQL MCP Server'ı Azure Container Apps'e dağıtma