کتابخانه‌ی استاندارد · پایگاه داده

دیتابیس db

رابط مشترک پایگاه‌های داده، مهاجرت ساختار و استخر اتصال.

واردسازی دیتابیس

نام آرگومان‌ها شناسه‌ی خود کد است و معادل فارسی ندارد؛ گونه‌ها، کلیدواژه‌ها و نام بسته‌ها با معادل فارسی نوشته می‌شوند.

هر موتور پایگاه داده بسته‌ی خودش را دارد: اس کیو لایت، مای اس کیو ال، پستگرس، برای کلید و مقدار ردیس، برای تحلیل داده کلیک هاوس و برای جستجو تایپ‌سنس، میلی‌سرچ، الستیک سرچ و برای جستجو و تحلیل اپن سرچ؛ این دو تای آخر از راه اتصال به پرسمان‌های SQL هم پاسخ می‌دهند. این بسته رابط اتصال را می‌دهد که سه موتور SQL پیاده‌اش می‌کنند؛ اگر کدتان را با آن بنویسید، عوض کردن موتور فقط یک خط است. برای بررسی خود SQL پیش از آنکه به سروری برسد، اس کیو ال آن را با گویش هر موتور تجزیه می‌کند و برابر طرح جدول‌هایتان می‌سنجد.

مهاجرت‌ها ساختار پایگاه داده را همراه کد پیش می‌برند: هر تغییر یک شماره دارد و مهاجرت به بالا آن‌هایی را اعمال می‌کند که شماره‌شان از نسخه‌ی فعلی طرح‌واره بالاتر است. مقدارهایی را که کاربر وارد کرده هرگز مستقیم در SQL نچسبانید؛ آن‌ها را با نقل قول یا پارامترهای آماده‌سازی‌شده بفرستید.

چند نکته که معمولاً غافلگیر می‌کند:

  • نقل قول فقط نقل‌قول تکی را دوتا می‌کند؛ این همان استاندارد SQL است که اس کیو لایت و پستگرس دنبال می‌کنند. مای اس کیو ال به‌طور پیش‌فرض بک‌اسلش را هم نویسه‌ی گریز می‌داند؛ پس روی مای اس کیو ال با c.نقل قول خود اتصال نقل‌قول کنید که بک‌اسلش‌ها را هم گریز می‌دهد.
  • مهاجرت به بالا شماره‌ی نسخه‌ها را مقایسه می‌کند، نه فهرستی از نام‌های اعمال‌شده را. مهاجرتی که شماره‌اش از بالاترین مهاجرت اعمال‌شده کمتر است، مثلاً مهاجرتی که از یک شاخه‌ی قدیمی ادغام شده، بی‌صدا رد می‌شود. به هر مهاجرت تازه همیشه شماره‌ی آزاد بعدی را بدهید.
  • مای اس کیو ال هر CREATE، ALTER و DROP را جداگانه ثبت قطعی می‌کند؛ پس روی مای اس کیو ال مهاجرتی که وسط کار شکست بخورد ممکن است دستورهای اولش را اعمال‌شده باقی بگذارد. اس کیو لایت و پستگرس کل مهاجرت را برمی‌گردانند.
  • SQL مهاجرت در هر ; بیرون از نقل‌قول تکی به دستورها جدا می‌شود. بدنه‌ی تابع پستگرس در $$ ... $$ یا تریگری با چند دستور تکه‌تکه می‌شود؛ این‌ها را با c.اجرا اجرا کنید.

نوشتن کد روی اتصال

به تابع‌های داده‌ای خود به‌جای یک پایگاه داده‌ی SQLite یا PostgreSQL پارامتری از نوع پویا دیتابیس.اتصال بدهید. آن‌وقت با همه‌ی موتورهای SQL کار می‌کنند و آزمون‌ها می‌توانند یک SQLite درون حافظه بدهند، در حالی که نسخه‌ی اصلی PostgreSQL می‌دهد. دیتابیس.اجرا کن یک دستور را اجرا می‌کند و اگر موفق بود درست برمی‌گرداند؛ پ.خطا() می‌گوید چه چیزی خراب شد؛ پ.شناسه آخرین درج() شناسه‌ی ردیفی را که همین الان درج شد می‌دهد.

db-guide-store.salam
واردسازی دیتابیس
واردسازی دیتابیس.اس کیو لایت

تابع آماده سازی(پ: پویا دیتابیس.اتصال): منطقی:
    برگشت دیتابیس.اجرا کن(پ، "CREATE TABLE notes (id INTEGER PRIMARY KEY, author TEXT NOT NULL, body TEXT NOT NULL)")
پایان

تابع افزودن یادداشت(پ: پویا دیتابیس.اتصال، نویسنده: رشته، متن: رشته): صحیح۶۴:
    دستور := "INSERT INTO notes (author, body) VALUES (" + دیتابیس.نقل قول(نویسنده) + ", " + دیتابیس.نقل قول(متن) + ")"
    اگر وارونه دیتابیس.اجرا کن(پ، دستور):
        سرچاپ "درج نشد:"، پ.خطا()
        برگشت ۰
    پایان
    برگشت پ.شناسه آخرین درج()
