Mengonfigurasi pengaturan modul mssql-python

Driver mssql-python menyediakan Settings kelas yang mengontrol perilaku di seluruh modul. Pengaturan ini memengaruhi semua koneksi dan operasi kursor. Konfigurasikan sekali saat startup aplikasi, sebelum Anda membuat koneksi apa pun.

Pengaturan akses

Ambil objek saat ini Settings dan periksa atau ubah propertinya:

import mssql_python

# Get settings object
settings = mssql_python.get_settings()

# Check current values
print(settings.lowercase)
print(settings.decimal_separator)

Pengaturan yang tersedia

Pengaturan berikut mengontrol bagaimana driver mengembalikan data dan memformat hasil.

huruf kecil

Pengaturan lowercase mengontrol apakah nama kolom di cursor.description ditampilkan dalam huruf kecil. Aktifkan pengaturan ini saat aplikasi Anda mengakses kolom berdasarkan nama dan Anda ingin menghindari ketidakcocokan penggunaan huruf besar/kecil. Framework web seperti Flask dan FastAPI sering mengonversi baris data menjadi kamus, sehingga konsistensi penggunaan huruf besar/kecil menjadi penting:

settings = mssql_python.get_settings()

# Enable lowercase column names (default: False)
settings.lowercase = True

# Column names in cursor.description are now lowercased:
# ('productid', ...) instead of ('ProductID', ...)
Nilai Deskripsi
False Default. Nama kolom mempertahankan casing asli.
True Nama kolom di dalam cursor.description diubah menjadi huruf kecil.

Pemisah desimal

Driver menyediakan fungsi tingkat modul untuk mengontrol pemisah desimal untuk konversi numerik. Ubah pengaturan ini hanya jika instans SQL Server Anda menggunakan lokal dengan koma sebagai pemisah desimal, seperti lokal Prancis atau Jerman. Sebagian besar aplikasi tidak perlu mengubah pengaturan ini:

import mssql_python

# Get current separator
sep = mssql_python.getDecimalSeparator()
print(f"Current separator: {sep}")  # Usually "."

# Set custom separator (for locales using comma)
mssql_python.setDecimalSeparator(",")

Untuk informasi selengkapnya tentang penanganan desimal, lihat Pemetaan tipe data.

native_uuid

Pengaturan native_uuid mengontrol apakah kolom UNIQUEIDENTIFIER dikembalikan sebagai objek Python uuid.UUID atau sebagai string huruf besar yang kompatibel dengan pyodbc. Pengaturan ini berguna untuk tim yang bermigrasi dari pyodbc yang bergantung pada nilai UUID string:

settings = mssql_python.get_settings()

# Return UUIDs as uuid.UUID objects (default: True)
settings.native_uuid = True

# Return UUIDs as uppercase strings (pyodbc-compatible)
settings.native_uuid = False
Nilai Deskripsi
True Default. UNIQUEIDENTIFIER kolom mengembalikan uuid.UUID objek.
False UNIQUEIDENTIFIER kolom mengembalikan string huruf kapital (kompatibel dengan pyodbc).

Anda juga dapat mengatur native_uuid per koneksi:

# Override for a specific connection
conn = mssql_python.connect(connection_string, native_uuid=False)

Note

Pengaturan native_uuid diperkenalkan di mssql-python versi 1.5.0.

Konstanta tingkat modul

Driver menyediakan konstanta baca-saja untuk kepatuhan DB-API 2.0 yang menggambarkan kapabilitasnya. Gunakan konstanta ini untuk menulis kode yang beradaptasi dengan driver DB-API yang berbeda:

import mssql_python

# DB-API 2.0 compliance level
print(mssql_python.apilevel)      # '2.0'

# Thread safety level
print(mssql_python.threadsafety)  # 1

# Parameter style
print(mssql_python.paramstyle)    # 'pyformat'

tingkat api

Konstanta apilevel melaporkan tingkat kepatuhan DB-API:

Nilai Meaning
'2.0' Kepatuhan penuh DB-API 2.0.

keamanan thread

