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

اس کیو ال `db/sql`

خواندن، بررسی و گونه‌یابی SQL بدون پایگاه داده: تجزیه‌گر آگاه از گویش، فهرست جدول‌ها و جانگهدارهای گونه‌دار.

واردسازی دیتابیس.اس کیو ال

در این صفحه

از همین جا: یک قدم‌به‌قدم از طرح تا پرسمان بررسی‌شده
خواندن یک پرسمان بدون پایگاه داده
مهاجرت‌های شما همان طرح هستند
گذاشتن مقدارها، با امنیت
گونه‌ی هر جانگهدار
تولید توابع پرسمان
گونه‌ها
پایاها و متغیرها
تابع‌ها

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

همان ایده‌ی sqlc در زبان Go است، با این تفاوت که طرح از همان SQL که می‌نویسید می‌آید: دستورهای CREATE TABLE در مهاجرت‌های شما همان فهرست هستند، پس پرونده‌ی دومی نیست که باید هم‌گام نگه داشته شود.

چیزهایی که مردم را غافلگیر می‌کند:

گویش توصیه نیست. ? در SQLite و MySQL جانگهدار است و در PostgreSQL عملگر ساده، چون پستگرس جانگهدارهایش را با $1 شماره می‌زند؛ "name" همه‌جا نام نقل‌قول‌شده است جز در MySQL که رشته است؛ AUTOINCREMENT و AUTO_INCREMENT و GENERATED ... AS IDENTITY هر کدام به یک موتور تعلق دارند. همان گویشی را بدهید که واقعا روی آن اجرا می‌کنید.
بررسی نام‌ها را تنها وقتی پیدا می‌کند که دستور تجزیه شده باشد. گزارشی که خطای نگارشی دارد چیزی درباره‌ی ستون‌ها نمی‌گوید، پس نخست نگارش را درست کنید و دوباره اجرا کنید.
جدولی که ستون‌هایش معلوم نیست، از CREATE TABLE ... AS SELECT یا نمایی که بسته نتوانسته بخواند، باز می‌ماند: ستون‌های آن هرگز گمشده گزارش نمی‌شوند. بی‌خبری همیشه خوش‌خبری نیست.
اعمال دستورها را به ترتیب می‌خواند، پس نما باید پس از جدول‌هایی بیاید که از آن‌ها گزینش می‌کند، درست همان‌طور که در پایگاه داده هست.
متن عیب‌ها در هر دو حالت زبانی انگلیسی است؛ کدها یکی هستند، پس برنامه‌ی فارسی می‌تواند روی code تطبیق بدهد.
جانگهدارها یک وکتور<رشته> به شما می‌دهد که مالکش هستید: وکتور و رشته‌های داخلش را در پایان آزاد کنید.
سلام اجازه می‌دهد نام فاصله داشته باشد، SQL نه. SELECT نام خانوادگی FROM t یک ستون و یک نام جایگزین است، نه یک نام، و بی‌هیچ اعتراضی پذیرفته می‌شود - و چون نام‌های فارسی بیشتر دو واژه‌اند، دانستنش مهم است. در گیومه بگذاریدشان: SELECT "نام خانوادگی" FROM t.

از همین جا: یک قدم‌به‌قدم از طرح تا پرسمان بررسی‌شده

شش بخش پس از این، بسته را تکه‌تکه باز می‌کنند. این یکی آن را کنار هم می‌گذارد، به همان ترتیبی که در پروژه‌ای واقعی با آن روبه‌رو می‌شوید: پروژه‌ای که از پیش پایگاه داده دارد و انبوهی رشته‌ی پرسمان. برنامه‌ی زیر تمام مسیر است و همان‌طور که هست اجرا می‌شود - بدون سرور، بدون اتصال، بدون هیچ آماده‌سازی.

db-sql-tutorial.salam

واردسازی رشته
واردسازی دیتابیس.اس کیو ال

ناپایا طرح کلی := اس کیو ال.فهرست جداول {}

تابع عدد(ن: صحیح): رشته:
    برگشت رشته.از عدد(ن برگردان صحیح۶۴)
پایان

تابع گام(ش: صحیح، عنوان: رشته):
    سرچاپ ""
    سرچاپ "گام " + عدد(ش) + ": " + عنوان
پایان

تابع بیازما(پ: رشته):
    ناپایا ن := اس کیو ال.بررسی(پ، طرح کلی)
    اگر ن.ok و ن.warnings == ۰:
        سرچاپ "  درست   " + پ
    وگرنه:
        سرچاپ "  نادرست " + پ
        ناپایا ای := ۰
        تا ای < ن.items.طول():
            ع := ن.items.بگیر(ای)
            سرچاپ "          " + ع.code + " " + ع.message
            اگر وارونه رشته.خالی است(ع.help):
                سرچاپ "          " + ع.help
            پایان
            ای = ای + ۱
        پایان
    پایان
    اس کیو ال.آزادسازی گزارش(ن)
پایان