پایان

تابع نمایش یادداشت‌ها(پ: پویا دیتابیس.اتصال، نویسنده: رشته):
    ردیف‌ها := پ.پرسمان("SELECT id, body FROM notes WHERE author = " + دیتابیس.نقل قول(نویسنده) + " ORDER BY id")
    تا ردیف‌ها.بعدی():
        سرچاپ "#" + ردیف‌ها.عدد صحیح(۰)، ردیف‌ها.متن(۱)
    پایان
    _ := ردیف‌ها.بستن()
پایان

تابع ریشه:
    پ := اس کیو لایت.اتصال(اس کیو لایت.بازکردن(":memory:"))
    اگر وارونه آماده سازی(پ):
        سرچاپ "آماده‌سازی نشد:"، پ.خطا()
        برگشت ۱
    پایان
    افزودن یادداشت(پ، "سارا"، "خرید شیر")
    افزودن یادداشت(پ، "امید"، "تماس با بانک")
    افزودن یادداشت(پ، "سارا"، "تولد 'رضا' است")
    افزودن یادداشت(پ، "x' OR '1'='1"، "تلاش برای نفوذ")
    نمایش یادداشت‌ها(پ، "سارا")
    سرچاپ "یادداشت‌های امید:"، دیتابیس.پرسمان عدد(پ، "SELECT COUNT(*) FROM notes WHERE author = 'امید'")
    سرچاپ "همه‌ی یادداشت‌ها:"، دیتابیس.پرسمان عدد(پ، "SELECT COUNT(*) FROM notes")
    _ := پ.بستن()
    برگشت ۰
پایان
خروجی#1 خرید شیر #3 تولد 'رضا' است یادداشت‌های امید: 1 همه‌ی یادداشت‌ها: 4

هر مقداری که از کاربر آمده از نقل قول می‌گذرد که آن را داخل گیومه می‌گذارد و هر گیومه‌ی درونش را دوتا می‌کند. برای همین آپاستروف در 'رضا' درست ذخیره می‌شود، و نام نویسنده‌ی x' OR '1'='1 به‌جای عوض کردن معنای پرسمان، فقط به شکل یک نام عجیب ذخیره می‌شود. هیچ‌وقت SQL را با چسباندن ورودی خام نسازید.

پرسمان یک پویا دیتابیس.ردیف ها برمی‌گرداند. بعدی به ردیف بعد می‌رود و در پایان نادرست برمی‌گرداند، پس تا ردیف‌ها.بعدی(): از همه‌ی ردیف‌ها می‌گذرد؛ ستون‌ها را با جایگاهشان و با عدد صحیح، متن، عدد اعشار و خالی است بخوانید و ردیف‌ها را همیشه بستن کنید. برای یک عدد یا رشته‌ی تنها، پرسمان عدد و پرسمان متن همه‌ی این کارها را در یک فراخوانی انجام می‌دهند.

تراکنش: همه یا هیچ

وقتی چند دستور باید با هم موفق شوند یا با هم شکست بخورند، آن‌ها را درون یک تراکنش اجرا کنید. پ.شروع تراکنش() یک پویا دیتابیس.تراکنش با اجرا و پرسمان خودش برمی‌گرداند؛ ثبت تراکنش تغییرها را ماندگار می‌کند و بازگردانی همه را دور می‌ریزد. انتقال زیر پول را از یک حساب برمی‌دارد، به حساب دیگر می‌دهد، بعد نتیجه را بررسی می‌کند و اگر حساب اول زیر صفر رفته باشد بازمی‌گرداند.

db-guide-transfer.salam
واردسازی دیتابیس
واردسازی دیتابیس.اس کیو لایت

تابع انتقال(پ: پویا دیتابیس.اتصال، از حساب: صحیح، به حساب: صحیح، مبلغ: صحیح): رشته:
    ت := پ.شروع تراکنش()
    اگر وارونه ت.معتبر():
        برگشت "شروع نشد: " + پ.خطا()
    پایان
    _ := ت.اجرا("UPDATE accounts SET balance = balance - " + مبلغ + " WHERE id = " + از حساب)
    _ := ت.اجرا("UPDATE accounts SET balance = balance + " + مبلغ + " WHERE id = " + به حساب)
    ردیف‌ها := ت.پرسمان("SELECT balance FROM accounts WHERE id = " + از حساب)
    ناپایا مانده := ۰
    اگر ردیف‌ها.بعدی():
        مانده = ردیف‌ها.عدد صحیح(۰)
    پایان
    _ := ردیف‌ها.بستن()
    اگر مانده < ۰:
        _ := ت.بازگردانی()
        برگشت "رد شد، فقط " + (مانده + مبلغ) + " مانده"
    پایان
    _ := ت.ثبت تراکنش()
    برگشت مبلغ + " منتقل شد"