Konstanta threadsafety melaporkan tingkat keamanan benang:

Nilai Meaning
0 Thread tidak dapat menggunakan modul yang sama.
1 Utas dapat berbagi modul tetapi tidak koneksi.
2 Threads dapat berbagi modul dan koneksi.
3 Utas dapat berbagi modul, koneksi, dan kursor.

Driver mssql-python menggunakan threadsafety = 1, yang berarti:

  • Anda dapat mengimpor dan menggunakan modul di beberapa utas.
  • Setiap koneksi harus hanya dimiliki oleh satu utas pada satu waktu.
  • Buat koneksi terpisah per utas, atau gunakan kumpulan koneksi (diaktifkan secara default). Untuk informasi selengkapnya, lihat Pengumpulan koneksi.

paramstyle

Konstanta paramstyle menunjukkan format placeholder parameter:

Style Format Example
'qmark' Tanda tanya WHERE id = ?
'numeric' Posisi numerik WHERE id = :1
'named' Dinamai WHERE id = :id
'format' ANSI C printf WHERE id = %s
'pyformat' Format Python WHERE id = %(id)s

Driver mssql-python menggunakan paramstyle = 'pyformat'. Selalu gunakan parameter bernama untuk mencegah injeksi SQL. Jangan pernah membuat kueri dengan input pengguna melalui pemformatan string atau f-string:

# Use named parameters with %(name)s syntax
cursor.execute(
    "SELECT * FROM Production.Product WHERE ProductSubcategoryID = %(cat)s AND ListPrice > %(price)s",
    {"cat": 5, "price": 10.00}
)

Informasi versi

Periksa versi driver mana yang diinstal:

import mssql_python

# Driver version
print(mssql_python.__version__)  # e.g., '1.5.0'

Mengonfigurasi pengaturan saat startup

Atur konfigurasi modul sekali saat startup aplikasi, sebelum Anda membuat koneksi apa pun. Menetapkan nilai lebih awal mencegah perilaku yang tidak konsisten di seluruh koneksi:

import mssql_python

def configure_driver():
    """Configure mssql-python settings for this application."""
    settings = mssql_python.get_settings()
    
    # Use lowercase column names in cursor.description
    settings.lowercase = True

# Call at application startup
configure_driver()

# All subsequent connections use these settings
conn = mssql_python.connect(connection_string)

Pertimbangan keamanan ulir

Pengaturan modul bersifat global dan memengaruhi semua koneksi di semua utas. Jika Anda mengubah pengaturan setelah koneksi sudah terbuka, koneksi yang ada mungkin tidak mencerminkan perubahan secara konsisten. Tetapkan semua nilai konfigurasi sebelum Anda membuat koneksi pertama Anda:

import mssql_python
import threading

# Settings changes affect all threads
settings = mssql_python.get_settings()
settings.lowercase = True  # Affects all connections in all threads

def worker():
    # This connection uses the global settings
    conn = mssql_python.connect(connection_string)
    cursor = conn.cursor()
    cursor.execute("SELECT Name FROM Production.Product")
    row = cursor.fetchone()
    print(cursor.description[0][0])  # 'name' due to global setting

threads = [threading.Thread(target=worker) for _ in range(5)]
for t in threads:
    t.start()
for t in threads:
    t.join()

Penting

Konfigurasikan pengaturan sebelum membuat koneksi. Mengubah pengaturan setelah koneksi dibuat dapat menyebabkan perilaku yang tidak konsisten.

Konfigurasi khusus koneksi

Anda dapat mengganti beberapa pengaturan per koneksi tanpa mengubah default global. Gunakan penggantian per koneksi saat bagian yang berbeda dari aplikasi Anda memerlukan perilaku yang berbeda. Misalnya, modul pelaporan mungkin memerlukan UUID string sementara aplikasi lainnya menggunakan uuid.UUID objek:

# Per-connection native_uuid override
conn = mssql_python.connect(connection_string, native_uuid=False)

# Use the autocommit property
conn.autocommit = True

Konten terkait

  • Last updated on