تابع ریشه:
    گام(۱، "طرحی که از پیش دارید")
    طرح کلی = اس کیو ال.فهرست تازه(اس کیو ال.گویش شماره(اس کیو ال.اس کیو لایت))
    دیرکن اس کیو ال.آزادسازی فهرست(طرح کلی)
    ناپایا ساخته := اس کیو ال.اعمال(طرح کلی، """
        CREATE TABLE نویسندگان (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            name TEXT NOT NULL,
            country TEXT
        );
        CREATE TABLE کتابها (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            author_id INTEGER NOT NULL,
            title TEXT NOT NULL,
            year INTEGER,
            price REAL
        );
    """)
    شمارش := "  " + عدد(اس کیو ال.شمار جدول(طرح کلی)) + " جدول خوانده شد، "
    سرچاپ شمارش + عدد(اس کیو ال.شمار ستون(طرح کلی، "کتابها")) + " ستون روی کتابها"
    اگر وارونه ساخته.ok:
        سرچاپ اس کیو ال.متن گزارش(ساخته)
    پایان
    اس کیو ال.آزادسازی گزارش(ساخته)

    گام(۲، "پرسمان هایی که از پیش دارید")
    بیازما("SELECT id, titles FROM کتابها WHERE author_id = ?")
    بیازما("SELECT ک.title, ن.nationality FROM کتابها ک JOIN نویسندگان ن ON ن.id = ک.author_id")
    بیازما("INSERT INTO کتابها (title) VALUES (?)")
    بیازما("SELECT id FROM کتابها WHERE year = 'recent'")
    بیازما("DELETE FROM کتابها")

    گام(۳، "همان پنج تا، درست شده")
    بیازما("SELECT id, title FROM کتابها WHERE author_id = ?")
    بیازما("SELECT ک.title, ن.country FROM کتابها ک JOIN نویسندگان ن ON ن.id = ک.author_id")
    بیازما("INSERT INTO کتابها (author_id, title) VALUES (?, ?)")
    بیازما("SELECT id FROM کتابها WHERE year = 2024")
    بیازما("DELETE FROM کتابها WHERE id = ?")

    گام(۴، "یک پرسمان چه می گیرد و چه می دهد")
    ناپایا ت := اس کیو ال.تحلیل کن("SELECT title, price FROM کتابها WHERE year > ?"، طرح کلی)
    سرچاپ "  یک " + اس کیو ال.نام دستور(ت.kind) + " روی " + ت.table
    پ := ت.params.بگیر(۰)
    سرچاپ "  می گیرد " + پ.column + " از گونه " + اس کیو ال.گونه سلام(پ.kind، پ.not_null)
    ناپایا ای := ۰
    تا ای < ت.results.طول():
        س := ت.results.بگیر(ای)
        سرچاپ "  می دهد " + س.name + " از گونه " + اس کیو ال.گونه سلام(س.kind، وارونه س.nullable)
        ای = ای + ۱
    پایان
    اس کیو ال.آزادسازی تحلیل(ت)

    گام(۵، "مقدارها با امنیت سر جایشان می نشینند")
    ناپایا مقدارها := اس کیو ال.مقدارهای تازه()
    اس کیو ال.افزودن متن(مقدارها، "O'Brien")
    اس کیو ال.افزودن عدد(مقدارها، ۱۳۶۷ برگردان صحیح۶۴)
    ناپایا خطا := اس کیو ال.گزارش {}
    پرشده := اس کیو ال.پرکردن("INSERT INTO کتابها (title, year) VALUES (?, ?)"، مقدارها، اس کیو ال.گویش شماره(اس کیو ال.اس کیو لایت)، خطا)
    سرچاپ "  " + پرشده
    اس کیو ال.آزادسازی گزارش(خطا)
    اس کیو ال.آزادسازی مقدارها(مقدارها)

    گام(۶، "یا بگذارید خودش کد را بنویسد")
    ناپایا ن۲ := اس کیو ال.گزارش {}
    ناپایا پرسمان ها := اس کیو ال.خواندن پرسمان ها("""
-- name: BooksByAuthor :many
SELECT id, title, year FROM "کتابها" WHERE author_id = ?;
"""، ن۲)
    کد := اس کیو ال.تولید کد("store"، پرسمان ها، طرح کلی، ن۲)
    سرچاپ کد
    اس کیو ال.آزادسازی پرسمان ها(پرسمان ها)
    اس کیو ال.آزادسازی گزارش(ن۲)
    برگشت ۰
پایان

خروجی گام 1: طرحی که از پیش دارید 2 جدول خوانده شد، 5 ستون روی کتابها گام 2: پرسمان هایی که از پیش دارید نادرست SELECT id, titles FROM کتابها WHERE author_id = ? SQL311 no column named "titles" in this statement did you mean "title"? نادرست SELECT ک.title, ن.nationality FROM کتابها ک JOIN نویسندگان ن ON ن.id = ک.author_id SQL311 "ن" has no column "nationality" نادرست INSERT INTO کتابها (title) VALUES (?) SQL315 "author_id" is NOT NULL with no default and this INSERT leaves it out add it to the column list and to every row نادرست SELECT id FROM کتابها WHERE year = 'recent' SQL330 "year" is int and this compares it with text a number goes here without quotes نادرست DELETE FROM کتابها SQL320 this DELETE has no WHERE clause and removes every row add a WHERE clause, or use TRUNCATE when that is what you mean گام 3: همان پنج تا، درست شده درست SELECT id, title FROM کتابها WHERE author_id = ? درست SELECT ک.title, ن.country FROM کتابها ک JOIN نویسندگان ن ON ن.id = ک.author_id درست INSERT INTO کتابها (author_id, title) VALUES (?, ?) درست SELECT id FROM کتابها WHERE year = 2024 درست DELETE FROM کتابها WHERE id = ? گام 4: یک پرسمان چه می گیرد و چه می دهد یک select روی کتابها می گیرد year از گونه option.Option<i64> می دهد title از گونه str می دهد price از گونه option.Option<f64> گام 5: مقدارها با امنیت سر جایشان می نشینند INSERT INTO کتابها (title, year) VALUES ('O''Brien', 1367) گام 6: یا بگذارید خودش کد را بنویسد package store import db import db.sql import mem import option struct BooksByAuthorRow: pub id: i64 = 0 as i64 pub title: str = "" pub year: option.Option<i64> = option.None() as option.Option<i64> end func fill_query(c: dyn db.Connection, raw: str, a: sql.Args): str: mut rep := sql.Report {} out := sql.Fill(raw, a, sql.DialectNamed(c.Kind()), rep) sql.FreeReport(rep) ret out end pub func BooksByAuthor(c: dyn db.Connection, author_id: i64): Vector<BooksByAuthorRow>: mut a := sql.NewArgs() sql.AddInt(a, author_id) q := fill_query(c, "SELECT id, title, year FROM \"کتابها\" WHERE author_id = ?", a) sql.FreeArgs(a) mut rows := Vector {} as Vector<BooksByAuthorRow> r := c.Query(q) if r.Ok(): until r.Next(): mut out := BooksByAuthorRow {} out.id = r.Int64(0) out.title = r.Text(1) if r.IsNull(2): out.year = option.None() as option.Option<i64> else: out.year = option.Some(r.Int64(2)) end rows.push(out) end r.Close() end mem.Free(q as void*) ret rows end