پایان

تابع موجودی‌ها(پ: پویا دیتابیس.اتصال): رشته:
    برگشت دیتابیس.پرسمان متن(پ، "SELECT group_concat(name || '=' || balance, ' ') FROM accounts")
پایان

تابع ریشه:
    پ := اس کیو لایت.اتصال(اس کیو لایت.بازکردن(":memory:"))
    ناپایا آغاز := وکتور {} برگردان وکتور<رشته>
    دیرکن آغاز.آزادکن()
    آغاز.بیفزا("CREATE TABLE accounts (id INTEGER PRIMARY KEY, name TEXT, balance INTEGER)")
    آغاز.بیفزا("INSERT INTO accounts VALUES (1, 'علی', 100), (2, 'سارا', 50)")
    سرچاپ دیتابیس.در تراکنش(پ، آغاز)
    سرچاپ انتقال(پ، ۱، ۲، ۳۰)، "|"، موجودی‌ها(پ)
    سرچاپ انتقال(پ، ۱، ۲، ۵۰۰)، "|"، موجودی‌ها(پ)
    سرچاپ انتقال(پ، ۲، ۱، ۸۰)، "|"، موجودی‌ها(پ)
    _ := پ.بستن()
پایان
خروجیtrue 30 منتقل شد | علی=70 سارا=80 رد شد، فقط 70 مانده | علی=70 سارا=80 80 منتقل شد | علی=150 سارا=0

درون تراکنش، پرسمان‌ها تغییرهای ثبت‌نشده را می‌بینند و همین بررسی را ممکن می‌کند. اتصال‌های دیگر تا ثبت تراکنش آن‌ها را نمی‌بینند. وقتی فهرست ثابتی از دستورها دارید و میانشان بررسی‌ای نیست، دیتابیس.در تراکنش همه را در یک تراکنش اجرا می‌کند و اگر یکی شکست بخورد نادرست برمی‌گرداند و هیچ‌کدام اعمال نمی‌شود.

مهاجرت هنگام راه‌اندازی

هر بار که برنامه شروع می‌شود مهاجرت به بالا را صدا بزنید. این تابع هر نسخه‌ی اعمال‌شده را در جدولی از آنِ خودش ثبت می‌کند، پس اجرای نخست طرح‌واره را می‌سازد، اجراهای بعدی کاری نمی‌کنند، و نسخه‌ای از برنامه که مهاجرت ۳ را اضافه کرده فقط همان را اعمال می‌کند. داده‌های موجود سر جایشان می‌مانند.

db-guide-startup.salam
واردسازی دیتابیس
واردسازی دیتابیس.اس کیو لایت

تابع مهاجرت‌ها(): دیتابیس.مهاجرت گر:
    ناپایا م := دیتابیس.مهاجرت گر جدید()
    دیتابیس.افزودن مهاجرت(م، ۱، "ساخت کاربران"، "CREATE TABLE users (id INTEGER PRIMARY KEY, email TEXT NOT NULL UNIQUE)"، "DROP TABLE users")
    دیتابیس.افزودن مهاجرت(م، ۲، "افزودن نام"، "ALTER TABLE users ADD COLUMN name TEXT DEFAULT ''"، "ALTER TABLE users DROP COLUMN name")
    برگشت م
پایان

تابع راه اندازی(پ: پویا دیتابیس.اتصال):
    ناپایا م := مهاجرت‌ها()
    پیش := دیتابیس.نسخه طرح‌واره(م، پ)
    اعمال شده := دیتابیس.مهاجرت به بالا(م، پ)
    سرچاپ "طرح‌واره"، پیش، "به"، دیتابیس.نسخه طرح‌واره(م، پ)، "(" + اعمال شده + " مهاجرت اعمال شد)"
    دیتابیس.آزادکردن مهاجرت گر(م)
پایان

تابع ریشه:
    پ := اس کیو لایت.اتصال(اس کیو لایت.بازکردن(":memory:"))
    راه اندازی(پ)
    سرچاپ دیتابیس.اجرا کن(پ، "INSERT INTO users (email, name) VALUES ('a@x.ir', 'علی')")
    راه اندازی(پ)
    ناپایا م := مهاجرت‌ها()
    دیتابیس.افزودن مهاجرت(م، ۳، "افزودن شهر"، "ALTER TABLE users ADD COLUMN city TEXT"، "ALTER TABLE users DROP COLUMN city")
    سرچاپ "در انتظار:"، دیتابیس.تعداد در انتظار(م، پ)
    سرچاپ "اعمال شد:"، دیتابیس.مهاجرت به بالا(م، پ)، "اکنون در نسخه‌ی"، دیتابیس.نسخه طرح‌واره(م، پ)
    سرچاپ دیتابیس.پرسمان متن(پ، "SELECT name FROM users WHERE email = 'a@x.ir'")
    دیتابیس.آزادکردن مهاجرت گر(م)
    _ := پ.بستن()
