WP-692 Add runSql Blueprint step

[seanmorris]

What is this PR doing?

This PR addresses #692, by allowing developers to provide SQL via a resource. The queries will be run as part of the Blueprint setup process.

What problem is it solving?

This allows a user to execute SQL in the context of a playground instance to set up the WordPress install inside.

Currently, in production, there's no easy way to set up Playground for a complex plugin like WooCommerce:

Preparing an entire custom SQLite file is tedious and may not be portable between WordPress versions
The ability to import entire SQL files was requested by multiple developers. Let's support it, or something equally expressive and convenient.

How is the problem addressed?

The following notation is now valid for Blueprint steps:

Run a set of SQL queries:

{
  step: 'runSql',
  sql: {
    resource: "literal",
    contents: "DELETE FROM wp_posts;\nDELETE FROM wp_users;",
    name: "queries.sql",
  }
}

Testing Instructions

1. Checkout the project & run

nx run playground-website:dev

Click the following link: (ensure the port number matches)
http://localhost:5400/website-server/#{%22landingPage%22:%20%22/wp-admin/edit.php%22,%20%22steps%22:[{%22step%22:%20%22login%22,%20%22username%22:%20%22admin%22,%20%22password%22:%20%22password%22},%20{%20%22step%22:%22runSql%22,%20%22sql%22:%20{%20%22resource%22:%20%22literal%22,%20%22name%22:%20%22queries.sql%22,%20%22contents%22:%20%22DELETE%20FROM%20wp_posts%22%20}%20}]}

You should see that all posts have been deleted.

[adamziel]

@seanmorris instead of defining two steps that are only distinguished by how you provide input, let's define a single step and use resources to provide input from different sources – just like the installPlugin step does:

{
	step: 'runSql',
	sql: {
		"resource": "vfs",
		"path": "/wordpress/schema/_Schema.sql"
	}
}

[
	{
		step: 'runSql',
		sql: {
			"resource": "literal",
			"contents": "DELETE FROM wp_posts"
		}
	},
	{
		step: 'runSql',
		sql: {
			"resource": "literal",
			"contents": "DELETE FROM wp_users"
		}
	}
]

That second example feels a bit clunky. I'd say that's fine for starters. If that becomes a problem, though, we might introduce another resource like:

[
	{
		step: 'runSql',
		sql: {
			"resource": "array",
			"glue": "\n",
			"contents": [
				"DELETE FROM wp_users",
				"DELETE FROM wp_posts"
			]
		}
	}
]

[adamziel]

Capturing what @seanmorris noticed:

I actually noticed a bug with that late last night if you give it a string that doesn't end in a newline, it doesn't handle it right

[seanmorris]

Capturing what @seanmorris noticed:

I actually noticed a bug with that late last night if you give it a string that doesn't end in a newline, it doesn't handle it right

This has been fixed.

[dmsnell]

wanted to note that I appreciate the approach of handling each line at a time and reading in chunks from the file. there could be rather large database files and doing it line by line should avoid excessive peak memory use.

[adamziel]

Nice! This looks great, @seanmorris, thank you!

Two last things here would be:

• Adding a unit test. You can use https://github.com/WordPress/wordpress-playground/blob/trunk/packages/playground/blueprints/src/lib/steps/install-plugin.spec.ts for inspiration. WordPress currently isn’t loaded in these blueprint tests so you may need to mock $wpdb. To run the tests, you’d do nx test playground-blueprints or nx test playground-blueprints:vite --watch.
• Brushing up the PR description to provide more context for future visitors. Two usage examples would be nice alongside rationale for why this step is needed – it could be just copied over from Support SQL dump import (to enable complex setups, e.g. for WooCommerce) #692 and it would make the PR description self-contained. Also, actionable testing instructions would be really useful. This could be as simple as "click this localhost:5400/#{"steps": [... link and confirm the site title says potato" or "take the first usage example above, go to localhost:5400/, paste it after #, confirm X happened".

[seanmorris]

• Adding a unit test. You can use https://github.com/WordPress/wordpress-playground/blob/trunk/packages/playground/blueprints/src/lib/steps/install-plugin.spec.ts for inspiration. WordPress currently isn’t loaded in these blueprint tests so you may need to mock $wpdb. To run the tests, you’d do nx test playground-blueprints or nx test playground-blueprints:vite --watch.

https://github.com/WordPress/wordpress-playground/pull/745/files#diff-a760bde1f650fd8be213a81d7ce7c07e8ce79bceefdc1439bbe63b48eae591f4R49

[seanmorris]

• This could be as simple as "click this localhost:5400/#{"steps": [... link and confirm the site title says potato" or "take the first usage example above, go to localhost:5400/, paste it after #, confirm X happened".

@adamziel I JUST realized what you meant by this. I forgot that you could just spin up playground and supply a blueprint on the query hash.

I added that to the description.

[adamziel]

Looks good! Would you please resolve the merge conflicts? Then, once the CI runs and all the checks are green, we can merge!

[seanmorris]

Looks good! Would you please resolve the merge conflicts? Then, once the CI runs and all the checks are green, we can merge!

@adamziel @dmsnell

https://github.com/WordPress/wordpress-playground/actions/runs/7091739719/job/19301742699

[adamziel]

🚢