گام ۱ تنها آماده‌سازی موجود است. برای این بسته توصیف طرح نمی‌نویسید؛ همان دستورهای CREATE TABLE که دارید را به آن می‌دهید. اعمال را به ترتیب روی پرونده‌های مهاجرت‌تان بگذارید و فهرست همان طرحی می‌شود که برنامه واقعا روی آن اجرا می‌شود.

گام ۲ همان چیزی است که برایش آمده‌اید. پنج پرسمان از آن‌هایی که در هر کدی پیدا می‌شوند، و پنج شکل متفاوت از غلط بودن: ستونی که به اشتباه جمع نوشته شده، ستونی که به جدول دیگرِ پیوند تعلق دارد، INSERT‌ای که ستون NOT NULL بی‌پیش‌فرض را جا انداخته، عددی که با واژه‌ای در گیومه مقایسه شده، و DELETE‌ای بدون WHERE. هر پنج تا بدون پایگاه داده پیدا می‌شوند و هر کدام می‌گویند چه باید کرد. آخری هشدار است نه خطا، چون گاهی پاک کردن کل جدول همان قصد است - نکته این است که شما در بازبینی تصمیم بگیرید، نه ساعت دو بامداد.

گام ۳ همان پنج تا است، درست شده، و می‌ارزد پیش از خواندن بقیه، یک بار پرسمان‌های خودتان را از این دو گام بگذرانید. سریع‌ترین راه همان دستور است: salam sql check src --schema=db هم پرونده‌های .sql را می‌خواند و هم SQL داخل پرونده‌های .salam را.

گام ۴ جایی است که دیگر یک بازبین ساده نیست. وقتی نام‌ها پیدا شدند، گونه‌ها هم می‌آیند: جانگهدار option.Option<i64> است چون year می‌تواند خالی باشد، و title یک str ساده است چون ستونش NOT NULL است. این همان امضایی است که کدتان باید داشته باشد، برگرفته از طرح نه از حافظه.

گام ۵ جلوی قدیمی‌ترین اشکال دنیا را می‌گیرد. پرکردن مقدارها را با نقل‌قولی که موتور می‌خواهد داخل پرسمان می‌نویسد - ببینید با آپاستروف در O'Brien چه می‌کند - و چون پرسمان نخست واکافت شده، ?ای که داخل یک رشته نشسته دست‌نخورده می‌ماند.

گام ۶ بخشی است که می‌توانید دیگر با دست ننویسید. یک پرسمان را با نام و گونه حاشیه‌نویسی کنید و تابع تولیدشده همان پارامترها و همان ساختار ردیفی را دارد که گام ۴ در آورده بود. با salam sql generate queries --schema=db --output=gen/store.salam اجرایش کنید.

دو چیز را با خودتان ببرید. طرح همان دستورهای ساختاری است که از پیش دارید، پس هیچ‌چیز نمی‌تواند از آن جا بماند. و همه‌ی این بررسی‌ها پیش از اجرای برنامه رخ می‌دهند، که تنها زمانی است که اشتباه در یک پرسمان ارزان است.

خواندن یک پرسمان بدون پایگاه داده

بازبینی یک دستور، یا یک متن کامل از دستورهای جدا شده با ;، را تجزیه می‌کند و یک گزارش برمی‌گرداند. ن.ok به محض اینکه خطایی باشد نادرست است؛ متن گزارش همه‌ی فهرست را همان‌طور که یک کامپایلر می‌نویسد نشان می‌دهد، با خط و ستون و پیام و یک خط راهنما. بیشتر قاعده‌های گویش همین‌جا هستند: یک رشته برای SQLite درست است و برای PostgreSQL غلط، و گزارش می‌گوید کدام بخشش را عوض کنید.

db-sql-guide-lint.salam

واردسازی دیتابیس.اس کیو ال

تابع گزارش(عنوان: رشته، پرسمان: رشته، گ: اس کیو ال.گویش):
    ناپایا ن := اس کیو ال.بازبینی(پرسمان، گ)
    اگر ن.ok:
        سرچاپ عنوان، "درست"
    وگرنه:
        سرچاپ عنوان، اس کیو ال.متن گزارش(ن)
    پایان
    اس کیو ال.آزادسازی گزارش(ن)