پایان
خروجیطرح‌واره 0 به 2 (2 مهاجرت اعمال شد) true طرح‌واره 2 به 2 (0 مهاجرت اعمال شد) در انتظار: 1 اعمال شد: 1 اکنون در نسخه‌ی 3 علی

هیچ‌وقت مهاجرتی را که جایی اجرا شده تغییر ندهید؛ به‌جایش مهاجرت تازه‌ای بیفزایید. هر مهاجرت در تراکنش خودش اجرا می‌شود، پس روی اس کیو لایت و پستگرس مهاجرتی که شکست بخورد طرح‌واره را در نسخه‌ی قبلی نگه می‌دارد. بازگردانی آخرین مهاجرت را با SQL بخش down برمی‌گرداند و مهاجرت به به هر نسخه‌ای می‌رود؛ این‌ها در توسعه به کار می‌آیند و در محیط اصلی کمتر.

انتخاب موتور هنگام اجرا

چون باقی برنامه فقط پویا دیتابیس.اتصال را می‌بیند، موتور را می‌شود از یک تنظیم انتخاب کرد. این‌جا متغیر محیطی APP_DB میان PostgreSQL، MySQL و یک پرونده‌ی SQLite انتخاب می‌کند و همه‌ی کد پس از وصل شدن برای هر سه یکی است.

db-guide-engines.salam
واردسازی دیتابیس
واردسازی دیتابیس.اس کیو لایت
واردسازی دیتابیس.پستگرس
واردسازی دیتابیس.مای اس کیو ال
واردسازی محیط

تابع وصل شدن(): پویا دیتابیس.اتصال:
    موتور := محیط.دریافت با پیش فرض("APP_DB"، "sqlite")
    اگر موتور == "postgres":
        برگشت پستگرس.اتصال(پستگرس.بازکردن("host=127.0.0.1 port=5432 user=app password=secret dbname=app"))
    وگرنه موتور == "mysql":
        برگشت مای اس کیو ال.اتصال(مای اس کیو ال.بازکردن("127.0.0.1"، "app"، "secret"، "app"، ۳۳۰۶))
    پایان
    برگشت اس کیو لایت.اتصال(اس کیو لایت.بازکردن("app.db"))
پایان

تابع ریشه:
    پ := وصل شدن()
    اگر وارونه پ.معتبر():
        سرچاپ "اتصال به"، پ.نوع()، "برقرار نشد:"، پ.خطا()
        برگشت ۱
    پایان
    سرچاپ "وصل شد به"، پ.نوع()
    _ := دیتابیس.اجرا کن(پ، "CREATE TABLE IF NOT EXISTS visits (page VARCHAR(100))")
    _ := دیتابیس.اجرا کن(پ، "INSERT INTO visits (page) VALUES ('home')")
    سرچاپ "تعداد بازدیدها تا این‌جا:"، دیتابیس.پرسمان عدد(پ، "SELECT COUNT(*) FROM visits")
    _ := پ.بستن()
    برگشت ۰
پایان

بدون APP_DB از SQLite استفاده می‌کند و به چیز دیگری نیاز ندارد؛ هر اجرا یک بازدید می‌افزاید، پس شمارش هر بار یکی بیشتر می‌شود. برای آزمودن PostgreSQL، یک سرور با داکر راه بیندازید و برنامه را با APP_DB=postgres اجرا کنید:

docker run -d -p 5432:5432 -e POSTGRES_USER=app -e POSTGRES_PASSWORD=secret -e POSTGRES_DB=app postgres:17
APP_DB=postgres salam run db-guide-engines.salam

به SQLی بسنده کنید که همه‌ی موتورهایتان می‌فهمند، یا بخش‌های ویژه‌ی هر موتور را در یک تابع نگه دارید. جانگهدارها و نقل قول‌گذاری در موتورها فرق دارند؛ این هم دلیل دیگری است که نقل قول را به نقل قول یا پ.نقل قول بسپارید.

کارابزار
یک دستور، موفق شد یا نه؟دیتابیس.اجرا کن
یک مقدار تنهاپرسمان عدد، پرسمان عدد۶۴، پرسمان اعشار، پرسمان متن
چندین ردیفپ.پرسمان، سپس بعدی و بستن
چند دستور که به هم وابسته‌اندپ.شروع تراکنش، ثبت تراکنش، بازگردانی، یا دیتابیس.در تراکنش
تغییر طرح‌وارهمهاجرت گر جدید، افزودن مهاجرت، مهاجرت به بالا
چند اتصال برای نخ‌هااستخر جدید، گرفتن، رهاکردن

گونه‌ها

مهاجرت Migration

