Konfigurasi Datasource dalam Lucee: Rujukan Lengkap dan Penyelesaian Masalah

Konfigurasi Datasource dalam Lucee: Rujukan Lengkap dan Penyelesaian Masalah

Datasource dalam Lucee ialah definisi sambungan yang menghubungkan aplikasi anda dengan pangkalan data, dan ia menyimpan maklumat seperti kelas pemacu JDBC, hos, port, nama pangkalan data, nama pengguna dan kata laluan. Anda boleh mencipta datasource melalui tiga cara: Lucee Administrator (antara muka web), struktur this.datasources di dalam Application.cfc, atau fail .CFConfig.json untuk automasi. Artikel ini merangkumi ketiga-tiganya, diikuti dengan bahagian penyelesaian masalah untuk ralat yang biasa seperti "datasource tidak dijumpai".

Jika anda belum memasang Lucee, baca dahulu panduan cara memasang Lucee.

Bagaimana Lucee Mengurus Sambungan Pangkalan Data

Sebelum menulis sebarang konfigurasi, elok difahami cara Lucee mengendalikan sambungan. Lucee menggunakan Apache Commons Pool 2 untuk menguruskan kolam (pool) sambungan pangkalan data. Apabila pertanyaan dijalankan, Lucee meminta sambungan dari kolam, menjalankan pertanyaan, kemudian memulangkan sambungan itu semula ke kolam untuk digunakan oleh permintaan lain. Pendekatan ini mengelakkan kos membuka sambungan baharu untuk setiap operasi pangkalan data.

Lucee menyediakan tiga corak pengurusan sambungan yang akan kita bincangkan kemudian: sambungan berkongsi (pooled), sambungan eksklusif (exclusive), dan sambungan transaksi (transaction).

Cara 1: Mencipta Datasource melalui Lucee Administrator

Cara paling biasa untuk memulakan ialah melalui antara muka web Lucee Administrator:

1. Buka Lucee Administrator di /lucee/admin/web.cfm.
2. Navigasi ke Services, kemudian Datasource.
3. Isikan medan sambungan: Name (nama rujukan), Type (jenis pangkalan data, contohnya MySQL), Host, Port (3306 untuk MySQL), Database, Username dan Password.
4. Klik Create.

Setelah datasource dicipta, Lucee menyimpannya dalam konteks web atau pelayan bergantung pada tempat anda menciptanya. Perlu diingat bahawa datasource yang dicipta melalui antara muka ini tidak menetapkan bundleName dan bundleVersion, kerana Lucee menggunakan pemacu yang sudah dipasang secara lalai. Satu petua berguna: jika anda mahukan templat konfigurasi Application.cfc untuk tetapan yang betul, pasang dahulu sambungan MySQL, cipta datasource dalam admin, dan lihat templat yang dipaparkan di bahagian bawah halaman butiran datasource.

Cara 2: Mendefinisikan Datasource dalam Application.cfc

Untuk aplikasi yang boleh dialihkan antara persekitaran, definisikan datasource terus dalam Application.cfc. Ini memastikan tetapan sambungan mengikut kod aplikasi anda dan bukannya bergantung pada konfigurasi pelayan secara manual.

component {
    this.name = "AplikasiSaya";

    this.datasources["mydb"] = {
        class: "com.mysql.cj.jdbc.Driver",
        bundleName: "com.mysql.cj",
        bundleVersion: "9.5.0",
        connectionString: "jdbc:mysql://localhost:3306/mydb?characterEncoding=UTF-8&serverTimezone=UTC",
        username: "dbuser",
        password: "dbpass",
        connectionLimit: -1,
        liveTimeout: 15,
        validate: false
    };

    this.datasource = "mydb";
}

Beberapa tetapan pilihan yang perlu anda tahu: connectionLimit mengawal bilangan maksimum sambungan (lalai -1 bermaksud tanpa had), liveTimeout ialah tempoh minit sambungan tidak aktif dibenarkan (lalai -1), dan validate menentukan sama ada sambungan disahkan sebelum digunakan (lalai false). Pastikan nama datasource dalam kod anda sepadan dengan tepat, termasuk huruf besar kecil, kerana Lucee memadankan nama secara tepat.

Cara 3: Mengautomasikan dengan .CFConfig.json

Untuk persekitaran yang diautomasikan seperti Docker atau CI/CD, anda boleh menyimpan datasource dalam fail .CFConfig.json. Format ini digunakan oleh alat CFConfig dan boleh diimport oleh Lucee ketika pelayan bermula.

{
  "datasources": {
    "mydb": {
      "class": "com.mysql.cj.jdbc.Driver",
      "bundleName": "com.mysql.cj",
      "bundleVersion": "9.5.0",
      "connectionString": "jdbc:mysql://localhost:3306/mydb?characterEncoding=UTF-8&serverTimezone=UTC",
      "username": "dbuser",
      "password": "dbpass",
      "requestExclusive": false
    }
  }
}

Alat CFConfig juga menyediakan antara muka baris arahan untuk mengurus datasource tanpa membuka Lucee Administrator. Contohnya, cfconfig datasource list untuk menyenaraikan datasource, dan cfconfig datasource save name=myDSN dbdriver=mysql host=localhost port=3306 database=myDB untuk mencipta satu. Pilihan dbdriver yang sah termasuk MySQL, MSSQL, MSSQL2 (pemacu jTDS), PostgreSql, Oracle dan Other untuk URL JDBC tersuai.

Mendapatkan Driver JDBC Terus dari Maven