پایان

تابع ریشه:
    لایت := اس کیو ال.گویش شماره(اس کیو ال.اس کیو لایت)
    مای := اس کیو ال.گویش شماره(اس کیو ال.مای اس کیو ال)
    پست := اس کیو ال.گویش شماره(اس کیو ال.پستگرس)

    گزارش("پرسمان ساده: "، "SELECT id, name FROM users WHERE id = ?"، لایت)
    گزارش("نیمه کاره:   "، "SELECT id FROM users WHERE"، لایت)
    گزارش("نشانگر غلط:  "، "SELECT id FROM users WHERE id = ?"، پست)
    گزارش("ویژه پستگرس:"، "SELECT id FROM users WHERE name ILIKE 'a%'"، مای)
    گزارش("ویژه مای:    "، "CREATE TABLE t (id INT AUTO_INCREMENT)"، لایت)
    گزارش("ویرگول فارسی:"، "SELECT id، name FROM users"، لایت)

    سرچاپ "شمار جانگهدار:"، اس کیو ال.شمار پارامتر("UPDATE users SET name = ?, age = ? WHERE id = ?"، لایت)
    برگشت ۰
پایان

خروجیپرسمان ساده: درست نیمه کاره: error[SQL105] 1:27: expected a value, found the end of the statement help: a column name, a literal, a function call or a placeholder goes here نشانگر غلط: error[SQL201] 1:33: '?' is not a placeholder in postgres help: postgres numbers its placeholders: $1, $2 ویژه پستگرس: error[SQL205] 1:33: ILIKE is postgres only help: use LOWER(x) LIKE LOWER(y), or LIKE on a case-insensitive column ویژه مای: error[SQL211] 1:24: AUTO_INCREMENT is a mysql keyword help: sqlite spells it AUTOINCREMENT ویرگول فارسی: error[SQL005] 1:10: an Arabic comma '،' is not SQL punctuation help: write ',' instead شمار جانگهدار: 3

کامپایلر همین بررسی‌ها را به شکل یک دستور هم دارد، پس می‌توان یک پروژه‌ی کامل را بدون نوشتن برنامه‌ای برایش بررسی کرد: salam sql check src --schema=db پرونده‌های .sql زیر src را می‌خواند، و رشته‌های SQL داخل پرونده‌های .salam آن را، و هر کدام را با جایگاهشان در منبع سلام گزارش می‌کند. بدون --dialect هر پرونده‌ی سلام با همان موتوری خوانده می‌شود که واردسازی کرده، پس درختی که db/sqlite و db/mysql را با هم دارد بدون هیچ گزینه‌ای درست بررسی می‌شود. پرسمانی که تکه‌تکه ساخته شده - با + یا .concat چسبانده شده، یا هر رشته‌ای که تنها ایرادش این است که در میانه تمام می‌شود - تکه است نه دستور، پس شمرده و رد می‌شود و خطای نگارشی گزارش نمی‌شود. شمارش در خط پایانی می‌آید، پس هیچ‌چیز بی‌صدا بررسی‌نشده نمی‌ماند؛ تکه بودن خودش دلیل دیگری است برای بستن مقدارها به شکل جانگهدار به جای چسباندنشان به متن.

هر عیب یک کد دارد. SQL0xx واکافتی است، SQL1xx نگارشی، SQL2xx قاعده‌ی گویش و SQL3xx نام یا شماری که با طرح نمی‌خواند. وقتی می‌خواهید یک چیز خاص را بپذیرید روی کد تطبیق بدهید؛ هرگز روی پیام تطبیق ندهید.

مهاجرت‌های شما همان طرح هستند

اعمال دستورهای ساختار را روی یک فهرست جداول اجرا می‌کند: CREATE TABLE جدولی را با ستون‌ها و گونه‌هایشان و NOT NULL و PRIMARY KEY آن‌ها می‌افزاید، ALTER TABLE می‌افزاید و حذف و تغییر نام می‌کند، DROP برمی‌دارد و CREATE VIEW ستون‌های نما را ثبت می‌کند. همان رشته‌هایی را که به دیتابیس.افزودن مهاجرت می‌دهید به آن بدهید و فهرست همان طرحی می‌شود که برنامه واقعا دارد.

db-sql-guide-catalog.salam

واردسازی دیتابیس.اس کیو ال

ناپایا طرح جدول ها := اس کیو ال.فهرست جداول {}

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

تابع ریشه:
    طرح جدول ها = اس کیو ال.فهرست تازه(اس کیو ال.گویش شماره(اس کیو ال.اس کیو لایت))
    دیرکن اس کیو ال.آزادسازی فهرست(طرح جدول ها)

    ناپایا ساخته := اس کیو ال.اعمال(طرح جدول ها، """
        CREATE TABLE users (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            email TEXT NOT NULL,
            name TEXT
        );
        CREATE TABLE orders (
            id INTEGER PRIMARY KEY,
            user_id INTEGER NOT NULL,
            total REAL NOT NULL
        );
    """)
    سرچاپ "طرح خوانده شد:"، ساخته.ok، " جدول ها:"، اس کیو ال.شمار جدول(طرح جدول ها)
    اس کیو ال.آزادسازی گزارش(ساخته)

    بررسی("SELECT u.email, o.total FROM users u JOIN orders o ON o.user_id = u.id WHERE u.id = ?")
    بررسی("SELECT id, mail FROM users")
    بررسی("SELECT id FROM user")
    بررسی("INSERT INTO users (name) VALUES (?)")
    بررسی("DELETE FROM orders")
    برگشت ۰