ساختار مهاجرت
یک مهاجرت: یک تغییر شماره‌دار در ساختار پایگاه داده.
نامانگلیسیگونهتوضیح
نسخهversionصحیح = 0شماره‌ی نسخه؛ مهاجرت‌ها به ترتیب همین شماره اعمال می‌شوند.
نامnameرشته = ""نام.
اعمالupرشته = ""SQL اعمال؛ چند دستور را با ; جدا کنید.
برگرداندنdownرشته = ""SQL برگرداندن.
db-Migrate.salam
واردسازی دیتابیس
واردسازی دیتابیس.اس کیو لایت

تابع ریشه:
    ا := اس کیو لایت.اتصال(اس کیو لایت.بازکردن(":memory:"))
    ناپایا م := دیتابیس.مهاجرت گر جدید()
    دیتابیس.افزودن مهاجرت(م، ۱، "users"، "CREATE TABLE users (id INTEGER PRIMARY KEY, email TEXT NOT NULL)"، "DROP TABLE users")
    دیتابیس.افزودن مهاجرت(م، ۲، "posts"، "CREATE TABLE posts (id INTEGER PRIMARY KEY, title TEXT); INSERT INTO posts (title) VALUES ('سلام')"، "DROP TABLE posts")
    دیتابیس.افزودن مهاجرت(م، ۳، "tags"، "ALTER TABLE posts ADD COLUMN tag TEXT"، "ALTER TABLE posts DROP COLUMN tag")
    سرچاپ دیتابیس.تعداد مهاجرت(م)، دیتابیس.نسخه طرح‌واره(م، ا)، دیتابیس.تعداد در انتظار(م، ا)

    سرچاپ دیتابیس.مهاجرت به(م، ا، ۲)
    سرچاپ دیتابیس.نسخه طرح‌واره(م، ا)، دیتابیس.اعمال شده(م، ا، ۲)، دیتابیس.اعمال شده(م، ا، ۳)
    سرچاپ دیتابیس.مهاجرت به بالا(م، ا)، دیتابیس.نسخه طرح‌واره(م، ا)
    سرچاپ دیتابیس.مهاجرت به بالا(م، ا)
    سرچاپ دیتابیس.بازگردانی(م، ا)، دیتابیس.نسخه طرح‌واره(م، ا)
    سرچاپ دیتابیس.مهاجرت به(م، ا، ۰)، دیتابیس.نسخه طرح‌واره(م، ا)
    سرچاپ دیتابیس.پرسمان عدد(ا، "SELECT COUNT(*) FROM " + دیتابیس.جدول مهاجرت)
    دیتابیس.آزادکردن مهاجرت گر(م)

    ناپایا م۲ := دیتابیس.مهاجرت گر در("app_versions")
    دیتابیس.افزودن مهاجرت(م۲، ۱، "t"، "CREATE TABLE t (x INTEGER)"، "DROP TABLE t")
    سرچاپ دیتابیس.ساخت جدول(م۲، ا)، دیتابیس.مهاجرت به بالا(م۲، ا)، م۲.جدول
    دیتابیس.آزادکردن مهاجرت گر(م۲)

    تکه‌ها := دیتابیس.جداکردن دستورها("INSERT INTO t VALUES (1); SELECT ';' ; ")
    سرچاپ تکه‌ها.طول()، تکه‌ها.دریافت(۱)
پایان
خروجی3 0 3 2 2 true false 1 3 0 true 2 2 0 0 0 1 app_versions 2 SELECT ';'

مهاجرت گر Migrator

ساختار مهاجرت گر
مجموعه‌ی مهاجرت‌ها.
نامانگلیسیگونهتوضیح
مهاجرت‌هاitemsوکتور<مهاجرت>مهاجرت‌ها.
جدولtableرشته = ""نام جدول نسخه‌ها.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Migrate.salam

ردیف ها Rows

میانجی ردیف ها
رابط ردیف‌های یک پرسمان؛ متدهایش: بعدی، متن، عدد صحیح، بستن و مانند آن.
db-Connection.salam
واردسازی دیتابیس
واردسازی دیتابیس.اس کیو لایت