Sejak Lucee 6.1, anda tidak perlu memasang sambungan MySQL terlebih dahulu untuk mendapatkan pemacu. Anda boleh merujuk pemacu terus dari repositori Maven dengan menetapkan bundleName dan bundleVersion dalam definisi datasource anda, contohnya com.mysql.cj dengan versi tertentu. Ini membolehkan anda menggunakan versi pemacu terbaharu dari Maven walaupun belum ada sambungan Lucee untuknya.

Satu peringatan penting: apabila anda mencipta datasource melalui Lucee Administrator, Lucee tidak akan menetapkan bundleName dan bundleVersion kerana ia menggunakan pemacu yang dipasang secara lalai. Untuk mengambil terus dari Maven, anda mesti menambah maklumat bundle itu sendiri dalam definisi anda.

Tiga Jenis Sambungan dalam Lucee

Sambungan eksklusif diaktifkan dengan menetapkan requestExclusive kepada true. Gunakannya dengan berhati-hati kerana ia boleh menghabiskan kolam sambungan di bawah beban tinggi. Sambungan transaksi tidak memerlukan konfigurasi tambahan kerana ia berlaku secara automatik dalam blok transaction.

Menggunakan Datasource dalam Kod

Setelah datasource ditakrifkan, anda boleh merujuk namanya dalam pertanyaan menggunakan tag cfquery atau fungsi queryExecute:

<cfquery name="qPengguna" datasource="mydb">
    SELECT id, nama
    FROM pengguna
    WHERE emel = <cfqueryparam value="#form.emel#" cfsqltype="cf_sql_varchar">
</cfquery>

Fungsi queryExecute menawarkan cara yang sama dalam sintaks skrip, dan menerima parameter sebagai array:

var qPengguna = queryExecute(
    "SELECT id, nama FROM pengguna WHERE emel = ?",
    [form.emel],
    { datasource: "mydb" }
);

Dalam kedua-dua bentuk, gunakan parameter terikat dan bukannya mencantumkan nilai terus ke dalam rentetan SQL. Sentiasa gunakan cfqueryparam untuk melindungi pertanyaan anda daripada suntikan SQL. Butiran lanjut dalam artikel cfquery dan cfqueryparam.

Penyelesaian Masalah: Ralat Datasource yang Biasa

"datasource [nama] doesn't exist"

Ini ralat yang paling kerap ditemui pembangun Lucee baharu. Mesej penuh biasanya menyertakan senarai nama datasource yang tersedia, contohnya "available datasource names are [...]". Ralat ini bermakna nama yang dirujuk dalam kod anda belum ditakrifkan. Punca lazim termasuk:

• Nama tidak sepadan dengan tepat, kerana Lucee memadankan nama datasource secara tepat termasuk huruf besar kecil.
• Datasource ditakrifkan dalam Application.cfc tetapi nama application atau konteks tidak sepadan, atau Application.cfm lama masih bercanggah.
• Datasource dicipta dalam konteks pelayan (server) tetapi dirujuk dari konteks web, atau sebaliknya.
• Anda lupa menyimpan atau mengimport fail .CFConfig.json.

Semak semula ejaan dan skop datasource anda, kemudian sahkan ia muncul dalam Lucee Administrator.

"Connection timed out" atau sambungan gagal

Biasanya bermaksud hos atau port salah, atau pelayan pangkalan data tidak boleh dicapai. Dalam Docker, gunakan nama perkhidmatan rangkaian (contohnya nama bekas pangkalan data) dan bukannya localhost, kerana localhost merujuk kepada bekas Lucee itu sendiri.

Datasource ditakrifkan tetapi pertanyaan masih gagal

Pastikan pemacu JDBC tersedia. Jika anda menggunakan pendekatan Maven, pastikan bundleName dan bundleVersion ditetapkan. Jika menggunakan sambungan MySQL, pastikan sambungan org.lucee:mysql-jdbc-extension dipasang. Untuk aplikasi yang bergantung kepada Hibernate, rujuk pengenalan ORM dan Hibernate.

Soalan Lazim (FAQ)

Kenapa Lucee kata "datasource tidak dijumpai"? Ini bermakna nama datasource yang dirujuk dalam kod belum ditakrifkan dalam konteks yang betul. Semak ejaan, huruf besar kecil, dan sama ada ia dicipta dalam konteks web atau pelayan.

Bagaimana cara sambungkan Lucee ke MySQL? Guna kelas pemacu com.mysql.cj.jdbc.Driver dengan rentetan sambungan jdbc:mysql://host:3306/database. Anda boleh menciptanya melalui Administrator, this.datasources dalam Application.cfc, atau .CFConfig.json.

Apakah port lalai MySQL? Port lalai MySQL ialah 3306. Jika anda menukar port, pastikan ia sepadan dalam rentetan sambungan datasource anda.

Apakah perbezaan antara datasource web dan datasource pelayan? Datasource pelayan (server) boleh dikongsi oleh semua aplikasi pada pelayan itu, manakala datasource web terhad kepada satu aplikasi atau konteks. Rujuk panduan memahami Application.cfc untuk butiran skop.

Bolehkah saya mengautomasikan konfigurasi datasource dalam Docker? Ya. Letakkan fail .CFConfig.json atau definisikan this.datasources dalam Application.cfc, dan ia akan dikenakan secara automatik apabila bekas bermula. Lihat artikel deploy Lucee dengan Docker.

Sumber

• Database Connection Management in Lucee, docs.lucee.org
• Get Datasource Drivers Directly from Maven, docs.lucee.org
• CFConfig, Ortus Solutions
• Manage Datasources, CFConfig Documentation
• Lucee on GitHub