پایان

خروجیطرح خوانده شد: true جدول ها: 2 درست SELECT u.email, o.total FROM users u JOIN orders o ON o.user_id = u.id WHERE u.id = ? نادرست SELECT id, mail FROM users error[SQL311] 1:12: no column named "mail" in this statement help: did you mean "email"? نادرست SELECT id FROM user error[SQL317] 1:16: no table named "user" help: did you mean "users"? نادرست INSERT INTO users (name) VALUES (?) error[SQL315] 1:1: "email" is NOT NULL with no default and this INSERT leaves it out help: add it to the column list and to every row نادرست DELETE FROM orders warning[SQL320] 1:1: this DELETE has no WHERE clause and removes every row help: add a WHERE clause, or use TRUNCATE when that is what you mean

با یک فهرست، بررسی نام‌ها را پیدا می‌کند: ستون یا جدول ناشناخته خطا است و نزدیک‌ترین نام واقعی پیشنهاد می‌شود، ستونی که دو جدول پیوندخورده هر دو دارند تا وقتی مشخصش نکنید خطا است، INSERT برابر فهرست ستون‌ها و برابر ستون‌هایی که NOT NULL بدون مقدار پیش‌فرض هستند بررسی می‌شود، و UPDATE یا DELETE بدون WHERE هشدار است، چون تقریبا هرگز منظور همین نبوده.

گونه‌هایی هم که در دست دارد می‌خواند: مقایسه‌ی ستون عددی با مقداری در گیومه که عدد نیست روی SQLite و MySQL هشدار است، چون آنجا بی‌صدا هیچ‌وقت برابر نمی‌شود یا بی‌صدا صفر می‌شود، و روی PostgreSQL خطا است چون نمی‌پذیردش؛ ستونی در فهرست نتیجه‌ی پرسمان GROUP BY که نه گروه شده و نه تجمیع، روی PostgreSQL خطا و جای دیگر هشدار است، با همان استثنایی که خود آن موتورها می‌گذارند: گروه کردن روی تمام کلید اصلی یک جدول بقیه‌ی ستون‌های همان جدول را تعیین می‌کند، پس آن‌ها بی‌اشکال هستند؛ و USING (col) در هر دو سمت پیوند بررسی می‌شود. زیرپرسمانی که برای مقایسه‌ای که در آن نشسته شمار ستون نادرستی برمی‌گرداند، ORDER BY 3 وقتی دستور دو ستون برمی‌گرداند، LIMIT که عدد نیست، تجمیع در WHERE به جای HAVING، ستونی که در یک SET دو بار مقدار می‌گیرد، و دو ستون نتیجه با یک نام جایگزین هم گزارش می‌شوند.

گذاشتن مقدارها، با امنیت

هر سه راه‌انداز SQL دستور آماده ندارند - تنها db/sqlite است که Prepare و Bind* دارد - پس کدی که باید روی MySQL یا PostgreSQL اجرا شود دست آخر مقدارها را با دست به SQL می‌چسباند، و همین‌جاست که اشتباه در نقل‌قول تبدیل به تزریق می‌شود. پرکردن همین یک کار را درست انجام می‌دهد: پرسمان را واکافت می‌کند، پس می‌داند کدام ? جانگهدار است و کدام نویسه‌ای داخل یک رشته، می‌سنجد که شمار مقدارها بخواند، و هر مقدار را همان‌طور که گویش می‌خواهد می‌نویسد.

db-sql-guide-fill.salam

واردسازی دیتابیس.اس کیو ال

تابع نمایش(پرسمان: رشته، م: اس کیو ال.مقدارها، گ: اس کیو ال.گویش):
    ناپایا ن := اس کیو ال.گزارش {}
    خروجی := اس کیو ال.پرکردن(پرسمان، م، گ، ن)
    اگر ن.ok:
        سرچاپ خروجی
    وگرنه:
        سرچاپ اس کیو ال.متن گزارش(ن)
    پایان
    اس کیو ال.آزادسازی گزارش(ن)
پایان

تابع ریشه:
    لایت := اس کیو ال.گویش شماره(اس کیو ال.اس کیو لایت)
    پست := اس کیو ال.گویش شماره(اس کیو ال.پستگرس)

    ناپایا ردیف := اس کیو ال.مقدارهای تازه()
    اس کیو ال.افزودن متن(ردیف، "O'Brien")
    اس کیو ال.افزودن عدد(ردیف، ۴۱ برگردان صحیح۶۴)
    اس کیو ال.افزودن منطقی(ردیف، درست)
    اس کیو ال.افزودن خالی(ردیف)
    نمایش("INSERT INTO users (name, age, paid, note) VALUES (?, ?, ?, ?)"، ردیف، لایت)
    نمایش("INSERT INTO users (name, age, paid, note) VALUES ($1, $2, $3, $4)"، ردیف، پست)
    اس کیو ال.آزادسازی مقدارها(ردیف)

    ناپایا حمله := اس کیو ال.مقدارهای تازه()
    اس کیو ال.افزودن متن(حمله، "x' OR '1'='1")
    نمایش("SELECT id FROM users WHERE name = ?"، حمله، لایت)
    اس کیو ال.آزادسازی مقدارها(حمله)

    ناپایا یکی := اس کیو ال.مقدارهای تازه()
    اس کیو ال.افزودن عدد(یکی، ۷ برگردان صحیح۶۴)
    نمایش("SELECT id FROM notes WHERE body = '?' AND id = ?"، یکی، لایت)
    نمایش("SELECT id FROM users WHERE id = ? AND org = ?"، یکی، لایت)
    اس کیو ال.آزادسازی مقدارها(یکی)
    برگشت ۰