تابع گزارش(ا: dyn دیتابیس.اتصال):
    سرچاپ ا.نوع()، ا.معتبر()، ا.پینگ()
    _ := ا.اجرا("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, score REAL)")
    _ := ا.اجرا("INSERT INTO users (name, score) VALUES (" + ا.نقل قول("O'Brien") + ", 7.5)")
    _ := ا.اجرا("INSERT INTO users (name, score) VALUES ('مریم', 9)")
    سرچاپ ا.شناسه آخرین درج()، ا.تعداد تغییرات()

    ر := ا.پرسمان("SELECT id, name, score FROM users ORDER BY id")
    سرچاپ ر.معتبر()، ر.تعداد ستون()، ر.نام ستون(۱)
    تا ر.بعدی():
        سرچاپ ر.عدد صحیح(۰)، ر.متن(۱)، ر.عدد اعشار(۲)، ر.عدد صحیح۶۴(۰)، ر.خالی است(۲)، ر.نوع ستون(۱)
    پایان
    _ := ر.بستن()

    ت := ا.شروع تراکنش()
    سرچاپ ت.معتبر()
    _ := ت.اجرا("UPDATE users SET score = 0")
    ت‌ر := ت.پرسمان("SELECT SUM(score) FROM users")
    _ := ت‌ر.بعدی()
    سرچاپ ت‌ر.عدد اعشار(۰)
    _ := ت‌ر.بستن()
    _ := ت.بازگردانی()
    ت۲ := ا.شروع تراکنش()
    _ := ت۲.اجرا("DELETE FROM users WHERE id = 1")
    _ := ت۲.ثبت تراکنش()

    سرچاپ دیتابیس.پرسمان عدد(ا، "SELECT COUNT(*) FROM users")، دیتابیس.پرسمان عدد۶۴(ا، "SELECT MAX(id) FROM users")
    سرچاپ دیتابیس.پرسمان اعشار(ا، "SELECT score FROM users")، دیتابیس.پرسمان متن(ا، "SELECT name FROM users")
    سرچاپ دیتابیس.شمارش ردیف ها(ا، "SELECT * FROM users")
    سرچاپ دیتابیس.اجرا کن(ا، "INSERT INTO users (name) VALUES ('علی')")، دیتابیس.اجرا کن(ا، "INSERT INTO nowhere VALUES (1)")
    سرچاپ ا.خطا()
    ناپایا دستورها := وکتور {} برگردان وکتور<رشته>
    دستورها.افزودن("INSERT INTO users (name) VALUES ('سارا')")
    دستورها.افزودن("INSERT INTO users (name) VALUES ('رضا')")
    سرچاپ دیتابیس.اجرای همه(ا، دستورها)
    دستورها.افزودن("INSERT INTO nowhere VALUES (1)")
    سرچاپ دیتابیس.در تراکنش(ا، دستورها)، دیتابیس.پرسمان عدد(ا، "SELECT COUNT(*) FROM users")
    سرچاپ دیتابیس.نقل قول("it's")
    _ := ا.بستن()
پایان

تابع ریشه:
    گزارش(اس کیو لایت.اتصال(اس کیو لایت.بازکردن(":memory:")))
    سرچاپ دیتابیس.اس کیو لایت، دیتابیس.مای اس کیو ال، دیتابیس.پستگرس
    سرچاپ دیتابیس.نوع خالی، دیتابیس.نوع صحیح، دیتابیس.نوع اعشاری، دیتابیس.نوع متن، دیتابیس.نوع دودویی
پایان
خروجیsqlite true true 2 1 true 3 name 1 O'Brien 7.5 1 false 3 2 مریم 9 2 false 3 true 0 1 2 9 مریم 1 true false no such table: nowhere 2 false 4 'it''s' sqlite mysql postgres 0 1 2 3 4

تراکنش Tx

میانجی تراکنش
رابط تراکنش؛ متدهایش: اجرا، پرسمان، ثبت تراکنش و بازگردانی.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Connection.salam

اتصال Connection

میانجی اتصال
رابط مشترک همه‌ی موتورها. کدی که با آن نوشته شود بدون تغییر روی SQLite، MySQL و PostgreSQL کار می‌کند؛ آن را با اتصال هر موتور بگیرید.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Connection.salam

استخر Pool

ساختار استخر
استخر اتصال‌ها برای برنامه‌هایی که هم‌زمان چند اتصال لازم دارند.
نامانگلیسیگونهتوضیح
اتصال‌هاconnsوکتوراتصال‌ها.
گرفته‌شده‌هاtakenوکتور<صحیح>کدام اتصال گرفته شده.
حدlimitصحیح = 0بیشترین شمار اتصال.
db-Pool.salam
واردسازی دیتابیس
واردسازی دیتابیس.اس کیو لایت

تابع ریشه:
    ناپایا استخر := دیتابیس.استخر جدید(۲)
    تکرار ۳:
        سرچاپ دیتابیس.افزودن(استخر، اس کیو لایت.اتصال(اس کیو لایت.بازکردن(":memory:")))
    پایان
    سرچاپ دیتابیس.اندازه(استخر)، دیتابیس.بیکار(استخر)، دیتابیس.در استفاده(استخر)

    یک := دیتابیس.گرفتن(استخر)
    دو := دیتابیس.گرفتن(استخر)
    سه := دیتابیس.گرفتن(استخر)
    سرچاپ دیتابیس.اجاره شده(یک)، دیتابیس.اجاره شده(سه)، سه == دیتابیس.بدون اجاره
    سرچاپ دیتابیس.بیکار(استخر)، دیتابیس.در استفاده(استخر)

    ا := دیتابیس.اتصال اجاره‌ای(استخر، یک)
    سرچاپ دیتابیس.پرسمان عدد(ا، "SELECT 6 * 7")
    دیتابیس.رهاکردن(استخر، یک)
    دیتابیس.رهاکردن(استخر، دو)
    سرچاپ دیتابیس.بیکار(استخر)، دیتابیس.حذف مرده ها(استخر)
    دیتابیس.بستن همه(استخر)
    دیتابیس.آزادکردن(استخر)
