Filament Database Laravel Package

Getting Started

This release turns the package into a fuller database console for Filament panels: a connection overview, a per-connection SQL workspace, grouped schema/transfer/destructive actions, and hardened import/export paths. Start by reading the published config file — that is where nearly every behavior discussed in 3.1.0 lives.

Minimal setup:

1. Require the package and run the install/publish command to get config/<package>.php.
2. Define your connections in config (or reuse config/database.php connections) and restrict which ones are exposed per environment.
3. Register the plugin/page in your Panel provider, ideally only for local and staging (or behind a dedicated admin panel with MFA).
4. Add authorization: a Gate/policy that decides who may view a connection, who may run SQL, and who may perform destructive actions. Do not ship this to production without an explicit gate.
5. Set max_export_rows and the SQL timeouts before your first real use.

First use case: point it at a staging database, browse tables through the connection overview, and use the SQL workspace for read-only SELECTs while debugging. That gives you value with the least risk, and it exercises the new connection-scoped history and read-only controls before you grant anyone write or destructive access.

Implementation Patterns

Environment- and role-scoped panels. The most common day-to-day pattern is one panel for local/staging with broad access and a separate, tightly gated panel (or no registration at all) for production. Keep the connection list in config per environment so a production deploy cannot accidentally surface a prod connection in the dev panel.

Connection-first workflow. With the new connection-level overview, structure your team's habits around "pick connection → browse schema → open SQL workspace." Because SQL history is now scoped to its connection and cleared from the view when you switch, treat the workspace as a per-connection scratchpad rather than a shared log. If you need durable query history, persist it yourself.

Read-only SQL as the default posture. The 3.1.0 read-only path runs under database read-only controls on supported drivers, with a configurable server-side timeout on PostgreSQL, MySQL, and MariaDB. Use this as the everyday mode for support/debugging staff, and reserve write-capable SQL for a super-admin gate. Pair it with a database user that is itself read-only — the feature is a control, not a replacement for least-privilege credentials.

Exports as a bounded, deliberate operation. Exports cap at 10,000 rows via max_export_rows. For analyst handoffs, raise the cap per environment or per request rather than globally. For anything that must round-trip exactly, use JSON or SQL export: CSV output now prefixes common spreadsheet formula cells so Excel renders them as text, which is correct for safety but changes the literal values.

CSV imports for seeding and bulk loads. Imports process in 500-row chunks to bound memory. Use them for reference data and staging seeds, and design your import files so a partial failure is recoverable (idempotent keys or a truncate-then-load step), since chunking means a mid-file failure leaves earlier chunks committed.

Grouped destructive actions. Transfer, schema, and destructive actions are now grouped with clearer warnings and empty states. Lean on those groupings in your runbooks: require a second operator for the destructive group, and document that empty states are expected (not broken) when a connection has no tables or no pending transfers.

Integration tips. Wrap the SQL page and destructive actions in your existing audit logging (user, connection, statement, timestamp) via model events or a middleware, since the package's own history is view-scoped. Cache connection metadata if your overview page gets slow against schemas with thousands of tables.

Gotchas and Tips

• The export cap fails quietly by design. A 10,000-row cap means large exports are truncated, not errored. Surface the configured cap in your UI copy and check row counts before handing files to stakeholders.
• CSV is now lossy for formula-like values. Cells beginning with =, +, -, or @ are prefixed so Excel treats them as text. If anyone diffs a CSV export against source data, they will see mismatches — use JSON/SQL export for verification and migrations.
• The SQL runner disables itself when table visibility restrictions are configured. This is a security feature, not a bug. If the workspace suddenly disappears after you add a visibility restriction, that is why; relax the restriction for trusted roles if you need both.
• Read-only enforcement depends on the driver. "Supported drivers" is doing real work in that sentence. Verify behavior on your exact driver and version, and confirm the server-side timeout is actually applied on PostgreSQL, MySQL, and MariaDB — a client-side timeout alone can leave a long query running server-side.
• Switching connections clears your SQL history view. Save anything you want to keep before switching; don't treat the workspace as a log.
• Chunked imports are not transactional. A 500-row chunk boundary is also a failure boundary. For all-or-nothing loads, import into a staging table and swap.
• Debugging access issues: check, in order, the panel registration (is the page registered in this environment?), the Gate, the connection allowlist in config, and then table visibility restrictions. Most "the page vanished" reports resolve at one of those four.
• Extension points: the config file is the primary surface (max_export_rows, connection definitions, timeout settings), followed by Filament policies and your own Gate definitions. Prefer config and gates over forking views; the UI changed noticeably in this release, so custom view overrides will be the first thing to break on upgrade.
• Upgrade note: there are no listed breaking changes in 3.1.0, but the SQL history scoping, export behavior, and read-only execution all change observable behavior. Smoke-test exports and any scripted SQL workspace usage after upgrading, and re-check the Filament 5.8.2 / CommonMark 2.10.3 pins match your app's constraints.