پایان

خروجیINSERT INTO users (name, age, paid, note) VALUES ('O''Brien', 41, 1, NULL) INSERT INTO users (name, age, paid, note) VALUES ('O''Brien', 41, TRUE, NULL) SELECT id FROM users WHERE name = 'x'' OR ''1''=''1' SELECT id FROM notes WHERE body = '?' AND id = 7 error[SQL400] 1:1: this query takes 2 values but got 1 help: add or remove an argument so the two agree

مقدار متنی در گیومه‌ی تک پیچیده می‌شود و هر گیومه‌ی داخلش دو برابر، و روی MySQL ممیز وارون هم دو برابر می‌شود، چون MySQL ممیز وارون را گریز می‌خواند و آن دو تای دیگر نه. مقدار منطقی روی SQLite و MySQL 1 یا 0 است و روی PostgreSQL TRUE یا FALSE؛ خالی NULL می‌شود؛ عددها ساده نوشته می‌شوند. '?' در پرسمان چهارم همان‌طور که بود می‌ماند، چیزی که جست‌وجو و جایگزینی ساده روی رشته اشتباه می‌گرفت.

این جایگزینی است، نه دستور آماده: پایگاه داده هنوز یک دستور کامل را تجزیه می‌کند و بازاستفاده‌ی نقشه‌ی اجرا نیست. جایی که راه‌انداز می‌تواند آماده و بسته کند، مانند sqlite، همان ابزار بهتری است. جایی که نمی‌تواند، این راه امن گذاشتن مقدارها است، و یک تابع بازبینی‌شده است به جای قاعده‌ی نقل‌قولی که در هر فراخوانی تکرار شود.

گونه‌ی هر جانگهدار

تحلیل کن هر کاری که بررسی می‌کند انجام می‌دهد و علاوه بر آن می‌گوید پرسمان چه می‌گیرد و چه برمی‌گرداند. هر پارامتر می‌گوید با کدام ستون، در کدام جدول، مقایسه شده و آن ستون چه گونه‌ای دارد؛ هر ستون نتیجه می‌گوید ستون با چه نامی برمی‌گردد، گونه‌اش چیست و می‌تواند خالی باشد یا نه. گونه سلام آن را به گونه‌ی سلام تبدیل می‌کند که مقدار را در آن می‌خوانید، پس LEFT JOIN به شما option.Option<i64> می‌دهد آنجا که پیوند درونی i64 می‌دهد.

db-sql-guide-analyze.salam

واردسازی دیتابیس.اس کیو ال

تابع شرح(پرسمان: رشته، طرح: اس کیو ال.فهرست جداول):
    ناپایا ت := اس کیو ال.تحلیل کن(پرسمان، طرح)
    سرچاپ پرسمان
    سرچاپ "  دستور:"، اس کیو ال.نام دستور(ت.kind)، "روی"، ت.table
    ناپایا ای := ۰
    تا ای < ت.params.طول():
        پ := ت.params.بگیر(ای)
        سرچاپ "  جانگهدار"، پ.ordinal، "ستون"، پ.column، "از گونه"، اس کیو ال.گونه سلام(پ.kind، پ.not_null)
        ای = ای + ۱
    پایان
    ناپایا جی := ۰
    تا جی < ت.results.طول():
        س := ت.results.بگیر(جی)
        سرچاپ "  ستون"، س.name، "برمی گردد با گونه"، اس کیو ال.گونه سلام(س.kind، وارونه س.nullable)
        جی = جی + ۱
    پایان
    اس کیو ال.آزادسازی تحلیل(ت)
پایان

تابع ریشه:
    ناپایا طرح := اس کیو ال.فهرست تازه(اس کیو ال.گویش شماره(اس کیو ال.اس کیو لایت))
    دیرکن اس کیو ال.آزادسازی فهرست(طرح)
    ناپایا ساخته := اس کیو ال.اعمال(طرح، """
        CREATE TABLE users (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            email TEXT NOT NULL,
            name TEXT,
            age INTEGER
        );
    """)
    اس کیو ال.آزادسازی گزارش(ساخته)

    شرح("SELECT id, name FROM users WHERE email = ? AND age > ?"، طرح)
    شرح("INSERT INTO users (email, name) VALUES (?, ?) RETURNING id"، طرح)
    برگشت ۰
پایان

خروجیSELECT id, name FROM users WHERE email = ? AND age > ? دستور: select روی users جانگهدار 1 ستون email از گونه str جانگهدار 2 ستون age از گونه option.Option<i64> ستون id برمی گردد با گونه i64 ستون name برمی گردد با گونه option.Option<str> INSERT INTO users (email, name) VALUES (?, ?) RETURNING id دستور: insert روی users جانگهدار 1 ستون email از گونه str جانگهدار 2 ستون name از گونه option.Option<str> ستون id برمی گردد با گونه i64