پایان
خروجیtrue true false 2 2 0 true false true 0 2 42 2 0

پایاها و متغیرها

جدول مهاجرت MIGRATION_TABLE

پایا جدول مهاجرت: رشته = "schema_migrations"
نام پیش‌فرض جدولی که نسخه‌های اعمال‌شده در آن ثبت می‌شوند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Migrate.salam

اس کیو لایت SQLITE

پایا اس کیو لایت: رشته = "sqlite"
نام موتور SQLite.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Connection.salam

مای اس کیو ال MYSQL

پایا مای اس کیو ال: رشته = "mysql"
نام موتور MySQL.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Connection.salam

پستگرس POSTGRES

پایا پستگرس: رشته = "postgres"
نام موتور PostgreSQL.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Connection.salam

الستیک سرچ ELASTICSEARCH

پایا الستیک سرچ: رشته = "elasticsearch"
نام موتور Elasticsearch.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Connection.salam

اپن سرچ OPENSEARCH

پایا اپن سرچ: رشته = "opensearch"
نام موتور اپن سرچ.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Connection.salam

کلیک هاوس CLICKHOUSE

پایا کلیک هاوس: رشته = "clickhouse"
نام موتور کلیک هاوس.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Connection.salam

نوع خالی TYPE_NULL

پایا نوع خالی: صحیح۳۲ = 0
گونه‌ی ستون: تهی.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Connection.salam

نوع صحیح TYPE_INT

پایا نوع صحیح: صحیح۳۲ = 1
گونه‌ی ستون: عدد صحیح.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Connection.salam

نوع اعشاری TYPE_FLOAT

پایا نوع اعشاری: صحیح۳۲ = 2
گونه‌ی ستون: اعشاری.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Connection.salam

نوع متن TYPE_TEXT

پایا نوع متن: صحیح۳۲ = 3
گونه‌ی ستون: متن.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Connection.salam

نوع دودویی TYPE_BLOB

پایا نوع دودویی: صحیح۳۲ = 4
گونه‌ی ستون: دودویی.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Connection.salam

بدون اجاره NO_LEASE

پایا بدون اجاره: صحیح۳۲ = -1
شماره‌ای که گرفتن وقتی اتصال آزادی نیست برمی‌گرداند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Pool.salam

تابع‌ها

مهاجرت گر جدید NewMigrator

تابع مهاجرت گر جدید(): مهاجرت گر
مهاجرت‌گر با جدول پیش‌فرض.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Migrate.salam

مهاجرت گر در NewMigratorIn

تابع مهاجرت گر در(table: رشته): مهاجرت گر
مهاجرت‌گر با جدول نسخه‌ی دیگر.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Migrate.salam

آزادکردن مهاجرت گر FreeMigrator

تابع آزادکردن مهاجرت گر(m &: مهاجرت گر)
حافظه را آزاد می‌کند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Migrate.salam

افزودن مهاجرت AddMigration

تابع افزودن مهاجرت(m &: مهاجرت گر، version: صحیح، name: رشته، up: رشته، down: رشته)
مهاجرتی با شماره، نام و SQL اعمال و برگرداندن می‌افزاید؛ ترتیب افزودن مهم نیست.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Migrate.salam

تعداد مهاجرت MigrationCount

تابع تعداد مهاجرت(m: مهاجرت گر): صحیح
شمار مهاجرت‌ها.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Migrate.salam

جداکردن دستورها SplitStatements

تابع جداکردن دستورها(sql: رشته): وکتور<رشته>
متن SQL را در هر ; به دستورها جدا می‌کند. ; درون رشته‌ای با نقل‌قول تکی جداکننده نیست، اما درون نامی با نقل‌قول دوتایی، توضیح یا بلوک $$ هست.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Migrate.salam

ساخت جدول EnsureTable

تابع ساخت جدول(m: مهاجرت گر، c: dyn اتصال): صحیح
جدول نسخه‌ها را اگر نباشد می‌سازد.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Migrate.salam

نسخه طرح‌واره SchemaVersion

تابع نسخه طرح‌واره(m: مهاجرت گر، c: dyn اتصال): صحیح
بالاترین نسخه‌ی اعمال‌شده؛ اگر هیچ، صفر.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Migrate.salam

اعمال شده IsApplied

تابع اعمال شده(m: مهاجرت گر، c: dyn اتصال، version: صحیح): منطقی
این نسخه اعمال شده.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Migrate.salam

تعداد در انتظار PendingCount

تابع تعداد در انتظار(m: مهاجرت گر، c: dyn اتصال): صحیح
شمار مهاجرت‌های اعمال‌نشده.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Migrate.salam

مهاجرت به بالا MigrateUp

تابع مهاجرت به بالا(m: مهاجرت گر، c: dyn اتصال): صحیح
هر مهاجرتی را که شماره‌اش از نسخه‌ی فعلی طرح‌واره بالاتر است، به ترتیب و هر کدام در تراکنش خودش، اعمال می‌کند و شمار مهاجرت‌های اجراشده را برمی‌گرداند. در نخستین شکست می‌ایستد.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Migrate.salam

بازگردانی Rollback

تابع بازگردانی(m: مهاجرت گر، c: dyn اتصال): منطقی
آخرین مهاجرت را برمی‌گرداند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Connection.salam

مهاجرت به MigrateTo

تابع مهاجرت به(m: مهاجرت گر، c: dyn اتصال، target: صحیح): صحیح
بالا یا پایین می‌رود تا نسخه به عدد داده‌شده برسد و شمار گام‌ها را برمی‌گرداند؛ صفر یعنی همه برگردند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Migrate.salam

پرسمان عدد QueryInt

تابع پرسمان عدد(c: dyn اتصال، sql: رشته): صحیح
نخستین ستون نخستین ردیف به شکل عدد؛ برای COUNT و مانند آن.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Connection.salam

پرسمان عدد۶۴ QueryInt64

تابع پرسمان عدد۶۴(c: dyn اتصال، sql: رشته): صحیح۶۴
مثل تابع بالا، ۶۴ بیتی.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Connection.salam

پرسمان اعشار QueryFloat

تابع پرسمان اعشار(c: dyn اتصال، sql: رشته): اعشار۶۴
مثل تابع بالا، اعشاری.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Connection.salam

پرسمان متن QueryText

تابع پرسمان متن(c: dyn اتصال، sql: رشته): رشته
مثل تابع بالا، متن.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Connection.salam

شمارش ردیف ها CountRows

تابع شمارش ردیف ها(c: dyn اتصال، sql: رشته): صحیح
شمار ردیف‌های نتیجه‌ی پرسمان.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Connection.salam

اجرا کن Run

تابع اجرا کن(c: dyn اتصال، sql: رشته): منطقی
دستوری را اجرا می‌کند؛ اگر موفق بود، درست.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Connection.salam

اجرای همه RunAll

تابع اجرای همه(c: dyn اتصال، stmts: وکتور<رشته>): صحیح
دستورها را به ترتیب اجرا می‌کند و شمار موفق‌ها را برمی‌گرداند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Connection.salam

در تراکنش InTx

تابع در تراکنش(c: dyn اتصال، stmts: وکتور<رشته>): منطقی
همه‌ی دستورها را در یک تراکنش اجرا می‌کند؛ اگر یکی شکست بخورد، هیچ‌کدام اعمال نمی‌شود.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Connection.salam

نقل قول QuoteLiteral

تابع نقل قول(s: رشته): رشته
رشته را به شکل مقدار SQL برمی‌گرداند: میان دو نقل‌قول تکی و با دوتا کردن هر ' درونش. بک‌اسلش دست‌نخورده می‌ماند؛ پس روی مای اس کیو ال نقل قول خود اتصال را به کار ببرید.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Connection.salam

استخر جدید NewPool

تابع استخر جدید(limit: صحیح): استخر
استخر خالی با بیشترین شمار اتصال.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Pool.salam

افزودن Add

تابع افزودن(p &: استخر، c: dyn اتصال): منطقی
اتصالی به استخر می‌افزاید؛ اگر استخر پر باشد، نادرست.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Connection.salam

گرفتن Acquire

تابع گرفتن(p &: استخر): صحیح
یک اتصال آزاد را می‌گیرد و شماره‌ی اجاره را برمی‌گرداند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Pool.salam

اجاره شده Leased

تابع اجاره شده(lease: صحیح): منطقی
این شماره‌ی اجاره معتبر است.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Pool.salam

اتصال اجاره‌ای Conn

تابع اتصال اجاره‌ای(p: استخر، lease: صحیح): dyn اتصال
اتصال یک اجاره.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Pool.salam

رهاکردن Release

تابع رهاکردن(p &: استخر، lease: صحیح)
اتصال را به استخر برمی‌گرداند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Pool.salam

اندازه Size

تابع اندازه(p: استخر): صحیح
شمار اتصال‌ها.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Pool.salam

بیکار Idle

تابع بیکار(p: استخر): صحیح
شمار اتصال‌های آزاد.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Pool.salam

در استفاده InUse

تابع در استفاده(p: استخر): صحیح
شمار اتصال‌های گرفته‌شده.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Pool.salam

حذف مرده ها DropDead

تابع حذف مرده ها(p &: استخر): صحیح
اتصال‌های آزادی را که دیگر پاسخ نمی‌دهند می‌بندد و برمی‌دارد.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Pool.salam

بستن همه CloseAll

تابع بستن همه(p &: استخر)
همه‌ی اتصال‌ها را می‌بندد.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Pool.salam

آزادکردن Free

تابع آزادکردن(p &: استخر)
حافظه‌ی استخر را آزاد می‌کند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: db-Migrate.salam