همین اندازه بس است تا کد اتصال یک پرسمان را بسازید، یا در یک آزمون مطمئن شوید پرسمان هنوز همان چیزی را می‌گیرد و برمی‌گرداند که کد دور و برش باور دارد. جانگهدارها به ترتیب ظاهر شدن شماره می‌خورند، همان ترتیبی که راه‌انداز آن‌ها را می‌بندد؛ برای PostgreSQL شماره همان عددی است که در $n نوشته شده و جا افتادن یکی از آن شماره‌ها خودش خطا است.

کار	ابزار
این SQL برای موتور من درست نوشته شده؟	`بازبینی`
چند مقدار می‌بندد؟	`شمار پارامتر`، `جانگهدارها`
خواندن طرح	`فهرست تازه`، `اعمال`
جدول‌ها و ستون‌ها وجود دارند؟	`بررسی`
چه می‌گیرد و چه برمی‌گرداند؟	`تحلیل کن`
کدام گونه‌ی سلام یک ستون را می‌خواند؟	`گونه سلام`
گذاشتن مقدارها در SQL با امنیت	`مقدارهای تازه`، `افزودن ...`، `پرکردن`
گشتن در طرح	`شمار جدول`، `نام جدول`، `شمار ستون`، `ستون شماره`، `جدول دارد`، `ستون دارد`

تولید توابع پرسمان

وقتی طرح و تحلیل در دست است، گام آخر مکانیکی می‌شود، پس بسته خودش انجامش می‌دهد: یک پرونده‌ی .sql را همان‌طور که sqlc می‌خواهد حاشیه‌نویسی کنید و تولید کد کد سلام آن را می‌نویسد - یک ساختار ردیف برای هر پرسمان، یک تابع گونه‌دار برای هر پرسمان، و هر کدام هنگام تولید برابر طرح بررسی می‌شود.

db-sql-guide-generate.salam

واردسازی دیتابیس.اس کیو ال

تابع ریشه:
    ناپایا طرح := اس کیو ال.فهرست تازه(اس کیو ال.گویش شماره(اس کیو ال.اس کیو لایت))
    دیرکن اس کیو ال.آزادسازی فهرست(طرح)
    ناپایا ساخته := اس کیو ال.اعمال(طرح، """
        CREATE TABLE users (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            email TEXT NOT NULL,
            name TEXT
        );
    """)
    اس کیو ال.آزادسازی گزارش(ساخته)

    پرسمان ها := """
-- name: GetUser :one
SELECT id, email, name FROM users WHERE email = ?;

-- name: CreateUser :exec
INSERT INTO users (email, name) VALUES (?, ?);
"""
    ناپایا ن := اس کیو ال.گزارش {}
    ناپایا خوانده := اس کیو ال.خواندن پرسمان ها(پرسمان ها، ن)
    سرچاپ "پرسمان ها:"، خوانده.طول()
    کد := اس کیو ال.تولید کد("store"، خوانده، طرح، ن)
    اگر ن.ok:
        سرچاپ کد
    وگرنه:
        سرچاپ اس کیو ال.متن گزارش(ن)
    پایان
    اس کیو ال.آزادسازی پرسمان ها(خوانده)
    اس کیو ال.آزادسازی گزارش(ن)
    برگشت ۰
پایان

خروجیپرسمان ها: 2 package store import db import db.sql import mem import option struct GetUserRow: pub id: i64 = 0 as i64 pub email: str = "" pub name: option.Option<str> = option.None() as option.Option<str> end func fill_query(c: dyn db.Connection, raw: str, a: sql.Args): str: mut rep := sql.Report {} out := sql.Fill(raw, a, sql.DialectNamed(c.Kind()), rep) sql.FreeReport(rep) ret out end pub func GetUser(c: dyn db.Connection, email: str, ok &: bool): GetUserRow: mut a := sql.NewArgs() sql.AddText(a, email) q := fill_query(c, "SELECT id, email, name FROM users WHERE email = ?", a) sql.FreeArgs(a) mut out := GetUserRow {} ok = false r := c.Query(q) if r.Ok(): if r.Next(): out.id = r.Int64(0) out.email = r.Text(1) if r.IsNull(2): out.name = option.None() as option.Option<str> else: out.name = option.Some(r.Text(2)) end ok = true end r.Close() end mem.Free(q as void*) ret out end pub func CreateUser(c: dyn db.Connection, email: str, name: str): bool: mut a := sql.NewArgs() sql.AddText(a, email) sql.AddText(a, name) q := fill_query(c, "INSERT INTO users (email, name) VALUES (?, ?)", a) sql.FreeArgs(a) done := c.Exec(q) == 0 mem.Free(q as void*) ret done end

گونه‌ها اینها هستند: :one (نخستین ردیف، با پارامتر خروجی ok &: bool)، :many (یک وکتور از ردیف‌ها)، :exec (یک منطقی) و :execrows (شمار ردیف‌های تغییریافته). نام پارامترها از ستونی می‌آید که هر جانگهدار با آن مقایسه شده و گونه‌شان هم از همان؛ ستونی که می‌تواند خالی باشد به شکل option.Option<T> برمی‌گردد و با IsNull خوانده می‌شود. پرسمانی که با طرح نخواند تولید را متوقف می‌کند و نام پرسمان در پیام می‌آید، پس غلط املایی هرگز به پرونده‌ی تولیدشده نمی‌رسد.

دستورش این است: salam sql generate queries --schema=db --output=gen/store.salam --package=store. پرونده‌ی تولیدشده یک dyn db.Connection می‌گیرد، پس یک مجموعه تابع به SQLite و MySQL و PostgreSQL خدمت می‌کند و نقل‌قول هر گویش را هنگام اجرا از c.Kind() برمی‌دارد.

گونه‌ها

پارامتر `Param`

ساختار پارامتر

یک جانگهدار، و ستونی که به آن بسته شده.

نام	انگلیسی	گونه	توضیح
marker	`marker`	`رشته = ""`	جانگهدار همان‌طور که نوشته شده: `?` یا `$2` یا `:name`.
ordinal	`ordinal`	`صحیح = 0`	جایش، از ۱؛ برای `$n` همان عدد است.
table	`table`	`رشته = ""`	جدول ستونی که با آن مقایسه شده، وقتی چنین ستونی بوده.
column	`column`	`رشته = ""`	ستونی که با آن مقایسه شده، وقتی چنین ستونی بوده.
kind	`kind`	`صحیح = 7`	گونه‌ی `TYPE_*` آن ستون، یا `نوع ناشناخته`.
not_null	`not_null`	`منطقی = نادرست`	درست وقتی آن ستون نمی‌تواند خالی باشد.

db-sql-Methods.salam

واردسازی دیتابیس.اس کیو ال

تابع ریشه:
    لایت := اس کیو ال.گویش شماره(اس کیو ال.اس کیو لایت)
    سرچاپ لایت.name، اس کیو ال.گویش نام("postgresql").name، اس کیو ال.گویش شماره(اس کیو ال.ماریادی بی).name

    ناپایا بد := اس کیو ال.بازبینی("SELECT id FROM t WHERE"، لایت)
    سرچاپ بد.ok، بد.errors، بد.warnings، بد.statements
    سرچاپ اس کیو ال.متن عیب(بد.items.بگیر(۰))
    اس کیو ال.آزادسازی گزارش(بد)

    سرچاپ اس کیو ال.شمار پارامتر("SELECT a FROM t WHERE b = ? AND c = ?"، لایت)
    ناپایا نشانه ها := اس کیو ال.جانگهدارها("SELECT a FROM t WHERE b = ? AND c = ?"، لایت)
    سرچاپ نشانه ها.طول()، نشانه ها.بگیر(۰)
    نشانه ها.آزادکن()

    ناپایا فهرست := اس کیو ال.فهرست تازه(لایت)
    ناپایا طرح := اس کیو ال.اعمال(فهرست، """
        CREATE TABLE users (id INTEGER PRIMARY KEY, email TEXT NOT NULL, age INTEGER);
    """)
    سرچاپ "طرح:"، طرح.ok، اس کیو ال.شمار جدول(فهرست)، اس کیو ال.نام جدول(فهرست، ۰)
    اس کیو ال.آزادسازی گزارش(طرح)
    سرچاپ اس کیو ال.جدول دارد(فهرست، "users")، اس کیو ال.ستون دارد(فهرست، "users"، "email")
    ستون یک := اس کیو ال.ستون شماره(فهرست، "users"، ۱)
    سرچاپ ستون یک.name، اس کیو ال.نام نوع(ستون یک.kind)، ستون یک.not_null

    ناپایا گم := اس کیو ال.بررسی("SELECT nope FROM users"، فهرست)
    سرچاپ اس کیو ال.متن گزارش(گم)
    اس کیو ال.آزادسازی گزارش(گم)

    ناپایا ت := اس کیو ال.تحلیل کن("SELECT id, age FROM users WHERE email = ?"، فهرست)
    سرچاپ اس کیو ال.نام دستور(ت.kind)، ت.table، ت.params.طول()، ت.results.طول()
    پ := ت.params.بگیر(۰)
    سرچاپ پ.marker، پ.ordinal، پ.table + "." + پ.column، اس کیو ال.گونه سلام(پ.kind، پ.not_null)
    س := ت.results.بگیر(۱)
    سرچاپ س.name، اس کیو ال.نام نوع(س.kind)، س.nullable
    اس کیو ال.آزادسازی تحلیل(ت)

    ناپایا مقدارها := اس کیو ال.مقدارهای تازه()
    اس کیو ال.افزودن عدد(مقدارها، ۳ برگردان صحیح۶۴)
    اس کیو ال.افزودن متن(مقدارها، "a'b")
    اس کیو ال.افزودن منطقی(مقدارها، نادرست)
    اس کیو ال.افزودن اعشار(مقدارها، ۲.۵)
    اس کیو ال.افزودن خالی(مقدارها)
    سرچاپ اس کیو ال.شمار مقدار(مقدارها)
    ناپایا خطا := اس کیو ال.گزارش {}
    پرشده := اس کیو ال.پرکردن("INSERT INTO t (a, b, c, d, e) VALUES (?, ?, ?, ?, ?)"، مقدارها، لایت، خطا)
    سرچاپ پرشده
    اس کیو ال.آزادسازی گزارش(خطا)
    اس کیو ال.آزادسازی مقدارها(مقدارها)

    اس کیو ال.آزادسازی فهرست(فهرست)
    برگشت ۰
پایان

خروجیsqlite postgres mariadb false 1 0 0 error[SQL105] 1:23: expected a value, found the end of the statement help: a column name, a literal, a function call or a placeholder goes here 2 2 ? طرح: true 1 users true true email text true error[SQL311] 1:8: no column named "nope" in this statement select users 1 2 ? 1 users.email str age int true 5 INSERT INTO t (a, b, c, d, e) VALUES (3, 'a''b', 0, 2.5, NULL)